de.esprit.appsuite.database.dbase

## Class DBObject

- java.lang.Object
- - de.esprit.common.util.DumpableObject
  - - de.esprit.common.util.TransferableObject
    - - de.esprit.appsuite.database.dbase.DBObject

- All Implemented Interfaces:
    DBPersistent, DBRecord, Renderable, DeepCloneable, Dumpable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable
  Direct Known Subclasses:
    DBO_esprit_group, DBO_esprit_user, DBO_esprit_userlist_view, DBO_insert_def, DBO_tnt_alltype, DBO_tnt_logmsg, DBO_tnt_nopk, DBO_tnt_persistent_type, DBO_tnt_pk_composed, DBO_tnt_pktype, DBO_tnt_route, DBO_tnt_route_vertex, DBO_tnt_stdtype, DBO_tnt_tank

      public abstract class DBObject
      extends TransferableObject
      implements DBRecord

  This is the abstract base class for modeling records of a database table as Java Objects. Records of a particular table are represented by the corresponding 'DBO_tablename' subclasses. DBObjects handle SELECTs, INSERTs, UPDATEs and DELETEs internally - totally removing the need of SQL statements. Furthermore - as they use prepared statements in most cases - they provide very fast queries and updates.

  #### DBObject subclasses

  Real database records are modeled by subclasses of this abstract superclass. Such subclasses can be created with the DBObject Compiler. There is one concrete DBObject subclass per database table or view.

  #### Database connection

  Prior to using DBObjects you must establish a database connection by providing a `DataSource` object. You may either instantiate a `DBConnectionPool` object and set it with `setDataSource(DataSource)` or you call one of the `connect(Credential)` methods, which creates an internal connection pool for you.

  #### Thread safety

  The DBObject class is thread safe in a manner, that never two threads will perform an action on the same database connection at the same time. The thread safety is guaranteed by the internal connection pool which grants exclusive access to only one single thread per connection at a time.

  #### Transaction support

  A thread who calls the static DBObject method `begin()` starts a database transaction. Every method call done by this thread in the same or any other DBObject will then happen in a transaction until either `commit()` or `rollback()` is called. The internal connection pool ensures that the same thread always gets the same connection he is working on until he has finished the transaction. Many threads may run transactions at the same time - as many as you have got connections in the pool.

  Note that nested transactions are supported. Thus begin() may be called n times by the same thread, each call increasing the nesting level. Accordingly commit() must be called n times decreasing the nesting level again. If nesting level 0 is reached by a commit() call then the database COMMIT is actually performed. A rollback() call at any nesting level will immediately break the transaction and fall back to nesting level 0.

  Note: because the transaction mechanism described above is provided by the `DBConnectionPool` class it only will work if the DataSource actually is an instance of that class. If your DataSource however is provided i.e. by your J2EE environment you must instead use the transaction monitor of that environment.

  #### Error reporting

  The DBObject class has got an internal `LogSupport` which reports details of database operations (full dump of record) to the system console. Typically your `ApplicationContext` is set as the current logger. The default logger is `AppUtil.getDefaultContext()`. You may create your own error handler by providing a class that implements the ``LogSupport`` interface and install it with the `setErrorLogger(LogSupport)` method.
  Author:
    Rainer Buesch
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BOOLEAN_CHAR`
    `static java.lang.String` | `DBO_PREFIX`
    `static java.lang.String` | `FALSE_STR`
    `static java.lang.String` | `TRUE_STR`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DBObject()` Note that only the subclasses can provide actual useful Constructors.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addRecordChangeListener(RecordChangeEvent.Listener l)` You may register for record changes here.
    `static void` | `addSqlListener(SqlEvent.Listener l)` You may register for SQL statements here.
    `static int` | `begin()` Starts a transaction on the current connection.
    `static int` | `begin(int txIsolationLevel)` Same as begin() but allows for setting the isolation level to any of Connection.TRANSACTION_*.
    `static boolean` | `checkSubclassVersion(java.lang.Class subClass, java.lang.String subClassVersion)`
    `void` | `clearAttributes()` Clears all member variables of this dbobject except the primary key values.
    `void` | `clearPrimaryKey()` Clears all primary key variables of this DBObject.
    `static void` | `clearStatementCache()` Clears the statement cache and thus forgets about all cached prepared statements.
    `void` | `clearValues()` Clears all member variables of this dbobject including the primary key values.
    `DBObject` | `clone()`
    `static void` | `close()` Closes the underlying connection-pool using an immediate shutdown.
    `static void` | `close(int shutDownDelay)` Closes the underlying connection-pool using a friendly shutdown.
    `static void` | `commit()` Commits the current transaction and finalizes the changes in the database.
    `int` | `compareTo(java.lang.Object o)` Implementation of Comparable interface.
    `static DBConnectionPool` | `connect(Credential cred)` Tries to create the database connection with the given credential information.
    `static void` | `connect(DatabaseCommandLineParser clp)` Tries to create the database connection by reading the credential information from the command line.
    `static void` | `connect(java.lang.String jdbcDriver, java.lang.String dbUrl, java.lang.String dbUser, java.lang.String dbPasswd, java.lang.String dbSchema, int minConns, int maxConns)` Tries to create the database connection with the given JDBC driver name and the given connection URL.
    `static java.lang.Object` | `convertArray(java.lang.Class newArrayClass, java.lang.Object sourceArray)` Converts the sourceArray to an array of type arrayClass so that the resultArray is castable to arrayClass.
    `void` | `copyRecordValues(DBRecord otherRecord, boolean isIncludePK)` Copies all values of an other record of the same type to this one.
    `protected java.lang.String` | `createDumpHeader()`
    `protected abstract DBRecord` | `createInstance()`
    `static DBObject` | `createInstance(java.lang.Class dboClass)` Creates an empty instance of the given DBObject type.
    `static DBObject` | `createInstance(java.lang.Class dboClass, java.lang.String... primaryKeys)` Creates an instance of the given DBObject type for the given primary key.
    `protected abstract DBRecord` | `createInstance(java.lang.String... primaryKeys)`
    `int` | `dbCountRecords()` Counts the number of records in the table by issuing a `select count(*) from ...`
    `int` | `dbCountRecords(SqlCondition cond)` Counts the number of records in the table by issuing a `select count(*) from ...`
    `void` | `dbCreateForeignKeyConstraints()` This call adds all foreign key constraints to a table.
    `void` | `dbCreateTable()` Creates the underlying table in the database if it does not exist yet.
    `void` | `dbDelete()` Deletes the record from the underlying database table using a prepared DELETE statement.
    `int` | `dbDelete(SqlCondition condition)` Performs a conditional deletion of all DBObjects of the given type, that match the given condition.
    `void` | `dbDropTable()` Removes the underlying table from the database.
    `void` | `dbExists()` Checks whether this DBObject exists as a record in the underlying database table by performing a high performant index only SELECT.
    `boolean` | `dbExistsTable()` Checks the existence of the underlying table in the database.
    `void` | `dbForceInsert()` Performs a forced insert of the DBObject.
    `void` | `dbForceUpdate()` Performs a forced update of the DBObject.
    `protected java.sql.Blob` | `dbGetBlob(java.sql.ResultSet rs, int index)`
    `protected boolean` | `dbGetBoolean(java.sql.ResultSet rs, int index)`
    `protected java.lang.Boolean` | `dbGetBooleanFromChar(java.sql.ResultSet rs, int index)`
    `protected java.sql.Clob` | `dbGetClob(java.sql.ResultSet rs, int index)`
    `protected java.sql.Date` | `dbGetDate(java.sql.ResultSet rs, int index)`
    `protected double` | `dbGetDouble(java.sql.ResultSet rs, int index)`
    `protected float` | `dbGetFloat(java.sql.ResultSet rs, int index)`
    `protected int` | `dbGetInt(java.sql.ResultSet rs, int index)`
    `protected long` | `dbGetLong(java.sql.ResultSet rs, int index)`
    `protected java.lang.String` | `dbGetString(java.sql.ResultSet rs, int index)`
    `protected java.sql.Time` | `dbGetTime(java.sql.ResultSet rs, int index)`
    `protected java.sql.Timestamp` | `dbGetTimestamp(java.sql.ResultSet rs, int index)`
    `void` | `dbInsert()` Inserts a record into the underlying database table using a prepared INSERT statement.
    `void` | `dbLoad(DBLoadMonitor monitor)` Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`.
    `void` | `dbLoad(DBLoadMonitor monitor, SqlCondition condition)` Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`.
    `void` | `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)` Loads records according to the given condition and order.
    `void` | `dbLoad(DBLoadMonitor monitor, SqlOrder order)` Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`.
    `void` | `dbRehash()` Re-reads the current DBObject from the database using a prepared SELECT statement.
    `void` | `dbSearch(DBLoadMonitor monitor, SqlCondition condition)` Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition)`.
    `void` | `dbSearch(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)` Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`.
    `DBRecord[]` | `dbSearch(SqlCondition condition)` Same as `dbSelect(SqlCondition condition)`.
    `DBRecord[]` | `dbSearch(SqlCondition condition, SqlOrder order)` Same as `dbSelect(SqlCondition condition, SqlOrder order)`.
    `DBRecord[]` | `dbSelect()` Reads all records of the underlying table without any condition, ordered by primary key.
    `DBRecord[]` | `dbSelect(SqlCondition condition)` Reads all records that match the given condition, ordered by primary key.
    `DBRecord[]` | `dbSelect(SqlCondition condition, SqlOrder order)` Reads all records that match the given condition, ordered by the given order clause.
    `DBRecord[]` | `dbSelect(SqlOrder order)` Reads all records of the table ordered by the given order.
    `protected void` | `dbSetBlob(java.sql.PreparedStatement ps, int index, java.sql.Blob blob, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetBlob(java.sql.PreparedStatement ps, int index, java.sql.Blob blob, DumpString ds, java.lang.String fieldName)`
    `protected void` | `dbSetBoolean(java.sql.PreparedStatement ps, int index, boolean value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetBooleanAsChar(java.sql.PreparedStatement ps, int index, java.lang.Boolean value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetClob(java.sql.PreparedStatement ps, int index, java.sql.Clob clob, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetClob(java.sql.PreparedStatement ps, int index, java.sql.Clob clob, DumpString ds, java.lang.String fieldName)`
    `protected void` | `dbSetDate(java.sql.PreparedStatement ps, int index, java.sql.Date value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetDouble(java.sql.PreparedStatement ps, int index, double value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetFloat(java.sql.PreparedStatement ps, int index, float value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetInt(java.sql.PreparedStatement ps, int index, int value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetLong(java.sql.PreparedStatement ps, int index, long value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetPersistentId(java.sql.PreparedStatement ps, int index, PersistentId value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetPersistentName(java.sql.PreparedStatement ps, int index, PersistentName value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetPK(java.sql.PreparedStatement ps, int index, java.lang.String valueStr, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetString(java.sql.PreparedStatement ps, int index, java.lang.String value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetTime(java.sql.PreparedStatement ps, int index, java.sql.Time value, DumpString ds, DBColumnKey col)`
    `protected void` | `dbSetTimestamp(java.sql.PreparedStatement ps, int index, java.sql.Timestamp value, DumpString ds, DBColumnKey col)`
    `void` | `dbUpdate()` Updates the record in the underlying database table using a prepared UPDATE statement.
    `static void` | `dumpStatementCache(java.io.PrintStream ps)` Dumps the content of the statement cache to the given stream for debugging.
    `boolean` | `equalAttributes(java.lang.Object o)` Compares two DBObject's by comparing their attribute values.
    `boolean` | `equalPrimaryKeys(java.lang.Object o)` Compares two DBObject's by comparing their primary key values.
    `boolean` | `equals(java.lang.Object o)` Compares two DBObject's by comparing their primary key values.
    `static java.sql.ResultSet` | `executeQuery(java.lang.String sql)` Executes the given statement in the Database and returns a ResultSet with the matching records.
    `static int` | `executeSQL(java.lang.String sql)` Executes the given statement in the Database and returns the number of records affected
    `boolean` | `exists()` Same as `dbExists()` just any Exception that may have been thrown is caught away.
    `boolean` | `existsField(java.lang.String fieldName)` Tells whether this field name exists in this DBObject
    `boolean` | `forceInsert()` Performs a forced insert of the DBObject.
    `boolean` | `forceUpdate()` Performs a forced update of the DBObject.
    `DBColumnKey[]` | `getAllColumns()` Returns an array of all column definitions
    `abstract DBColumnKey[]` | `getAttributeColumns()` Returns the attribute column definitions from the concrete subclass
    `int` | `getAttributeCount()` Returns the number of attribute fields
    `java.lang.String[]` | `getAttributeFullNames()` Returns the names of the attribute columns in the format table.column
    `java.lang.String[]` | `getAttributeNames()` Returns the names of the attribute columns
    `java.lang.Object[]` | `getAttributeValues()` Returns the current values of the attribute columns
    `static javax.sql.DataSource` | `getDataSource()` Returns the underlying connection-pool object.
    `static int` | `getDecimalRoundingDigits()` Returns the current decimal rounding digits.
    `static java.math.RoundingMode` | `getDecimalRoundingMode()` Returns the current decimal rounding mode.
    `static LogSupport` | `getErrorLogger()`
    `DBColumnKey` | `getFieldByIndex(int index)` Accesses a field definition by index
    `DBColumnKey` | `getFieldByName(java.lang.String fieldName)` Fetches the field definition by name.
    `int` | `getFieldCount()` Returns the total number of fields (primary keys plus attribute fields)
    `protected java.lang.String` | `getFieldDefinition(java.lang.String fieldName)` Returns the column definition string as used in CREATE TABLE.
    `java.lang.String[]` | `getFieldFullNames()` Returns the names of all database fields in the format table.column.
    `java.lang.String` | `getFieldIcon(java.lang.String fieldName)` Returns a name for an icon if the field is a primary key field, null otherwise.
    `int` | `getFieldLength(java.lang.String fieldName)` Returns the length (in number or characters) of the given fieldname.
    `java.lang.String[]` | `getFieldNames()` Returns the pure column-names of all database fields not containing the tablename.
    `java.lang.String` | `getForeignKeyGroup(java.lang.String columnName)` Returns the group name of a particular foreign key column
    `java.lang.String[]` | `getForeignKeyGroups()` Returns an array of the available oreign key groups, if any.
    `java.lang.String` | `getForeignKeyRef(java.lang.String columnName)` Returns the reference of a foreign key column in the format table.column
    `int` | `getIndexOf(java.lang.String fieldName)` Returns the index of the given fieldname
    `static InsertFactory` | `getInsertFactory()` Returns the current `InsertFactory` if any (may be null).
    `java.lang.Class` | `getJavaType(java.lang.String fieldName)` Returns the java variable type of the given fieldname.
    `int` | `getJdbcType(java.lang.String fieldName)` Returns the jdbc-type of the given fieldname.
    `DBObject[]` | `getManagedDBObjects()` Returns always the identity reference.
    `abstract DBRecord` | `getMasterRecord()`
    `static DBRecord` | `getMasterRecord(java.lang.Class clazz)` Returns a cached DBObject instance of the given subclass.
    `abstract DBColumnKey[]` | `getPrimaryKeyColumns()` Returns the primary key column definition from the concrete subclass
    `int` | `getPrimaryKeyCount()` Returns the number of primary key fields
    `static PrimaryKeyFactory` | `getPrimaryKeyFactory()` Tells which PrimaryKeyFactory is currently in use (may be null).
    `java.lang.String[]` | `getPrimaryKeyFullNames()` Returns the names of the primary key columns in the format table.column
    `java.lang.String[]` | `getPrimaryKeyNames()` Returns the names of the primary key columns
    `SqlOrder` | `getPrimaryKeyOrder()` Returns the ORDER clause for ordering by primary key, or null if no primary key exists.
    `java.lang.String[]` | `getPrimaryKeyValues()` Returns the values of the primary key columns
    `static RdbmsInfo` | `getRdbmsInfo()` Returns an RdbmsInfo object which caches the most frequently used database meta data of the current connection.
    `static RdbmsSupport` | `getRdbmsSupport()` Returns an RDBMS specific RdbmsSupport object which encapsulates the particularities of the RDBMS system we currently are connected to.
    `java.lang.String` | `getRecordName()` Returns the name of the underlying database table on a DBObject.
    `java.awt.Color` | `getRenderColor()`
    `javax.swing.Icon` | `getRenderIcon()`
    `java.lang.String` | `getRenderText()` Returns a String that that represents this object in a GUI component.
    `static java.lang.String` | `getSchema()` Returns the current schema name if any.
    `abstract java.lang.String` | `getTableName()` Returns the name of the underlying database table
    `java.lang.Object` | `getValue(DBColumnKey columnKey)` Returns the current value of the given fieldname
    `java.lang.Object` | `getValue(java.lang.String fieldName)` Returns the current value of the given fieldname
    `java.lang.Object[]` | `getValues()` Returns the values of all database fields as an array
    `static AppSuiteVersion` | `getVersion()` The version of the DBObject Suite package that created the DBObject subclasses.
    `static boolean` | `hasConnection()` Tells whether the DBObject class has got an underlying ConnectionPool set.
    `int` | `hashCode()` Overridden to return a class specific hash-code.
    `boolean` | `hasPrimaryKey()` Tells whether this DBObject has got a Primary Key defined in the database
    `void` | `invalidate()` Sets the valid flag of this DBObject to false.
    `static boolean` | `isDecimalRounding()` Tells if decimal rounding is active.
    `boolean` | `isDirty()` Returns false if this object is known to be consistent with the database.
    `boolean` | `isFieldNumeric(java.lang.String fieldName)`
    `boolean` | `isFieldVirtual(java.lang.String fieldName)` Returns always false.
    `boolean` | `isForeignKey(java.lang.String fieldName)` Tells whether the given field is a foreign key field
    `boolean` | `isNotNullField(java.lang.String fieldName)` Tells wasCancelled this field is a not null field.
    `boolean` | `isPrimaryKey(java.lang.String fieldName)` Tells whether the given field is a primary key field
    `boolean` | `isPrimaryKeyValid()` Tells whether this DBObject has a valid primary key.
    `boolean` | `isPrimaryKeyValid(java.lang.String... pkValues)` Checks whether the given pkValues array is a valid primary key for this DBObject.
    `boolean` | `isReadPrimaryKeyOnly()` Tells whether only primary keys are read from the database.
    `static boolean` | `isSilent()` Tells whether DBObjects should do logging
    `static boolean` | `isStoreZeroAsNull()` Tells whether numeric zero values should be written as null.
    `static boolean` | `isTrimStringsOnRead()` Tells whether Strings are trimmed when they are read from the database By default strings are trimmed.
    `static boolean` | `isTrimStringsOnWrite()` Tells whether Strings are trimmed when they are written to the database.
    `protected abstract void` | `readAttributes(DBObject obj, int idx, java.sql.ResultSet rs)`
    `protected DBObject` | `readObject(DBObject dbo, int pkValue)`
    `protected DBObject` | `readObject(DBObject dbo, java.lang.String... pkValues)`
    `protected abstract void` | `readPrimaryKeys(DBObject obj, int idx, java.sql.ResultSet rs)`
    `static void` | `removeRecordChangeListener(RecordChangeEvent.Listener l)`
    `static void` | `removeSqlListener(SqlEvent.Listener l)`
    `static boolean` | `rollback()` Rolls back the last transaction started.
    `static double` | `roundValue(double value)` Rounds a double value according to the current decimal RoundingMode.
    `static float` | `roundValue(float value)` Rounds a float value according to the current decimal RoundingMode.
    `static void` | `setDataSource(javax.sql.DataSource conPool)` Sets the ConnectionPool to be used for accessing the JDBC database connection.
    `static void` | `setDecimalRounding(java.math.RoundingMode mode, int digits)` Sets the decimal rounding mode and the rounding digits.
    `static void` | `setErrorLogger(LogSupport logger)` Set a custom `LogSupport` which reports DBObject activity.
    `void` | `setFieldValue(java.lang.String fieldName, java.lang.Object value)` Sets the value of the instance variable which represents the database column fieldName
    `void` | `setFieldValue(java.lang.String fieldName, java.lang.String valueStr)` Sets the value of the instance variable which represents the database column fieldName .
    `static InsertFactory` | `setInsertFactory(InsertFactory factory)` Sets the InsertFactory to be used for record INSERTs.
    `static void` | `setPrimaryKeyFactory(PrimaryKeyFactory factory)` Sets the PrimaryKeyFactory to be used for record INSERTs.
    `void` | `setPrimaryKeyValues(java.lang.String... pkValues)` Sets the values of the primary key columns
    `void` | `setReadPrimaryKeyOnly(boolean readPKOnly)` Enforces that only primary key values are read from the database when performing a dbSelect() or dbSearch() call.
    `static void` | `setSchema(java.lang.String schema)` This allows for setting a schema name that will used as a tablename prefix when accessing the underlying database table.
    `static void` | `setSilent(boolean silent)` Turns logging on or off without changing the ErrorLogger.
    `static void` | `setStoreZeroAsNull(boolean storeAsNull)` This is a global switch that enforces storage of numeric zero values as null values in numeric fields.
    `static void` | `setTrimStringsOnRead(boolean doTrim)` Enforces Strings to be trimmed when they are read from the database
    `static void` | `setTrimStringsOnWrite(boolean doTrim)` Enforces Strings to be trimmed when they are written to the database
    `DumpString` | `toDumpString(DumpString s)` Fills the given DumpString with debugging information about this DBObject.
    `static java.lang.String` | `toKey(java.lang.String key)`
    `static java.lang.String` | `toKey(java.lang.String[] keys)`
    `protected java.lang.Object` | `toObject(boolean value)`
    `protected java.lang.Object` | `toObject(double value)`
    `protected java.lang.Object` | `toObject(float value)`
    `protected java.lang.Object` | `toObject(int value)`
    `protected java.lang.Object` | `toObject(long value)`
    `protected java.lang.Object` | `toObject(java.lang.Object value)`
    `ToString` | `toString(ToString s)` Returns a String representation of this DBObject which consists of the tablename and the primary key values
    `protected abstract void` | `writeAttributes(int idx, java.sql.PreparedStatement ps, DumpString ds)`
    `protected abstract void` | `writePrimaryKeys(int idx, java.sql.PreparedStatement ps, DumpString ds)`

    - ### Methods inherited from class de.esprit.common.util.TransferableObject

      `deepClone`

    - ### Methods inherited from class de.esprit.common.util.DumpableObject

      `configureDumpHeadlineLength, configureDumpMaxElementsPrinted, copyDumpStringValues, copyToStringValues, toDumpString, toString`

    - ### Methods inherited from class java.lang.Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface de.esprit.appsuite.database.dbase.DBRecord

      `getTranslationAppKey`

    - ### Methods inherited from interface de.esprit.common.type.DeepCloneable

      `deepClone`

    - ### Methods inherited from interface de.esprit.common.type.Dumpable

      `toDumpString, toString`

- - ### Field Detail

    - #### DBO_PREFIX

          public static final java.lang.String DBO_PREFIX

      See Also:
        Constant Field Values

    - #### TRUE_STR

          public static final java.lang.String TRUE_STR

      See Also:
        Constant Field Values

    - #### FALSE_STR

          public static final java.lang.String FALSE_STR

      See Also:
        Constant Field Values

    - #### BOOLEAN_CHAR

          public static final int BOOLEAN_CHAR

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DBObject

          protected DBObject()

      Note that only the subclasses can provide actual useful Constructors.

  - ### Method Detail

    - #### addRecordChangeListener

          public static void addRecordChangeListener(RecordChangeEvent.Listener l)

      You may register for record changes here. Only changes of DBObject instances are notified - no mass data operations like dbDelete(SqlCondition). Note: this method is supposed to be used for testing mainly.

    - #### removeRecordChangeListener

          public static void removeRecordChangeListener(RecordChangeEvent.Listener l)

    - #### addSqlListener

          public static void addSqlListener(SqlEvent.Listener l)

      You may register for SQL statements here. All executed SQL can be traced here.

    - #### removeSqlListener

          public static void removeSqlListener(SqlEvent.Listener l)

    - #### setInsertFactory

          public static InsertFactory setInsertFactory(InsertFactory factory)

      Sets the InsertFactory to be used for record INSERTs. If the factory is set then all DBObjects will ask this factory for INSERT default values for empty fields.

    - #### getInsertFactory

          public static InsertFactory getInsertFactory()

      Returns the current `InsertFactory` if any (may be null).

    - #### setPrimaryKeyFactory

          public static void setPrimaryKeyFactory(PrimaryKeyFactory factory)

      Sets the PrimaryKeyFactory to be used for record INSERTs. If the factory is not set then 'select max(...) from ...' statements are performed to determine new primary key values. Using a factory increases INSERT performance significantly.

    - #### getPrimaryKeyFactory

          public static PrimaryKeyFactory getPrimaryKeyFactory()

      Tells which PrimaryKeyFactory is currently in use (may be null).

    - #### setDataSource

          public static void setDataSource(javax.sql.DataSource conPool)

      Sets the ConnectionPool to be used for accessing the JDBC database connection.

    - #### getDataSource

          public static javax.sql.DataSource getDataSource()

      Returns the underlying connection-pool object.

    - #### hasConnection

          public static boolean hasConnection()

      Tells whether the DBObject class has got an underlying ConnectionPool set.

    - #### connect

          public static void connect(java.lang.String jdbcDriver,
                     java.lang.String dbUrl,
                     java.lang.String dbUser,
                     java.lang.String dbPasswd,
                     java.lang.String dbSchema,
                     int minConns,
                     int maxConns)
                              throws java.lang.Exception

      Tries to create the database connection with the given JDBC driver name and the given connection URL. Internally it creates a ConnectionPool with minConns database connections at startup and allows to increase connections on demand up to maxConns.
      Parameters:
        `jdbcDriver` - The fully qualified class name of the JDBC driver
        `dbUrl` - The database access URL
        `dbUser` - The name of the user
        `dbPasswd` - The password of the user
        `dbSchema` - The database schema (may be null)
        `minConns` - The number of connections that should initially be established
        `maxConns` - The max number of connections that can be established on demand
      Throws:
        `java.lang.Exception`

    - #### connect

          public static DBConnectionPool connect(Credential cred)
                                          throws java.lang.Exception

      Tries to create the database connection with the given credential information. Internally creates a ConnectionPool with one single connections.
      Throws:
        `java.lang.Exception`
      See Also:
        `DBConnectionPool`

    - #### connect

          public static void connect(DatabaseCommandLineParser clp)
                              throws java.lang.Exception

      Tries to create the database connection by reading the credential information from the command line. See `DatabaseCommandLineParser` to find out which command line options are evaluated for creating the database connection.
      Throws:
        `java.lang.Exception`
      See Also:
        `DatabaseCommandLineParser`, `DBConnectionPool`

    - #### close

          public static void close()

      Closes the underlying connection-pool using an immediate shutdown. No database access will be possible any more, unless you create and set a new ConnectionPool.
      See Also:
        `DBConnectionPool.close(int)`

    - #### close

          public static void close(int shutDownDelay)

      Closes the underlying connection-pool using a friendly shutdown. No database access will be possible any more, unless you create and set a new ConnectionPool.
      See Also:
        `DBConnectionPool.close(int)`

    - #### clearStatementCache

          public static void clearStatementCache()

      Clears the statement cache and thus forgets about all cached prepared statements. Any further db-access of any DBObject will need to recreate the according prepared statement.

    - #### dumpStatementCache

          public static void dumpStatementCache(java.io.PrintStream ps)

      Dumps the content of the statement cache to the given stream for debugging.

    - #### checkSubclassVersion

          public static boolean checkSubclassVersion(java.lang.Class subClass,
                                     java.lang.String subClassVersion)

    - #### getVersion

          public static AppSuiteVersion getVersion()

      The version of the DBObject Suite package that created the DBObject subclasses. Note that the version of the subclasses must match the version of this superclass. Otherwise the DBObject subclasses must be recreated.

    - #### getTableName

          public abstract java.lang.String getTableName()

      Returns the name of the underlying database table

    - #### getRecordName

          public java.lang.String getRecordName()

      Returns the name of the underlying database table on a DBObject. This name may differ on records that are composed of multiple DBObjects.
      Specified by:
        `getRecordName` in interface `DBPersistent`
      See Also:
        `getTableName()`, `ComposedRecord`

    - #### getRenderText

          public java.lang.String getRenderText()

      Returns a String that that represents this object in a GUI component. By default returns the tableName and the primary key values.
      Specified by:
        `getRenderText` in interface `Renderable`

    - #### getRenderIcon

          public javax.swing.Icon getRenderIcon()

      Specified by:
        `getRenderIcon` in interface `Renderable`

    - #### getRenderColor

          public java.awt.Color getRenderColor()

      Specified by:
        `getRenderColor` in interface `Renderable`

    - #### getPrimaryKeyNames

          public java.lang.String[] getPrimaryKeyNames()

      Returns the names of the primary key columns
      See Also:
        `getPrimaryKeyColumns()`

    - #### getPrimaryKeyFullNames

          public java.lang.String[] getPrimaryKeyFullNames()

      Returns the names of the primary key columns in the format table.column
      See Also:
        `getPrimaryKeyColumns()`

    - #### getPrimaryKeyColumns

          public abstract DBColumnKey[] getPrimaryKeyColumns()

      Returns the primary key column definition from the concrete subclass
      See Also:
        `getPrimaryKeyNames()`, `getPrimaryKeyFullNames()`, `getPrimaryKeyValues()`

    - #### setPrimaryKeyValues

          public void setPrimaryKeyValues(java.lang.String... pkValues)

      Sets the values of the primary key columns
      Specified by:
        `setPrimaryKeyValues` in interface `DBPersistent`
      See Also:
        `getPrimaryKeyValues()`

    - #### getPrimaryKeyValues

          public java.lang.String[] getPrimaryKeyValues()

      Returns the values of the primary key columns
      Specified by:
        `getPrimaryKeyValues` in interface `DBPersistent`
      See Also:
        `setPrimaryKeyValues(String...)`

    - #### getAttributeValues

          public java.lang.Object[] getAttributeValues()

      Returns the current values of the attribute columns
      Throws:
        `java.lang.Exception`
      See Also:
        `getAttributeColumns()`

    - #### getAttributeNames

          public java.lang.String[] getAttributeNames()

      Returns the names of the attribute columns
      See Also:
        `getAttributeColumns()`

    - #### getAttributeFullNames

          public java.lang.String[] getAttributeFullNames()

      Returns the names of the attribute columns in the format table.column
      See Also:
        `getAttributeColumns()`

    - #### getAttributeColumns

          public abstract DBColumnKey[] getAttributeColumns()

      Returns the attribute column definitions from the concrete subclass
      See Also:
        `getAttributeNames()`, `getAttributeFullNames()`, `getAttributeValues()`

    - #### getAllColumns

          public DBColumnKey[] getAllColumns()

      Returns an array of all column definitions

    - #### getJavaType

          public java.lang.Class getJavaType(java.lang.String fieldName)

      Description copied from interface: `DBRecord`
      Returns the java variable type of the given fieldname.
      Specified by:
        `getJavaType` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!

    - #### getJdbcType

          public int getJdbcType(java.lang.String fieldName)

      Description copied from interface: `DBRecord`
      Returns the jdbc-type of the given fieldname.
      Specified by:
        `getJdbcType` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!
      See Also:
        `Types`

    - #### getFieldLength

          public int getFieldLength(java.lang.String fieldName)

      Description copied from interface: `DBRecord`
      Returns the length (in number or characters) of the given fieldname.
      Specified by:
        `getFieldLength` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!

    - #### isNotNullField

          public boolean isNotNullField(java.lang.String fieldName)

      Description copied from interface: `DBRecord`
      Tells wasCancelled this field is a not null field.
      Specified by:
        `isNotNullField` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!

    - #### getMasterRecord

          public abstract DBRecord getMasterRecord()

      Specified by:
        `getMasterRecord` in interface `DBRecord`

    - #### readPrimaryKeys

          protected abstract void readPrimaryKeys(DBObject obj,
                             int idx,
                             java.sql.ResultSet rs)
                                           throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### readAttributes

          protected abstract void readAttributes(DBObject obj,
                            int idx,
                            java.sql.ResultSet rs)
                                          throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### writePrimaryKeys

          protected abstract void writePrimaryKeys(int idx,
                              java.sql.PreparedStatement ps,
                              DumpString ds)
                                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### writeAttributes

          protected abstract void writeAttributes(int idx,
                             java.sql.PreparedStatement ps,
                             DumpString ds)
                                           throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### isFieldVirtual

          public boolean isFieldVirtual(java.lang.String fieldName)

      Returns always false. This may be different on records that are composed of DBObjects.
      Specified by:
        `isFieldVirtual` in interface `DBRecord`
      Parameters:
        `fieldName` - can be the pure column name or in the format table.column - only the column name is checked!
      See Also:
        `ComposedRecord`

    - #### getFieldDefinition

          protected java.lang.String getFieldDefinition(java.lang.String fieldName)

      Returns the column definition string as used in CREATE TABLE. Note that the returned string is dynamically determined from the type of the current RDBMS system we are connected to.

    - #### invalidate

          public void invalidate()

      Sets the valid flag of this DBObject to false. This method should be called after having changed a variable in order to mark the object as not being in sync with the database.
      See Also:
        `dbUpdate()`, `dbRehash()`

    - #### isDirty

          public boolean isDirty()

      Returns false if this object is known to be consistent with the database. An empty object which has not yet been inserted into the database is not consistent for instance unless the `dbInsert()` method was called.
      Specified by:
        `isDirty` in interface `DBPersistent`
      See Also:
        `dbInsert()`, `dbUpdate()`, `dbDelete()`, `dbRehash()`

    - #### isSilent

          public static boolean isSilent()

      Tells whether DBObjects should do logging

    - #### setSilent

          public static void setSilent(boolean silent)

      Turns logging on or off without changing the ErrorLogger. Quite useful for testing purposes.

    - #### hasPrimaryKey

          public boolean hasPrimaryKey()

      Tells whether this DBObject has got a Primary Key defined in the database
      Specified by:
        `hasPrimaryKey` in interface `DBPersistent`

    - #### getPrimaryKeyCount

          public int getPrimaryKeyCount()

      Returns the number of primary key fields
      Specified by:
        `getPrimaryKeyCount` in interface `DBPersistent`

    - #### getAttributeCount

          public int getAttributeCount()

      Returns the number of attribute fields

    - #### getFieldCount

          public int getFieldCount()

      Returns the total number of fields (primary keys plus attribute fields)
      Specified by:
        `getFieldCount` in interface `DBRecord`

    - #### getFieldFullNames

          public java.lang.String[] getFieldFullNames()

      Returns the names of all database fields in the format table.column.
      Specified by:
        `getFieldFullNames` in interface `DBRecord`
      See Also:
        `getFieldNames()`

    - #### getFieldNames

          public java.lang.String[] getFieldNames()

      Returns the pure column-names of all database fields not containing the tablename.
      Specified by:
        `getFieldNames` in interface `DBRecord`
      See Also:
        `getFieldFullNames()`

    - #### getFieldByName

          public DBColumnKey getFieldByName(java.lang.String fieldName)

      Fetches the field definition by name. The name may either be the simple column name or the fully qualified name of the form 'table.column'

    - #### existsField

          public boolean existsField(java.lang.String fieldName)

      Tells whether this field name exists in this DBObject
      Specified by:
        `existsField` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!

    - #### getIndexOf

          public int getIndexOf(java.lang.String fieldName)

      Returns the index of the given fieldname

    - #### getFieldByIndex

          public DBColumnKey getFieldByIndex(int index)

      Accesses a field definition by index

    - #### getValue

          public java.lang.Object getValue(DBColumnKey columnKey)

      Returns the current value of the given fieldname

    - #### getValue

          public java.lang.Object getValue(java.lang.String fieldName)

      Returns the current value of the given fieldname
      Specified by:
        `getValue` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!

    - #### getValues

          public java.lang.Object[] getValues()

      Returns the values of all database fields as an array

    - #### readObject

          protected DBObject readObject(DBObject dbo,
                            int pkValue)
                                 throws java.sql.SQLException,
                                        RecordNotFoundException,
                                        InvalidPrimaryKeyException

      Throws:
        `java.sql.SQLException`
        `RecordNotFoundException`
        `InvalidPrimaryKeyException`

    - #### readObject

          protected DBObject readObject(DBObject dbo,
                            java.lang.String... pkValues)
                                 throws java.sql.SQLException,
                                        RecordNotFoundException,
                                        InvalidPrimaryKeyException

      Throws:
        `java.sql.SQLException`
        `RecordNotFoundException`
        `InvalidPrimaryKeyException`

    - #### dbExists

          public void dbExists()
                        throws InvalidPrimaryKeyException,
                               RecordNotFoundException,
                               java.sql.SQLException

      Checks whether this DBObject exists as a record in the underlying database table by performing a high performant index only SELECT. This call does not change anything in the DBObject itself.
      Throws:
        `InvalidPrimaryKeyException` - Thrown if the primary key is not valid.
        `RecordNotFoundException` - Thrown if the record could not be found.
        `java.sql.SQLException` - Thrown on any other database problem.
      See Also:
        `exists()`

    - #### dbDelete

          public int dbDelete(SqlCondition condition)
                       throws java.sql.SQLException

      Performs a conditional deletion of all DBObjects of the given type, that match the given condition. Note that this may affect many objects still in memory. After deletion the `isDirty()` state of the deleted DBObjects may not be consistent with the database.
      Returns:
        The number of records deleted from the underlying database table
      Throws:
        `java.sql.SQLException`

    - #### getPrimaryKeyOrder

          public SqlOrder getPrimaryKeyOrder()

      Returns the ORDER clause for ordering by primary key, or null if no primary key exists.

    - #### toString

          public ToString toString(ToString s)

      Returns a String representation of this DBObject which consists of the tablename and the primary key values
      Specified by:
        `toString` in interface `Dumpable`
      Overrides:
        `toString` in class `DumpableObject`

    - #### toDumpString

          public DumpString toDumpString(DumpString s)

      Fills the given DumpString with debugging information about this DBObject.
      Specified by:
        `toDumpString` in interface `Dumpable`
      Overrides:
        `toDumpString` in class `DumpableObject`
      See Also:
        `DumpableObject.toDumpString()`

    - #### createDumpHeader

          protected java.lang.String createDumpHeader()

      Overrides:
        `createDumpHeader` in class `DumpableObject`

    - #### dbInsert

          public void dbInsert()
                        throws InvalidPrimaryKeyException,
                               InsertFailedException,
                               java.sql.SQLException

      Inserts a record into the underlying database table using a prepared INSERT statement. All not-null fields must be set.

      Note that primary key fields are treated somewhat special. If the primary key field is set, then the INSERT operation is tried with that value. If it is omitted, the DBObject tries to determine a new PK value by performing the following calculation:

      - If a PrimaryKeyFactory is set and the current table is managed by it, then the key is taken from the factory.
      - If there is no PrimaryKeyFactory set or the current table is not managed by one, the SQL statement `select max() from...` is issued to the database.
      If the DBObject has a composed primary key, then only the last part of it may be omitted (for auto- calculation), otherwise the insert will fail. Note that primary key calculation and record insertion are both performed within a transaction in repeatable read mode in order to ensure that no other user can interfere.

      Futhermore if an InsertFactory is set, then it is checked for insert default values for any of the yet unset fields. If values are found then they are automatically applied before the insert is tried. Number fields with a value of 0 and boolean fields with a value of false are considered to be unset.

      After a successful insert `isDirty()` will return false.

      Specified by:
        `dbInsert` in interface `DBPersistent`
      Throws:
        `InsertFailedException` - Thrown if record insertion failed.
        `java.sql.SQLException` - Thrown if the databases makes trouble.
        `InvalidPrimaryKeyException`
      See Also:
        `dbUpdate()`, `dbDelete()`, `forceInsert()`, `isDirty()`, `InsertFactory`, `PrimaryKeyFactory`

    - #### setFieldValue

          public void setFieldValue(java.lang.String fieldName,
                           java.lang.Object value)
                             throws java.lang.Exception

      Sets the value of the instance variable which represents the database column
      fieldName
      Parameters:
        `fieldName` - the name of the database column
        `value` - the value
      Throws:
        `java.lang.Exception` - if the value type does not match the field type

    - #### setFieldValue

          public void setFieldValue(java.lang.String fieldName,
                           java.lang.String valueStr)
                             throws java.lang.Exception

      Sets the value of the instance variable which represents the database column
      fieldName
      . The valueStr parameter is converted to the correct data type of the column. If the conversion fails, a DataConversionException is thrown.
      Throws:
        `java.lang.Exception`
      See Also:
        `setFieldValue(String, Object)`

    - #### dbUpdate

          public void dbUpdate()
                        throws InvalidPrimaryKeyException,
                               RecordNotFoundException,
                               java.sql.SQLException

      Updates the record in the underlying database table using a prepared UPDATE statement. After a successful update the DBObject is in sync with the database and `isDirty()` will return false.
      Specified by:
        `dbUpdate` in interface `DBPersistent`
      Throws:
        `InvalidPrimaryKeyException` - Thrown if the primary key is invalid.
        `RecordNotFoundException` - Thrown if the record does not exist in the database.
        `java.sql.SQLException` - Thrown if the databases makes trouble.
      See Also:
        `isDirty()`, `forceUpdate()`, `dbUpdate()`

    - #### forceInsert

          public boolean forceInsert()

      Performs a forced insert of the DBObject. If the INSERT fails an UPDATE is tried instead.
      See Also:
        `forceUpdate()`

    - #### forceUpdate

          public boolean forceUpdate()

      Performs a forced update of the DBObject. If the UPDATE fails an INSERT is tried instead.
      See Also:
        `forceInsert()`

    - #### dbForceUpdate

          public void dbForceUpdate()
                             throws java.sql.SQLException,
                                    InvalidPrimaryKeyException,
                                    InsertFailedException

      Performs a forced update of the DBObject. If the UPDATE fails an INSERT is tried instead.
      Throws:
        `java.sql.SQLException`
        `InvalidPrimaryKeyException`
        `InsertFailedException`
      See Also:
        `dbForceInsert()`

    - #### dbForceInsert

          public void dbForceInsert()
                             throws java.sql.SQLException,
                                    RecordNotFoundException,
                                    InvalidPrimaryKeyException

      Performs a forced insert of the DBObject. If the INSERT fails an UPDATE is tried instead.
      Throws:
        `java.sql.SQLException`
        `RecordNotFoundException`
        `InvalidPrimaryKeyException`
      See Also:
        `dbForceUpdate()`

    - #### dbDelete

          public void dbDelete()
                        throws InvalidPrimaryKeyException,
                               RecordNotFoundException,
                               java.sql.SQLException

      Deletes the record from the underlying database table using a prepared DELETE statement. Note that the remaining DBObject has become invalid after this call even if no record was affected by the deletion. The latter case happens, when the record had been deleted already by another user - thus it is invalid in either case.
      Specified by:
        `dbDelete` in interface `DBPersistent`
      Throws:
        `InvalidPrimaryKeyException` - Thrown if the primary key is invalid.
        `java.sql.SQLException` - Thrown if the databases makes trouble.
        `RecordNotFoundException`
      See Also:
        `isDirty()`

    - #### exists

          public boolean exists()

      Same as `dbExists()` just any Exception that may have been thrown is caught away.
      Specified by:
        `exists` in interface `DBPersistent`
      Returns:
        true if the record exists in the database, false otherwise.
      See Also:
        `dbExists()`

    - #### dbRehash

          public void dbRehash()
                        throws InvalidPrimaryKeyException,
                               RecordNotFoundException,
                               java.sql.SQLException

      Re-reads the current DBObject from the database using a prepared SELECT statement. This can be used as an undo mechanism after a failed update() call. If this call was successful `isDirty()` will return false.
      Specified by:
        `dbRehash` in interface `DBPersistent`
      Throws:
        `InvalidPrimaryKeyException` - Thrown if the primary key is not valid.
        `RecordNotFoundException` - Thrown if no according record was found in the database.
        `java.sql.SQLException` - Thrown if a database problem occurred.
      See Also:
        `exists()`

    - #### getMasterRecord

          public static DBRecord getMasterRecord(java.lang.Class clazz)

      Returns a cached DBObject instance of the given subclass. The returned Object must be casted to the special subclass type in order to access it's particular fields.

      Note: DBObject instantiation is somewhat tricky! For creation of a DBObject of type XX we must use the createInstance() method of an instance of an XX object. Thus in order to create an XX we first must have an XX!! Thats why the subclass caches an instance of itself as a once- object. Thus we reuse the same masterXX for the creation of all the other instances.

      Returns:
        the static master object of the given subclass.

    - #### dbSearch

          public DBRecord[] dbSearch(SqlCondition condition)
                              throws java.sql.SQLException

      Same as `dbSelect(SqlCondition condition)`. It makes a difference only for composed DBObjects.
      Specified by:
        `dbSearch` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`

    - #### dbSearch

          public DBRecord[] dbSearch(SqlCondition condition,
                            SqlOrder order)
                              throws java.sql.SQLException

      Same as `dbSelect(SqlCondition condition, SqlOrder order)`. It makes a difference only for composed DBObjects.
      Specified by:
        `dbSearch` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`

    - #### dbSearch

          public void dbSearch(DBLoadMonitor monitor,
                      SqlCondition condition)
                        throws java.sql.SQLException

      Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition)`. It makes a difference only for composed DBObjects.
      Specified by:
        `dbSearch` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`

    - #### dbSearch

          public void dbSearch(DBLoadMonitor monitor,
                      SqlCondition condition,
                      SqlOrder order)
                        throws java.sql.SQLException

      Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`. It makes a difference only for composed DBObjects.
      Specified by:
        `dbSearch` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`

    - #### dbSelect

          public DBRecord[] dbSelect()
                              throws java.sql.SQLException

      Reads all records of the underlying table without any condition, ordered by primary key.
      Throws:
        `java.sql.SQLException`

    - #### dbSelect

          public DBRecord[] dbSelect(SqlCondition condition)
                              throws java.sql.SQLException

      Reads all records that match the given condition, ordered by primary key.
      Specified by:
        `dbSelect` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`

    - #### dbSelect

          public DBRecord[] dbSelect(SqlOrder order)
                              throws java.sql.SQLException

      Reads all records of the table ordered by the given order.
      Throws:
        `java.sql.SQLException`

    - #### dbSelect

          public DBRecord[] dbSelect(SqlCondition condition,
                            SqlOrder order)
                              throws java.sql.SQLException

      Reads all records that match the given condition, ordered by the given order clause. If the order clause is null, then no ordering is done.
      Specified by:
        `dbSelect` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`

    - #### dbLoad

          public void dbLoad(DBLoadMonitor monitor)
                      throws java.sql.SQLException

      Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`. With no condition and ordering by primary key.
      Throws:
        `java.sql.SQLException`

    - #### dbLoad

          public void dbLoad(DBLoadMonitor monitor,
                    SqlCondition condition)
                      throws java.sql.SQLException

      Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`. The default ordering is by primary key.
      Specified by:
        `dbLoad` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`

    - #### dbLoad

          public void dbLoad(DBLoadMonitor monitor,
                    SqlOrder order)
                      throws java.sql.SQLException

      Same as `dbLoad(DBLoadMonitor monitor, SqlCondition condition, SqlOrder order)`. With no condition and the given order.
      Throws:
        `java.sql.SQLException`

    - #### dbLoad

          public void dbLoad(DBLoadMonitor monitor,
                    SqlCondition condition,
                    SqlOrder order)
                      throws java.sql.SQLException

      Loads records according to the given condition and order. The LoadMonitor is being notified about each loaded record and is responsible for processing it. This method is typically called by a LoadThread for asynchronous loading.
      Specified by:
        `dbLoad` in interface `DBPersistent`
      Throws:
        `java.sql.SQLException`
      See Also:
        `DBLoadTask`

    - #### createInstance

          protected abstract DBRecord createInstance()

    - #### createInstance

          protected abstract DBRecord createInstance(java.lang.String... primaryKeys)
                                              throws java.sql.SQLException,
                                                     RecordNotFoundException,
                                                     InvalidPrimaryKeyException

      Throws:
        `java.sql.SQLException`
        `RecordNotFoundException`
        `InvalidPrimaryKeyException`

    - #### createInstance

          public static DBObject createInstance(java.lang.Class dboClass,
                                java.lang.String... primaryKeys)
                                         throws java.sql.SQLException,
                                                RecordNotFoundException,
                                                InvalidPrimaryKeyException

      Creates an instance of the given DBObject type for the given primary key.
      Throws:
        `java.sql.SQLException`
        `RecordNotFoundException`
        `InvalidPrimaryKeyException`

    - #### createInstance

          public static DBObject createInstance(java.lang.Class dboClass)

      Creates an empty instance of the given DBObject type.

    - #### dbCountRecords

          public int dbCountRecords()
                             throws java.sql.SQLException

      Counts the number of records in the table by issuing a `select count(*) from ...` statement.
      Throws:
        `java.sql.SQLException`

    - #### dbCountRecords

          public int dbCountRecords(SqlCondition cond)
                             throws java.sql.SQLException

      Counts the number of records in the table by issuing a `select count(*) from ...` statement using the given filter condition.
      Throws:
        `java.sql.SQLException`

    - #### begin

          public static int begin()
                           throws java.sql.SQLException

      Starts a transaction on the current connection. All database changes done since now are performed as a group action which must be finished with the commit() or rollback() call.

      Note that nested transactions are supported. Thus begin() may be called n times by the same thread, each call increasing the nesting level. Accordingly commit() must be called n times decreasing the nesting level again. If nesting level 0 is reached by a commit() call then the database COMMIT is actually performed. A rollback() call at any nesting level will immediately break the transaction and fall back to nesting level 0.

      Note that the default isolation level for a transaction is READ_COMMITTED.

      Returns:
        the nesting level of the transaction
      Throws:
        `java.sql.SQLException`
      See Also:
        `begin(int)`

    - #### begin

          public static int begin(int txIsolationLevel)
                           throws java.sql.SQLException

      Same as begin() but allows for setting the isolation level to any of Connection.TRANSACTION_*. Setting the isolation level has only effect on the first begin(int) call of a nested transaction. After the transaction the isolation level is automatically being resetted to its previous state.
      Returns:
        the nesting level of the transaction
      Throws:
        `java.sql.SQLException`
      See Also:
        `begin()`

    - #### commit

          public static void commit()
                             throws java.sql.SQLException,
                                    NotInTransactionException

      Commits the current transaction and finalizes the changes in the database.
      Throws:
        `java.sql.SQLException`
        `NotInTransactionException`

    - #### rollback

          public static boolean rollback()

      Rolls back the last transaction started. All database changes done since the begin() call are now undone.

      Note that this method does intentionally NOT throw an Exception. If the rollback fails in the database then there is nothing we can do about it anyway.

    - #### isPrimaryKeyValid

          public boolean isPrimaryKeyValid()

      Tells whether this DBObject has a valid primary key.

    - #### isPrimaryKeyValid

          public boolean isPrimaryKeyValid(java.lang.String... pkValues)

      Checks whether the given pkValues array is a valid primary key for this DBObject.

    - #### isFieldNumeric

          public boolean isFieldNumeric(java.lang.String fieldName)

    - #### getFieldIcon

          public java.lang.String getFieldIcon(java.lang.String fieldName)

      Returns a name for an icon if the field is a primary key field, null otherwise. The name has the format 'dbo/'.
      Specified by:
        `getFieldIcon` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!

    - #### isPrimaryKey

          public boolean isPrimaryKey(java.lang.String fieldName)

      Tells whether the given field is a primary key field
      Specified by:
        `isPrimaryKey` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!

    - #### isForeignKey

          public boolean isForeignKey(java.lang.String fieldName)

      Tells whether the given field is a foreign key field
      Specified by:
        `isForeignKey` in interface `DBRecord`
      Parameters:
        `fieldName` - might be a pure column name or in the format table.column - only the column name is checked!
      See Also:
        `DBRecord.getForeignKeyRef(String)`

    - #### getForeignKeyRef

          public java.lang.String getForeignKeyRef(java.lang.String columnName)

      Returns the reference of a foreign key column in the format table.column
      Specified by:
        `getForeignKeyRef` in interface `DBRecord`
      Parameters:
        `columnName` - The name of the field in the format table.column - only the column name is checked!

    - #### getForeignKeyGroup

          public java.lang.String getForeignKeyGroup(java.lang.String columnName)

      Returns the group name of a particular foreign key column
      See Also:
        `getForeignKeyGroups()`

    - #### getForeignKeyGroups

          public java.lang.String[] getForeignKeyGroups()

      Returns an array of the available oreign key groups, if any.
      See Also:
        `getForeignKeyGroup(String)`

    - #### equals

          public boolean equals(java.lang.Object o)

      Compares two DBObject's by comparing their primary key values.

      Note that the current valid-state is not considered for determining equality.

      Overrides:
        `equals` in class `java.lang.Object`
      Returns:
        true if all primary key values are not null and equal.

    - #### clone

          public DBObject clone()

      Overrides:
        `clone` in class `TransferableObject`

    - #### equalAttributes

          public boolean equalAttributes(java.lang.Object o)

      Compares two DBObject's by comparing their attribute values.
      Returns:
        true if all attribute values of both objects are equal.

    - #### equalPrimaryKeys

          public boolean equalPrimaryKeys(java.lang.Object o)

      Compares two DBObject's by comparing their primary key values.
      Returns:
        true if all primary key values of both objects are not null and equal.

    - #### hashCode

          public int hashCode()

      Overridden to return a class specific hash-code.
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### compareTo

          public int compareTo(java.lang.Object o)

      Implementation of Comparable interface. The comparison is done by stepping through all parts of the primary and comparing the values until a difference is found.
      Specified by:
        `compareTo` in interface `java.lang.Comparable`

    - #### dbExistsTable

          public boolean dbExistsTable()

      Checks the existence of the underlying table in the database.
      Returns:
        true if the table exists, false otherwise.

    - #### dbDropTable

          public void dbDropTable()
                           throws java.sql.SQLException

      Removes the underlying table from the database. All it's content will be lost.
      Throws:
        `java.sql.SQLException`

    - #### dbCreateTable

          public void dbCreateTable()
                             throws java.sql.SQLException

      Creates the underlying table in the database if it does not exist yet.
      Throws:
        `java.sql.SQLException`

    - #### dbCreateForeignKeyConstraints

          public void dbCreateForeignKeyConstraints()
                                             throws java.sql.SQLException

      This call adds all foreign key constraints to a table. This method is supposed to be called once after table creation. Note that this method requires all tables which are referenced by foreign keys to exist in the database. Therefore it is run typically after all tables have been created.
      Throws:
        `java.sql.SQLException`

    - #### executeSQL

          public static int executeSQL(java.lang.String sql)
                                throws ConnectionNotEstablishedException,
                                       java.sql.SQLException

      Executes the given statement in the Database and returns the number of records affected
      Throws:
        `ConnectionNotEstablishedException`
        `java.sql.SQLException`

    - #### executeQuery

          public static java.sql.ResultSet executeQuery(java.lang.String sql)
                                                 throws ConnectionNotEstablishedException,
                                                        java.sql.SQLException

      Executes the given statement in the Database and returns a ResultSet with the matching records.
      Throws:
        `ConnectionNotEstablishedException`
        `java.sql.SQLException`

    - #### getManagedDBObjects

          public DBObject[] getManagedDBObjects()

      Returns always the identity reference. This may however differ on `ComposedRecord` types.
      Specified by:
        `getManagedDBObjects` in interface `DBRecord`
      See Also:
        `ComposedRecord`

    - #### toKey

          public static java.lang.String toKey(java.lang.String key)

    - #### toKey

          public static java.lang.String toKey(java.lang.String[] keys)

    - #### getRdbmsSupport

          public static RdbmsSupport getRdbmsSupport()

      Returns an RDBMS specific RdbmsSupport object which encapsulates the particularities of the RDBMS system we currently are connected to.

    - #### getRdbmsInfo

          public static RdbmsInfo getRdbmsInfo()

      Returns an RdbmsInfo object which caches the most frequently used database meta data of the current connection.

    - #### setErrorLogger

          public static void setErrorLogger(LogSupport logger)

      Set a custom `LogSupport` which reports DBObject activity. The default is `LogChannel.getDefault()`. Note that this logger is optional, it is used to report details (record full dumps) when actions on a record do fail.
      See Also:
        `setSilent(boolean)`

    - #### getErrorLogger

          public static LogSupport getErrorLogger()

      See Also:
        `setErrorLogger(LogSupport)`

    - #### setDecimalRounding

          public static void setDecimalRounding(java.math.RoundingMode mode,
                                int digits)

      Sets the decimal rounding mode and the rounding digits. If the rounding mode is not null, then all float and double values of DBObjects will be rounded accordingly when the values are set. By default the rounding mode is null, thus no rounding takes place. Note that rounding applies to float or double values when accessing them via setter/getter methods!
      See Also:
        `roundValue(double)`

    - #### isDecimalRounding

          public static boolean isDecimalRounding()

      Tells if decimal rounding is active.
      See Also:
        `setDecimalRounding(RoundingMode, int)`

    - #### getDecimalRoundingMode

          public static java.math.RoundingMode getDecimalRoundingMode()

      Returns the current decimal rounding mode.
      See Also:
        `setDecimalRounding(RoundingMode, int)`

    - #### getDecimalRoundingDigits

          public static int getDecimalRoundingDigits()

      Returns the current decimal rounding digits.
      See Also:
        `setDecimalRounding(RoundingMode, int)`

    - #### convertArray

          public static java.lang.Object convertArray(java.lang.Class newArrayClass,
                                      java.lang.Object sourceArray)

      Converts the sourceArray to an array of type arrayClass so that the resultArray is castable to arrayClass.

    - #### dbGetString

          protected java.lang.String dbGetString(java.sql.ResultSet rs,
                                     int index)
                                          throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetInt

          protected int dbGetInt(java.sql.ResultSet rs,
                     int index)
                          throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetLong

          protected long dbGetLong(java.sql.ResultSet rs,
                       int index)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetFloat

          protected float dbGetFloat(java.sql.ResultSet rs,
                         int index)
                              throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetDouble

          protected double dbGetDouble(java.sql.ResultSet rs,
                           int index)
                                throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetBoolean

          protected boolean dbGetBoolean(java.sql.ResultSet rs,
                             int index)
                                  throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetBooleanFromChar

          protected java.lang.Boolean dbGetBooleanFromChar(java.sql.ResultSet rs,
                                               int index)
                                                    throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetDate

          protected java.sql.Date dbGetDate(java.sql.ResultSet rs,
                                int index)
                                     throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetTime

          protected java.sql.Time dbGetTime(java.sql.ResultSet rs,
                                int index)
                                     throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetTimestamp

          protected java.sql.Timestamp dbGetTimestamp(java.sql.ResultSet rs,
                                          int index)
                                               throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbGetBlob

          protected java.sql.Blob dbGetBlob(java.sql.ResultSet rs,
                                int index)

    - #### dbGetClob

          protected java.sql.Clob dbGetClob(java.sql.ResultSet rs,
                                int index)

    - #### dbSetClob

          protected void dbSetClob(java.sql.PreparedStatement ps,
                       int index,
                       java.sql.Clob clob,
                       DumpString ds,
                       DBColumnKey col)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetClob

          protected void dbSetClob(java.sql.PreparedStatement ps,
                       int index,
                       java.sql.Clob clob,
                       DumpString ds,
                       java.lang.String fieldName)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetBlob

          protected void dbSetBlob(java.sql.PreparedStatement ps,
                       int index,
                       java.sql.Blob blob,
                       DumpString ds,
                       DBColumnKey col)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetBlob

          protected void dbSetBlob(java.sql.PreparedStatement ps,
                       int index,
                       java.sql.Blob blob,
                       DumpString ds,
                       java.lang.String fieldName)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetPersistentName

          protected void dbSetPersistentName(java.sql.PreparedStatement ps,
                                 int index,
                                 PersistentName value,
                                 DumpString ds,
                                 DBColumnKey col)
                                      throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetPersistentId

          protected void dbSetPersistentId(java.sql.PreparedStatement ps,
                               int index,
                               PersistentId value,
                               DumpString ds,
                               DBColumnKey col)
                                    throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetString

          protected void dbSetString(java.sql.PreparedStatement ps,
                         int index,
                         java.lang.String value,
                         DumpString ds,
                         DBColumnKey col)
                              throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetInt

          protected void dbSetInt(java.sql.PreparedStatement ps,
                      int index,
                      int value,
                      DumpString ds,
                      DBColumnKey col)
                           throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetLong

          protected void dbSetLong(java.sql.PreparedStatement ps,
                       int index,
                       long value,
                       DumpString ds,
                       DBColumnKey col)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetFloat

          protected void dbSetFloat(java.sql.PreparedStatement ps,
                        int index,
                        float value,
                        DumpString ds,
                        DBColumnKey col)
                             throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetDouble

          protected void dbSetDouble(java.sql.PreparedStatement ps,
                         int index,
                         double value,
                         DumpString ds,
                         DBColumnKey col)
                              throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetBoolean

          protected void dbSetBoolean(java.sql.PreparedStatement ps,
                          int index,
                          boolean value,
                          DumpString ds,
                          DBColumnKey col)
                               throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetBooleanAsChar

          protected void dbSetBooleanAsChar(java.sql.PreparedStatement ps,
                                int index,
                                java.lang.Boolean value,
                                DumpString ds,
                                DBColumnKey col)
                                     throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetDate

          protected void dbSetDate(java.sql.PreparedStatement ps,
                       int index,
                       java.sql.Date value,
                       DumpString ds,
                       DBColumnKey col)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetTime

          protected void dbSetTime(java.sql.PreparedStatement ps,
                       int index,
                       java.sql.Time value,
                       DumpString ds,
                       DBColumnKey col)
                            throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetTimestamp

          protected void dbSetTimestamp(java.sql.PreparedStatement ps,
                            int index,
                            java.sql.Timestamp value,
                            DumpString ds,
                            DBColumnKey col)
                                 throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### dbSetPK

          protected void dbSetPK(java.sql.PreparedStatement ps,
                     int index,
                     java.lang.String valueStr,
                     DumpString ds,
                     DBColumnKey col)
                          throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### toObject

          protected java.lang.Object toObject(boolean value)

    - #### toObject

          protected java.lang.Object toObject(int value)

    - #### toObject

          protected java.lang.Object toObject(long value)

    - #### toObject

          protected java.lang.Object toObject(float value)

    - #### toObject

          protected java.lang.Object toObject(double value)

    - #### toObject

          protected java.lang.Object toObject(java.lang.Object value)

    - #### isTrimStringsOnRead

          public static boolean isTrimStringsOnRead()

      Tells whether Strings are trimmed when they are read from the database By default strings are trimmed.

    - #### setTrimStringsOnRead

          public static void setTrimStringsOnRead(boolean doTrim)

      Enforces Strings to be trimmed when they are read from the database

    - #### isTrimStringsOnWrite

          public static boolean isTrimStringsOnWrite()

      Tells whether Strings are trimmed when they are written to the database. By default strings are trimmed.

    - #### setTrimStringsOnWrite

          public static void setTrimStringsOnWrite(boolean doTrim)

      Enforces Strings to be trimmed when they are written to the database

    - #### setStoreZeroAsNull

          public static void setStoreZeroAsNull(boolean storeAsNull)

      This is a global switch that enforces storage of numeric zero values as null values in numeric fields. By default zero values are stored as 0 or 0.0 respectively.

      Note that zero values can be stored as nulls in the database, but if they are read back, they will be stored in primitive int, long, float or double fields as 0 values again.

    - #### isStoreZeroAsNull

          public static boolean isStoreZeroAsNull()

      Tells whether numeric zero values should be written as null.
      See Also:
        `setStoreZeroAsNull(boolean)`

    - #### getSchema

          public static java.lang.String getSchema()

      Returns the current schema name if any.
      See Also:
        `setSchema(String)`

    - #### setSchema

          public static void setSchema(java.lang.String schema)

      This allows for setting a schema name that will used as a tablename prefix when accessing the underlying database table. A schema name must be set when you want to access a table that resides in a different database schema than your default login schema.
      See Also:
        `getSchema()`

    - #### isReadPrimaryKeyOnly

          public boolean isReadPrimaryKeyOnly()

      Tells whether only primary keys are read from the database.
      See Also:
        `setReadPrimaryKeyOnly(boolean)`

    - #### setReadPrimaryKeyOnly

          public void setReadPrimaryKeyOnly(boolean readPKOnly)

      Enforces that only primary key values are read from the database when performing a dbSelect() or dbSearch() call. Attribute values will all be null. This is useful for saving memory if a huge amount of records has to be read. The missing attribute values can be retrieved when actually needed with a dbRehash() call.

    - #### clearPrimaryKey

          public void clearPrimaryKey()

      Clears all primary key variables of this DBObject. Object references are set to null, numeric values are set to zero, booleans are set to false.
      See Also:
        `clearAttributes()`

    - #### clearValues

          public void clearValues()

      Clears all member variables of this dbobject including the primary key values. Object references are set to null, numeric values are set to zero, booleans are set to false.
      See Also:
        `clearAttributes()`

    - #### clearAttributes

          public void clearAttributes()

      Clears all member variables of this dbobject except the primary key values. Object references are set to null, numeric values are set to zero, booleans are set to false.
      See Also:
        `clearValues()`

    - #### roundValue

          public static float roundValue(float value)

      Rounds a float value according to the current decimal RoundingMode.
      See Also:
        `setDecimalRounding(RoundingMode, int)`

    - #### roundValue

          public static double roundValue(double value)

      Rounds a double value according to the current decimal RoundingMode.
      See Also:
        `setDecimalRounding(RoundingMode, int)`

    - #### copyRecordValues

          public void copyRecordValues(DBRecord otherRecord,
                              boolean isIncludePK)
                                throws java.lang.Exception

      Copies all values of an other record of the same type to this one.
      Specified by:
        `copyRecordValues` in interface `DBRecord`
      Throws:
        `java.lang.Exception`

Copyright © 2014 EsprIT-Systems. All Rights Reserved.