LibEngsas
Public Types | Public Slots | Signals | Public Member Functions | Protected Member Functions | Private Slots | Private Member Functions | Private Attributes | List of all members
ESqlInit Class Reference

Class to manage database structures.This class is able to create and modify complexe database structures. You can define a structure in scheme() and this class handles the creation of this structure or updates an existing one automatically. To allow more customization, you can register update routines, to get a more customized post processsing of updates. More...

#include <esqlinit.h>

+ Inheritance diagram for ESqlInit:
+ Collaboration diagram for ESqlInit:

Public Types

enum  privileges {
  SELECT, INSERT, UPDATE, DEL,
  CREATE, ALTER
}
enum  Status {
  BadSettings, LoggedIn, LoginFailed, UpdateNeeded,
  UpdateFailed, NoUpdateNeeded
}

Public Slots

void reloadSettings ()
- Public Slots inherited from EObject
virtual void reloadSettings ()
 Used to reload the settings.

Signals

void actualStep (QString msg)
 Set the text above the upper progress bar to msg.
void finishedStep ()
 Increases the value of the progress bar by 1.
void neededSteps (int num)
 Sets the maximum of the progress bar to num.
- Signals inherited from EObject
void error (const QString &message)
void warning (const QString &message)
void information (const QString &message)
void reloadEnableActions ()
 Request reloading of enabled actions in EMainWindow.
void addMenu (QMenu *newMenu, const QString &parent, QString before=QString())
void addAction (QAction *newAction, const QString &parent, QString before=QString())
void addToolBar (QToolBar *newToolBar, Qt::ToolBarArea area=Qt::TopToolBarArea)
void addNewDockWidget (QDockWidget *widget, const Qt::DockWidgetArea &area)
void setCentralWidget (QWidget *centralWidget)
void showSettings ()
void showHelp (const QString &page)
void showStatusWidget (QWidget *widget)
void reloadSettingsRequest ()
 Indicates, that a reload of the settings is needed.
void doReloadSettings ()
 Emitted to bring the reload request back to the farest child.

Public Member Functions

 ESqlInit (QObject *parent=0, QString username=QString(), QString host=QString(), QString database=QString(), QString driver=QString(), QString password=QString())
virtual ~ESqlInit ()
ESqlInit::Status login (bool loginOnly=true, bool runUpdate=false)
 Logs in and after logging it's check the structure of the database against the given one at the scheme() function.
ESqlInit::Status loginGuiless (bool loginOnly=true, bool runUpdate=false)
QString label () const
 Returns the label set with setup().
int schemaVersion () const
 Returns the schema version set with setup().
QString databaseName () const
 Returns the database name, currently managed.
void addInformation (QString msg)
 Emits the signal information() with content msg.
- Public Member Functions inherited from EObject
 EObject (QObject *parent=0)
virtual ~EObject ()
void connectByPass (QObject *object)

Protected Member Functions

virtual void scheme ()=0
 Stores the database scheme.
void addUpdateRoutine (int toVersion, bool(*functionPointer)(ESqlInit *, QList< ESqlTable * >, QString &))
 Registers the update routine.
ESqlTableaddTable (QString name, bool appendFieldId=true, bool addPrefix=true)
 Adds a new table to the list of tables.
void addView (QString name, QString selectStatement, bool addPrefix=true)
 Adds a view to the list of views.
void setup (QString name, QString label, int version)
 Setup the needed meta data of this module.
- Protected Member Functions inherited from EObject
void addManagedDockWidget (QDockWidget *widget, const Qt::DockWidgetArea &area, QString actionLabel=QString(), QString actionParent=QString())
 Adds an dock widget via addNewDockWidget() and adds widget to the list of managed dock widgets.

Private Slots

bool updateDb ()

Private Member Functions

ESqlInit::Status login (bool loginOnly, bool runUpdate, bool enableGui)
bool updateNeeded ()
bool doUpdate ()
bool compareTables (ESqlTable *table, QString &errorString, bool create=false)
bool compareViews (QStringList view, QString &errorString, bool create=false)
QString createViewStatement (QStringList view)
bool runUpdateRoutines (int fromVersion, QString &errorString, int toVersion)
 Runs all needed and registered update routines.
void init ()
 Initializes the structure by calling scheme().

Private Attributes

QString dbName
QString versionTable
bool transactions
bool gui
EngSaS::SQL::DatabaseType dbType
QList< ESqlInit::privilegesneededPrivs
int actVersion
QString username
QString password
QString host
QString driver
ESqlDatabase db
int currentVersion
QString thisName
QString moduleLabel
QList< ESqlTable * > tables
QList< QStringList > views
QMap< int, bool(*)(ESqlInit
*, QList< ESqlTable * >
, QString &)> 
updateRoutines

Additional Inherited Members

- Static Public Member Functions inherited from EObject
static void connectByPass (QObject *parent, QObject *child)
- Protected Slots inherited from EObject
virtual void errorByPass (const QString &message)
virtual void warningByPass (const QString &message)
virtual void informationByPass (const QString &message)
virtual void reloadEnableActionsByPass ()
virtual void addMenuByPass (QMenu *newMenu, const QString &parent, QString before=QString())
virtual void addActionByPass (QAction *newAction, const QString &parent, QString before=QString())
virtual void addToolBarByPass (QToolBar *newToolBar, Qt::ToolBarArea area=Qt::TopToolBarArea)
virtual void addNewDockWidgetByPass (QDockWidget *widget, const Qt::DockWidgetArea &area)
virtual void setCentralWidgetByPass (QWidget *centralWidget)
virtual void showSettingsByPass ()
virtual void showHelpByPass (const QString &page)
virtual void showStatusWidgetByPass (QWidget *widget)
virtual void reloadSettingsRequestByPass ()

Detailed Description

Class to manage database structures.

This class is able to create and modify complexe database structures. You can define a structure in scheme() and this class handles the creation of this structure or updates an existing one automatically. To allow more customization, you can register update routines, to get a more customized post processsing of updates.

Note
This class doesn't delete any table automatically. This is for data security at the database. Normally data moving must be done before deleting a table. You can do this with help of the mentioned update routines and also delete the table within this routine.

To use this class, subclass it and implement scheme(). There you should setup the needed meta data by calling setup(). Afterwards, you can use addTable() to add tables. At last you can use addUpdateRoutine() to add some custom post update processing.

Here is an example scheme function:

void Example:scheme() {
setup("example", "Example Human Name", 9);
// add a table with standard id field
// the table will be called "example_users",
// because the name set by setup is "example".
ESqlTable *users = addTable ( "users" );
// add a second field
field = users->appendField ( "name", ESqlField::Varchar, true );
field->setLength ( 45 );
users->addIndex ( field );
// ad a theird field
field = users->appendField ( "givenName", ESqlField::Varchar );
field->setLength ( 45 );
// add an update routine from version < 6 to version = 6:
addUpdateRoutine(6, &Example::updateFrom5To6);
}
See Also
ESqlTable
ESqlField
Todo:

error message when inserting of vaules have failed

check needed rights and ask for username and password with extended rights, if they are needed for example things like create tables, ...

Member Enumeration Documentation

possible SQL permissions CREATE assumes ALTER and CREATE VIEW

Enumerator:
SELECT 
INSERT 
UPDATE 
DEL 
CREATE 
ALTER 
Enumerator:
BadSettings 
LoggedIn 
LoginFailed 
UpdateNeeded 
UpdateFailed 
NoUpdateNeeded 

Constructor & Destructor Documentation

ESqlInit::ESqlInit ( QObject *  parent = 0,
QString  username = QString(),
QString  host = QString(),
QString  database = QString(),
QString  driver = QString(),
QString  password = QString() 
)
ESqlInit::~ESqlInit ( )
virtual

Member Function Documentation

void ESqlInit::actualStep ( QString  msg)
signal

Set the text above the upper progress bar to msg.

+ Here is the caller graph for this function:

void ESqlInit::addInformation ( QString  msg)

Emits the signal information() with content msg.

Use this function to add information messages to the log in your updateRoutines.

+ Here is the call graph for this function:

ESqlTable * ESqlInit::addTable ( QString  name,
bool  appendFieldId = true,
bool  addPrefix = true 
)
protected

Adds a new table to the list of tables.

The added table will be named name with prefix of the name set by setup() (if addPrefix is true) and gets an id field, if appendFieldId is true (Default).

Returns
Pointer to the ESqlTable object, which represents the newly added table .

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void ESqlInit::addUpdateRoutine ( int  toVersion,
bool(*)(ESqlInit *, QList< ESqlTable * >, QString &)  functionPointer 
)
protected

Registers the update routine.

static bool Example::updateFrom3To4 (ESqlInit *caller, QList< ESqlTable* > tables, QString& errorString )
{
Q_UNUSED(tables);
caller->addInformation(tr("Your log message"));
// 1. delete useless table userhasmaterials
QSqlQuery query;
if(!query.exec(QString("DROP TABLE %1_userhasmaterials").arg(caller->label())){
errorString.append ( query.lastError().text() );
return false;
}
return true;
}
addUpdateRoutine(4, &Example::updateFrom3To4);
}

In the update routine, you can access the label set with setup() with help of caller->label(). To get the database name, which is used by current connection, use caller->databaseName(). If you want to add a message to the logs, use caller->addInformation().

Parameters
toVersionVersion which is reached, after the updateroutine is run
Note
The updateroutine functionPointer should handle a QString& to give back error messages
and it get's a pointer to the calling ESqlInit object.
See Also
label()
databaseName()
addInformation()
void ESqlInit::addView ( QString  name,
QString  selectStatement,
bool  addPrefix = true 
)
protected

Adds a view to the list of views.

The added view will be named name with prefix of the name set by setup() (if addPrefix is true). The view itself is defined with help of a select statement, which is the second parameter selectStatement.

bool ESqlInit::compareTables ( ESqlTable table,
QString &  errorString,
bool  create = false 
)
private

compares to tables in mode create = false it returns true if both tables are identical and false if not if update is set to true, it updates the table or even create it.

Note
Fields are not deleted here, to give you the chance to do something with the data, which is in the deleted fields. Therefore, you must delete fields in an updateRoutine. Also default values are not touched, if fields are deleted to avoid errors (because fields are not deleted, but default values needs the new structure).

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

bool ESqlInit::compareViews ( QStringList  view,
QString &  errorString,
bool  create = false 
)
private

checks, if view with current statement exists

Parameters
viewthe view which a create statement should be created
errora pointer to a QString where the error message is appended
createcreate view if it not exist or with other select statement
Returns
true if view already exists and is the same as needed
Todo:
Because, checking is quite complicated, the views are dropped and created again, this should be improved!

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

QString ESqlInit::createViewStatement ( QStringList  view)
private

create views statement

Parameters
viewindex of view at QList views;
Returns
SQL query to create view

+ Here is the caller graph for this function:

QString ESqlInit::databaseName ( ) const

Returns the database name, currently managed.

bool ESqlInit::doUpdate ( )
private

does the update

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void ESqlInit::finishedStep ( )
signal

Increases the value of the progress bar by 1.

+ Here is the caller graph for this function:

void ESqlInit::init ( )
private

Initializes the structure by calling scheme().

It allso adds the standard table "dbmoduleversions" as first table.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

QString ESqlInit::label ( ) const

Returns the label set with setup().

This string is used as a prefix for all tables of this module.

+ Here is the caller graph for this function:

ESqlInit::Status ESqlInit::login ( bool  loginOnly = true,
bool  runUpdate = false 
)

Logs in and after logging it's check the structure of the database against the given one at the scheme() function.

For convenience, this function enables GUI automatically, if QApplication is available. If only QCoreApplication is available, GUI is disabled automatically.

Parameters
runUpdateis set to false login returns true if an update is needed
runUpdateis set to true, login runs the update and return true if the updates are done successfull

+ Here is the caller graph for this function:

ESqlInit::Status ESqlInit::login ( bool  loginOnly,
bool  runUpdate,
bool  enableGui 
)
private

The internal login function

+ Here is the call graph for this function:

ESqlInit::Status ESqlInit::loginGuiless ( bool  loginOnly = true,
bool  runUpdate = false 
)

+ Here is the call graph for this function:

void ESqlInit::neededSteps ( int  num)
signal

Sets the maximum of the progress bar to num.

+ Here is the caller graph for this function:

void ESqlInit::reloadSettings ( )
slot

+ Here is the call graph for this function:

bool ESqlInit::runUpdateRoutines ( int  fromVersion,
QString &  errorString,
int  toVersion 
)
private

Runs all needed and registered update routines.

It runs all registered update routines, which are needed to reach toVersion from fromVersion. If an error occurs, errorString is filled and false is returned.

To register an update routine, call addUpdateRoutine().

Note
All tables are updated automatically, but some operations, like convert data to a new structure, can not be done automatically. In this case, you should register an updaet routine.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int ESqlInit::schemaVersion ( ) const

Returns the schema version set with setup().

virtual void ESqlInit::scheme ( )
protectedpure virtual

Stores the database scheme.

+ Here is the caller graph for this function:

void ESqlInit::setup ( QString  name,
QString  label,
int  version 
)
protected

Setup the needed meta data of this module.

The chosen name is used as a prefix for some tables and also an entry in the dbmodulesversion is done with this name. This entry contains also label and version.

+ Here is the call graph for this function:

bool ESqlInit::updateDb ( )
privateslot

initializes the update

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

bool ESqlInit::updateNeeded ( )
private

checks wether update of the structure is needed or not it also checks wether structure is newer than needed which might be bad too

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

Member Data Documentation

int ESqlInit::actVersion
private
int ESqlInit::currentVersion
private

current version of db structure

ESqlDatabase ESqlInit::db
private
QString ESqlInit::dbName
private
EngSaS::SQL::DatabaseType ESqlInit::dbType
private
QString ESqlInit::driver
private
bool ESqlInit::gui
private
QString ESqlInit::host
private
QString ESqlInit::moduleLabel
private
QList<ESqlInit::privileges> ESqlInit::neededPrivs
private
QString ESqlInit::password
private
QList<ESqlTable*> ESqlInit::tables
private

a list of all tables of the database which are needed by this module

QString ESqlInit::thisName
private

prefix of all tables which belongs to this module

bool ESqlInit::transactions
private
QMap<int, bool (*)(ESqlInit *, QList<ESqlTable*>, QString&)> ESqlInit::updateRoutines
private

the first int (QMap-Key) is the result version, which is reached, if updateFunction runs successfully. updateFunction should than return true

See Also
DBInit for examples
QString ESqlInit::username
private
QString ESqlInit::versionTable
private
QList<QStringList> ESqlInit::views
private

The documentation for this class was generated from the following files: