Holger's Java API

## com.antelmann.sql
Class BaseRowMapper<T extends DBEntry>

    java.lang.Object
      com.antelmann.sql.BaseRowMapper<T>

All Implemented Interfaces:
  TransactionRequired, MappingInfo, ObjectRowMapper<T>, Converter<RowItem,T>

Direct Known Subclasses:
  BaseDocumentMapper, BeanMapper, GenericPropertyEntryMapper, ImageURLEntryMapper, MappedEntryMapper, MessageEntryMapper, MySqlQueryToViewMapper, PropertyMapper, RelationshipStore.Mapper, SerializedEntrySQLMapper, ThumbnailMapper, UserImplMapper

    public abstract class BaseRowMapper<T extends DBEntry>

extends Object
implements ObjectRowMapper<T>, Converter<RowItem,T>

serves as a base class for implementations of ObjectRowMapper. The methods left to be implemented directly depend on the class to be mapped:

- generateRowProperties(Object)
- instantiate(RowItem)

The `generateNewID()`-method relies on an IDFactory to be set for this instance; otherwise, this method must be overridden, too (unless throwing an UnsupportedOperationException is acceptable).

Author:
  Holger Antelmann
See Also:
  `SQLMapFilter`, `JDBCRowStore`

Nested Class Summary

Nested classes/interfaces inherited from interface com.antelmann.util.Converter
`Converter.Adapter<T1,T2>`

Field Summary
`protected Database<Connection>` `db`
`protected ConnectionHelper` `helper`

Constructor Summary
`BaseRowMapper(Database<Connection> db, MappingInfo mi, IDFactory idFactory, Class<T> type, Object... topics)` allows to initialize this MappingInfo with the given one.
`BaseRowMapper(Database<Connection> db, String tableName, String idColumn)` the idColumn is also used as the displayColumn
`BaseRowMapper(Database<Connection> db, String tableName, String idColumn, IDFactory idFactory, Class<T> type)`
`BaseRowMapper(Database<Connection> db, String tableName, String idColumn, String displayColumn)`
`BaseRowMapper(Database<Connection> db, String tableName, String idColumn, String displayColumn, IDFactory idFactory, Class<T> type)`
`BaseRowMapper(Database<Connection> db, String tableName, String idColumn, String displayColumn, IDFactory idFactory, Class<T> type, String query)` this constructor is eventually called by all others

Method Summary
`void` `addColumnsForTopic(Object topic, String... columns)` adds all given columns as applicable for the given topic
`void` `applyFromMapping(MappingInfo mi, Object... topics)` applies the info from the given mapping to this mapping (excluding table, id, display and query properties).
`protected void` `checkExistence(DBReference ref)`
`T` `convert(RowItem obj)`
`RowItem` `convertBack(T obj)`
`protected SQLMapFilter<T>` `convertTopicFilter(TopicMapFilter<?> tfilter)`
`Map<String,Object>` `emptyStringsToNull(Map<String,Object> map)` convenience method; replaces all empty String values with null
`DefaultDBReference` `extractReference(RowItem ri, Object idTopic, Object classTopic, Object stringTopic, Class<?> defaultClass)` convenience method to extract a `DBReference` from topics while optionally being able to provide a defaultClass or an `EntryClassMapper`.
`Stub<T>` `extractStub(ResultSet rs, Class<T> typeClass)` this is used to generate the Stub from a row, using the displayColumn from the mapper.

`

`<S extends DBEntry> Stub<S>`

`

`extractStub(RowItem ri, Object idTopic, Object stringTopic, Class<S> type)`
convenience method

`Object` `generateNewID()` returns the return value of the given IDFactory or throws UnsupportedOperationException if no IDFactory was supplied
`protected abstract Map<String,Object>` `generateRowProperties(T entry)` generates a map that contains all columns mapped to their values, so that the map can be used to store the object into a row.
`protected ResultSet` `getAll(String[] columns)` returns all table rows with the given columns as a ResultSet; if the parameter is null or empty, all columns of the table (or tableQuery if applicable) are retrieved
`Hashtable<String,String>` `getColumnDisplayMapping()` provides direct access to the underlying data to individualize the column display information
`String[]` `getColumnNames()` returns all the columns that are retrieved by the mapper when querying the database); the column names for the ID column and display column are included in the returned array.
`String[]` `getColumnsForTopic(Object topic)` allows to determine whether there are any columns that are applicable for the given topic
`int` `getColumnSize(String column)` allows to determine the size of the given column name.
`Connection` `getConnection()`
`ConnectionHelper` `getConnectionHelper()`
`String` `getDisplayColumn()` for use in stubs (in case a single column is used as a display value)
`String` `getDisplayNameForColumn(String column)` returns a name suitable for display in a GUI if different from the column name used in the database
`Class<T>` `getEntryClass()`
`EntryClassMapper` `getEntryClassMapper()`
`String` `getIDColumn()` specifies the column where the ID of the entry is mapped to
`IDFactory` `getIDFactory()`
`Object` `getMappedValue(Object topic, RowItem ri)` convenience method: returns null if the topic is not mapped (or if the mapped value is indeed null)
`String` `getMappingForTopic(Object topic)` If the topic does not exist but is a String that is an existing column, it is returned as such.
`protected Integer` `getNextIntID()` a convenience implementation for easily providing a way of generating new IDs for tables using an integer column as ID column.
`static IDFactory` `getNextIntIDFactory(ConnectionHelper helper, String tableName, String idColumn)`
`static IDFactory` `getNextIntIDFactory(ConnectionHelper helper, String tableName, String idColumn, PatternExtractor<Object,Number> numberExtractor)`
`Filter<? super T>` `getPreStoreFilter()`
`Set<String>` `getReadOnlyColumns()` allows to specify columns that are never written back to the database (useful for columns that are part of a query)
`String[]` `getRestrictMappedColumns()` allows to limit the columns retrieved from a ResultSet when loading the data from a table query.
`ResultSet` `getResultSet(Filter<? super T> filter)` if no special filter for more effectively obtaining a ResultSet can be used (or if the filter is null), `getAll()` is called.
`int` `getSQLTypeforColumn(String column)` allows to determine the SQL-type for a given column name
`protected String[]` `getStubColumns()` allows to limit the columns in the select statement for retrieving stubs; this implementation returns an array containing the id column and - if applicable - the display column.
`String` `getStubQuery()`
`ResultSet` `getStubResultSet(Filter<? super Stub<?>> filter)` supports the same functionality as `getResultSet(Filter)`; additional support for `SQLStubFilter`
`String[]` `getSupportedTopicColumns()` returns all topics supported by `getColumnsForTopic(Object)`
`String[]` `getTableColumnNames()`
`String` `getTableName()` provides the name of the table that stores the data for the store
`String` `getTableQuery()` if querying involves something different than just selecting all columns of the table, this method returns the string used to replace the table name in a query.
`protected String` `getTableQueryForComboFilter(SQLComboFilter<?> filter)` this implementation first looks for a mapping for SQLCombiFilter.class and then (if no mapping was set) returns the tableQuery if non-null and the tableName otherwise.
`TransactionCounter` `getTransactionCounter()` returns the TransactionCounter instance that is used with this instance.
`String` `getUniqueRandomString()` a convenience implementation for easily providing a way of generating new IDs for tables using a random String as an ID.
`void` `handleAfterStore(T entry, boolean isInsert)` does nothing unless overridden
`protected void` `initMapping()` responsible for initializing and caching the meta data for the `MappingInfo` interface; note that this method is indirectly called by the constructor
`boolean` `isMappedTopic(Object topic)`
`boolean` `isTranslate()`
`Object` `javaToSql(Object obj, int sqlType, int precision)` implementation based on `ConnectionHelper.javaToSql(Object, int, int)`; used in `MappedEntryMapper`
`Object` `javaToSql(Object value, String column)` used to convert java values to their sql representation for filtering purposes
`protected void` `lockTable()` locks the table in a database specific way so that certain methods are prevented from running into deadlocks.
`void` `mapReference(DBReference ref, Map<String,Object> map, Object idTopic, Object classTopic, Object stringTopic)` #see `mapReference(DBReference, Map, Object, Object, Object, Class)`
`void` `mapReference(DBReference ref, Map<String,Object> map, Object idTopic, Object classTopic, Object stringTopic, Class<?> refType)` convenience method to map a `DBReference` to the given topics while optionally being able to provide an `EntryClassMapper` If the topic does not exist but is a String that is an existing column, it is used as such.
`RowItem` `mapToRow(T entry)` uses the abstract `generateRowProperties(DBEntry)` method to generate the RowItem
`ArrayList<String>` `removeColumnTopic(Object topic)` removes all columns from the mapping for the given topic
`void` `setColumnsForTopic(Object topic, String... columns)`
`protected void` `setDisplayColumn(String displayColumn)`
`void` `setEntryClass(Class<T> type)` this must never be null if the idFactory is non-null (or if a TopicMapFilter is used and the store overrides the MappingInfo)
`void` `setEntryClassMapper(EntryClassMapper ecm)`
`void` `setIDFactory(IDFactory idFactory, Class<T> type)`
`boolean` `setMappedValue(Object topic, Map<String,Object> map, Object value)` convenience method: sets the given value corresponding to the topic on the map only if the topic is mapped and the column is not read-only.
`void` `setNextIntIdAsFactory(Class<T> type)` sets a factory that uses `getNextIntID()` for `generateNewID()`
`void` `setPreStoreFilter(Filter<? super T> filter)` allows to specify a filter that is used before each update/insert
`void` `setReadOnlyColumns(String... columns)` allows to set the read-only columns in a potentially more convenient way
`void` `setRestrictedMappedColumns(String... columns)` restricts the columns that are actually retrieved when instantiating the RowItem; the other columns can still be queried upon, but they will not be available upon creating the instance.
`void` `setStubQuery(String stubQuery)` allows to specify a special query for retrieving stubs.
`protected void` `setTableQuery(String tableQuery)` allows to set a query for mapping the data instead of just using the table name.
`protected void` `setTableQuery(String tableQuery, String newIdColumn)` in addition to setting a table query, this also allows to change the id column (often required to ensure the uniqueness of the id column in a query that may contain the column multiple times).
`String` `setTopic(Object topic, String mapping)` allows to define information for `getMappingForTopic(Object)`
`void` `setTranslate(boolean flag)` allows to set the flag that determines whether a filter map is 'translated' before use.

`

`<X> X`

`

`sqlToJava(Object obj, Class<X> requiredJavaType)`
implementation based on `ConnectionHelper.sqlToJava(Object, Class)`; used in `MappedEntryMapper`

`Map<String,Object>` `toSQLMap(Map<String,Object> restrictions)` used for convenience to convert values from a filtering map
`void` `verifyBeforeDelete(Object id)` does nothing unless overridden
`void` `verifyBeforeStore(T entry, boolean isInsert)` checks whether the filter (if non-null) accepts the entry.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface com.antelmann.sql.ObjectRowMapper
`instantiate`

Field Detail

### db

    protected final Database<Connection> db

### helper

    protected final ConnectionHelper helper

Constructor Detail

### BaseRowMapper

    public BaseRowMapper(Database<Connection> db,
                         String tableName,
                         String idColumn)
                  throws DatabaseException

  the idColumn is also used as the displayColumn

  Throws:
    `DatabaseException`

### BaseRowMapper

    public BaseRowMapper(Database<Connection> db,
                         String tableName,
                         String idColumn,
                         IDFactory idFactory,
                         Class<T> type)
                  throws DatabaseException

Throws:
  `DatabaseException`

### BaseRowMapper

    public BaseRowMapper(Database<Connection> db,
                         String tableName,
                         String idColumn,
                         String displayColumn)
                  throws DatabaseException

Throws:
  `DatabaseException`

### BaseRowMapper

    public BaseRowMapper(Database<Connection> db,
                         String tableName,
                         String idColumn,
                         String displayColumn,
                         IDFactory idFactory,
                         Class<T> type)
                  throws DatabaseException

Throws:
  `DatabaseException`

### BaseRowMapper

    public BaseRowMapper(Database<Connection> db,
                         String tableName,
                         String idColumn,
                         String displayColumn,
                         IDFactory idFactory,
                         Class<T> type,
                         String query)
                  throws DatabaseException

  this constructor is eventually called by all others

  Throws:
    `DatabaseException`

### BaseRowMapper

    public BaseRowMapper(Database<Connection> db,
                         MappingInfo mi,
                         IDFactory idFactory,
                         Class<T> type,
                         Object... topics)
                  throws DatabaseException

  allows to initialize this MappingInfo with the given one. If the given `MappingInfo` instance is also a `DefaultMappingInfo`, the topics and read-only columns are initialized accordingly as well.

  Throws:
    `DatabaseException`

Method Detail

### convert

    public T convert(RowItem obj)
                              throws IllegalArgumentException

  Specified by:
    `convert` in interface `Converter<RowItem,T extends DBEntry>`
  Throws:
    `IllegalArgumentException`

### convertBack

    public RowItem convertBack(T obj)
                        throws IllegalArgumentException,
                               UnsupportedOperationException

  Specified by:
    `convertBack` in interface `Converter<RowItem,T extends DBEntry>`
  Throws:
    `IllegalArgumentException`
    `UnsupportedOperationException`

### applyFromMapping

    public void applyFromMapping(MappingInfo mi,
                                 Object... topics)

  applies the info from the given mapping to this mapping (excluding table, id, display and query properties). To use everything from a given MappingInfo, use the appropriate constructor.

  See Also:
    `BaseRowMapper(Database, MappingInfo, IDFactory, Class, Object...)`

### initMapping

    @Warning(value="called by the constructor")
    protected void initMapping()
                        throws DatabaseException

  responsible for initializing and caching the meta data for the `MappingInfo` interface; note that this method is indirectly called by the constructor

  Throws:
    `DatabaseException`
  See Also:
    `setTableQuery(String)`

### getPreStoreFilter

    public final Filter<? super T> getPreStoreFilter()

### setPreStoreFilter

    public void setPreStoreFilter(Filter<? super T> filter)

  allows to specify a filter that is used before each update/insert

  See Also:
    `verifyBeforeStore(DBEntry, boolean)`

### getStubQuery

    public final String getStubQuery()

### setStubQuery

    public void setStubQuery(String stubQuery)

  allows to specify a special query for retrieving stubs. It may also be useful to simply set the table name, if a complex query has been set on `setTableQuery(String)`

### isTranslate

    public final boolean isTranslate()

  See Also:
    `setTranslate(boolean)`

### setTranslate

    public void setTranslate(boolean flag)

  allows to set the flag that determines whether a filter map is 'translated' before use. The translation supports automatic conversion of types like java.util.Date to java.sql.Date or java.sql.Timestamp depending on the type of the targeted column within a filter map.

  See Also:
    `getStubResultSet(Filter)`, `getResultSet(Filter)`

### getEntryClassMapper

    public final EntryClassMapper getEntryClassMapper()

### setEntryClassMapper

    public void setEntryClassMapper(EntryClassMapper ecm)

### getReadOnlyColumns

    public Set<String> getReadOnlyColumns()

  allows to specify columns that are never written back to the database (useful for columns that are part of a query)

### setReadOnlyColumns

    public void setReadOnlyColumns(String... columns)

  allows to set the read-only columns in a potentially more convenient way

### setTopic

    public String setTopic(Object topic,
                           String mapping)

  allows to define information for `getMappingForTopic(Object)`

  Parameters:
    `mapping` - if null, the given topic is removed from the map
  Returns:
    the last mapping for the given topic
  See Also:
    `getMappingForTopic(Object)`

### removeColumnTopic

    public ArrayList<String> removeColumnTopic(Object topic)

  removes all columns from the mapping for the given topic

  Returns:
    a list of previously defined columns for the given topic or null
  See Also:
    `getColumnsForTopic(Object)`

### getSupportedTopicColumns

    public String[] getSupportedTopicColumns()

  returns all topics supported by `getColumnsForTopic(Object)`

### setColumnsForTopic

    public void setColumnsForTopic(Object topic,
                                   String... columns)

  See Also:
    `getColumnsForTopic(Object)`

### addColumnsForTopic

    public void addColumnsForTopic(Object topic,
                                   String... columns)

  adds all given columns as applicable for the given topic

  See Also:
    `getColumnsForTopic(Object)`

### getColumnDisplayMapping

    public Hashtable<String,String> getColumnDisplayMapping()

  provides direct access to the underlying data to individualize the column display information

  See Also:
    `getDisplayNameForColumn(String)`

### getConnectionHelper

    public final ConnectionHelper getConnectionHelper()

### getConnection

    public final Connection getConnection()

  Specified by:
    `getConnection` in interface `ObjectRowMapper<T extends DBEntry>`

### getTableName

    public final String getTableName()

  Description copied from interface: `MappingInfo`
  provides the name of the table that stores the data for the store

  Specified by:
    `getTableName` in interface `MappingInfo`
  See Also:
    `MappingInfo.getTableQuery()`

### getTableQuery

    public final String getTableQuery()

  Description copied from interface: `MappingInfo`
  if querying involves something different than just selecting all columns of the table, this method returns the string used to replace the table name in a query. The return value - if non-null - is used to create ResultSet objects, so that other columns than those merely present in the original table can be retrieved (e.g. through a join). If this value is null, the value from `MappingInfo.getTableName()` is used in all cases. If non-null, this variable would have a value like '(select a.field1, b.* from a, b where a.id=b.id) as t1'.

  Specified by:
    `getTableQuery` in interface `MappingInfo`
  See Also:
    `MappingInfo.getTableName()`

### getIDColumn

    public final String getIDColumn()

  Description copied from interface: `MappingInfo`
  specifies the column where the ID of the entry is mapped to

  Specified by:
    `getIDColumn` in interface `MappingInfo`

### getDisplayColumn

    public final String getDisplayColumn()

  Description copied from interface: `MappingInfo`
  for use in stubs (in case a single column is used as a display value)

  Specified by:
    `getDisplayColumn` in interface `MappingInfo`

### setDisplayColumn

    protected final void setDisplayColumn(String displayColumn)

### setTableQuery

    @Warning(value="called by the constructor")
    protected void setTableQuery(String tableQuery)
                          throws DatabaseException

  allows to set a query for mapping the data instead of just using the table name. This method calls `initMapping()` after setting the data. Since a query of the form '(select ...) as t1' may not be query optimized in certain databases, this implementation also supports a plain select statement to act as a query.

  Throws:
    `DatabaseException`

### setTableQuery

    @Warning(value="called by the constructor")
    protected void setTableQuery(String tableQuery,
                                              String newIdColumn)
                          throws DatabaseException

  in addition to setting a table query, this also allows to change the id column (often required to ensure the uniqueness of the id column in a query that may contain the column multiple times).

  Throws:
    `DatabaseException`
  See Also:
    `setTableQuery(String)`

### verifyBeforeStore

    public void verifyBeforeStore(T entry,
                                  boolean isInsert)
                           throws DatabaseException,
                                  SQLException

  checks whether the filter (if non-null) accepts the entry. If the entry is not accepted by the filter, a `NotApplicableDataWarning` is thrown. When overriding this method, it is advised to call this super implementation.

  Specified by:
    `verifyBeforeStore` in interface `ObjectRowMapper<T extends DBEntry>`
    `isInsert` - if true, the entry is about to be inserted; if false, it is an update
  Throws:
    `DatabaseException`
    `SQLException`
  See Also:
    `setPreStoreFilter(Filter)`

### verifyBeforeDelete

    public void verifyBeforeDelete(Object id)
                            throws DatabaseException,
                                   SQLException

  does nothing unless overridden

  Specified by:
    `verifyBeforeDelete` in interface `ObjectRowMapper<T extends DBEntry>`
  Throws:
    `WrongDataException` - if the deletion is not allowed for semantical reasons
    `DatabaseException`
    `SQLException`

### handleAfterStore

    public void handleAfterStore(T entry,
                                 boolean isInsert)
                          throws DatabaseException,
                                 SQLException

  does nothing unless overridden

  Specified by:
    `handleAfterStore` in interface `ObjectRowMapper<T extends DBEntry>`
    `isInsert` - if true, the entry is about to be inserted; if false, it is an update
  Throws:
    `DatabaseException`
    `SQLException`

### getIDFactory

    public final IDFactory getIDFactory()

### getEntryClass

    public final Class<T> getEntryClass()

### setEntryClass

    public void setEntryClass(Class<T> type)

  this must never be null if the idFactory is non-null (or if a TopicMapFilter is used and the store overrides the MappingInfo)

### setIDFactory

    public void setIDFactory(IDFactory idFactory,
                             Class<T> type)

### setNextIntIdAsFactory

    public void setNextIntIdAsFactory(Class<T> type)
                               throws NullPointerException

  sets a factory that uses `getNextIntID()` for `generateNewID()`

  Parameters:
    `type` - must not be null
  Throws:
    `NullPointerException`

### generateNewID

    public Object generateNewID()
                         throws DatabaseException,
                                UnsupportedOperationException

  returns the return value of the given IDFactory or throws UnsupportedOperationException if no IDFactory was supplied

  Specified by:
    `generateNewID` in interface `ObjectRowMapper<T extends DBEntry>`
  Throws:
    `DatabaseException`
    `UnsupportedOperationException`
  See Also:
    `DBClassStore.generateNewID()`, `SQLNumberGenerator`, `TransactionalNumberGenerator`

### generateRowProperties

    protected abstract Map<String,Object> generateRowProperties(T entry)
                                                         throws WrongDataException

  generates a map that contains all columns mapped to their values, so that the map can be used to store the object into a row. The ID column and the corresponding ID should not be put in there, as this will happen automatically later.

  Throws:
    `WrongDataException`

### mapToRow

    public RowItem mapToRow(T entry)
                     throws WrongDataException

  uses the abstract `generateRowProperties(DBEntry)` method to generate the RowItem

  Specified by:
    `mapToRow` in interface `ObjectRowMapper<T extends DBEntry>`
  Throws:
    `WrongDataException`
  See Also:
    `getReadOnlyColumns()`

### extractStub

    public Stub<T> extractStub(ResultSet rs,
                               Class<T> typeClass)
                                        throws SQLException

  this is used to generate the Stub from a row, using the displayColumn from the mapper. If the displayColumn is the same as the idColumn, this implementation is careful enough to only retrieve that column once and still construct the Stub correctly; this is something to take care of when overriding this method! Also: if you override this method and want to access more than merely id and display column, you must also override `getStubColumns()` to ensure that these columns are generally present.

  Specified by:
    `extractStub` in interface `ObjectRowMapper<T extends DBEntry>`
  Throws:
    `SQLException`

### getStubColumns

    protected String[] getStubColumns()

  allows to limit the columns in the select statement for retrieving stubs; this implementation returns an array containing the id column and - if applicable - the display column. If null (or an empty array) is returned, all columns ('*') are selected for extracting stubs.

  Returns:
    an array containing columns used in the select statement to extract stubs
  See Also:
    `extractStub(ResultSet, Class)`

### getAll

    protected ResultSet getAll(String[] columns)
                        throws SQLException

  returns all table rows with the given columns as a ResultSet; if the parameter is null or empty, all columns of the table (or tableQuery if applicable) are retrieved

  Throws:
    `SQLException`

### getStubResultSet

    public ResultSet getStubResultSet(Filter<? super Stub<?>> filter)
                               throws SQLException

  supports the same functionality as `getResultSet(Filter)`; additional support for `SQLStubFilter`

  Specified by:
    `getStubResultSet` in interface `ObjectRowMapper<T extends DBEntry>`
  Throws:
    `SQLException`

### getTableQueryForComboFilter

    protected String getTableQueryForComboFilter(SQLComboFilter<?> filter)

  this implementation first looks for a mapping for SQLCombiFilter.class and then (if no mapping was set) returns the tableQuery if non-null and the tableName otherwise.

  See Also:
    `getMappingForTopic(Object)`

### getResultSet

    public ResultSet getResultSet(Filter<? super T> filter)
                           throws SQLException

  if no special filter for more effectively obtaining a ResultSet can be used (or if the filter is null), `getAll()` is called. Special filters supported by this implementation include: SQLDirectQueryEntryFilter, SQLMapFilter, FullTextSearchFilter, SQLCombiFilter, TopicMapFilter and PreparedStatementEntryFilter.

  Specified by:
    `getResultSet` in interface `ObjectRowMapper<T extends DBEntry>`
  Throws:
    `SQLException`
  See Also:
    `PreparedStatementEntryFilter`, `SQLDirectQueryEntryFilter`, `FullTextSearchFilter`, `SQLMapFilter`, `TopicMapFilter`, `SQLComboFilter`, `SQLFetchSizeFilter`

### convertTopicFilter

    protected SQLMapFilter<T> convertTopicFilter(TopicMapFilter<?> tfilter)

### isMappedTopic

    public boolean isMappedTopic(Object topic)

### getMappingForTopic

    public String getMappingForTopic(Object topic)

  If the topic does not exist but is a String that is an existing column, it is returned as such.

  Specified by:
    `getMappingForTopic` in interface `MappingInfo`
  Returns:
    either a table name, a column name, a query string or null - depending on the given topic
  See Also:
    `setTopic(Object, String)`

### getColumnsForTopic

    public String[] getColumnsForTopic(Object topic)

  Description copied from interface: `MappingInfo`
  allows to determine whether there are any columns that are applicable for the given topic

  Specified by:
    `getColumnsForTopic` in interface `MappingInfo`
  Returns:
    an array of column names that apply to the given topic; the array may be empty but never null

### getColumnNames

    public String[] getColumnNames()

  Description copied from interface: `MappingInfo`
  returns all the columns that are retrieved by the mapper when querying the database); the column names for the ID column and display column are included in the returned array. Note that the return value refers to the columns in the table query; only if the query is null, the return value refers to the columns in the table itself.

  Specified by:
    `getColumnNames` in interface `MappingInfo`
  Returns:
    all columns that are retrieved by the mapper or null if this doesn't apply for this instance.
  See Also:
    `MappingInfo.getTableName()`, `MappingInfo.getTableQuery()`, `MappingInfo.getIDColumn()`, `MappingInfo.getDisplayColumn()`

### getTableColumnNames

    public String[] getTableColumnNames()
                                 throws DatabaseException

  Throws:
    `DatabaseException`

### getSQLTypeforColumn

    public int getSQLTypeforColumn(String column)
                            throws IllegalArgumentException

  Description copied from interface: `MappingInfo`
  allows to determine the SQL-type for a given column name

  Specified by:
    `getSQLTypeforColumn` in interface `MappingInfo`
  Returns:
    the SQL-type for the given column
  Throws:
    `IllegalArgumentException` - if the given column is not known
  See Also:
    `Types`

### getColumnSize

    public int getColumnSize(String column)
                      throws IllegalArgumentException

  Description copied from interface: `MappingInfo`
  allows to determine the size of the given column name. For a text column, this is the maximum number of characters; for a number column, this specifies the precision.

  Specified by:
    `getColumnSize` in interface `MappingInfo`
  Throws:
    `IllegalArgumentException` - if the given column is not known

### getDisplayNameForColumn

    public String getDisplayNameForColumn(String column)

  Description copied from interface: `MappingInfo`
  returns a name suitable for display in a GUI if different from the column name used in the database

  Specified by:
    `getDisplayNameForColumn` in interface `MappingInfo`
  Returns:
    a suitable display value for the given column or the given column itself if no better display name exists

### getTransactionCounter

    public TransactionCounter getTransactionCounter()

  returns the TransactionCounter instance that is used with this instance. The constructor ensures that a single TransactionCounter instance can be shared over multiple BaseRowMapper - provided the DBTransaction is an AbstractDBTransaction instance. This TransactionCounter is used to optimize the `getNextIntID()` method.

### lockTable

    protected void lockTable()
                      throws SQLException

  locks the table in a database specific way so that certain methods are prevented from running into deadlocks.

  Throws:
    `SQLException`
  See Also:
    `setNextIntIdAsFactory(Class)`, `getNextIntID()`, `ConnectionHelper.lockTable(boolean, String...)`

### getNextIntID

    @Warning(value={"to avoid deadlocks/inconsistencies this method would have to explicitly write-lock the table (which is database-specific) before accessing it","this method must be called synchronized on the transaction (which is usually the case when callled by generateNewID())"})
    protected Integer getNextIntID()
                            throws DatabaseException

  a convenience implementation for easily providing a way of generating new IDs for tables using an integer column as ID column. Note that subsequent calls to this method return the same numbers unless a record is actually inserted into the table in question or it is still the same transaction, in which case a locally cached counter is used. Consequently, this method is only save if used directly before inserting the DBEntry created with this ID and that this happens within the same synchronized transaction. This method uses this instance's TransactionCounter to ensure unique IDs within the same transaction. SQLExceptions are already encapsulated into DatabaseExceptions for easier use. Remaining problem though: since this method doesn't write to the database, merely calling getNetIntID() only holds a read-lock on the table; i.e. another simultaneous client on the database might call this method and receive the exact same ID. This problem can only be prevented if a write-lock is acquired before calling this method in the same transaction. Subclasses might want to resolve this issue by first explicitly acquiring a write-lock and only then make a call super.getNextIntID() (as the acquisition of such a lock is likely to be database dependent).

  Throws:
    `DatabaseException`
  See Also:
    `TransactionalNumberGenerator`

### getNextIntIDFactory

    public static IDFactory getNextIntIDFactory(ConnectionHelper helper,
                                                String tableName,
                                                String idColumn)

### getNextIntIDFactory

    public static IDFactory getNextIntIDFactory(ConnectionHelper helper,
                                                String tableName,
                                                String idColumn,
                                                PatternExtractor<Object,Number> numberExtractor)

### getUniqueRandomString

    public String getUniqueRandomString()

  a convenience implementation for easily providing a way of generating new IDs for tables using a random String as an ID. Each call can be expected to generate a unique ID, regardless of whether or not the return value is actually used to store a DBEntry.

  Returns:
    a String with a length of probably 36
  See Also:
    `UUID.toString()`

### emptyStringsToNull

    public Map<String,Object> emptyStringsToNull(Map<String,Object> map)

  convenience method; replaces all empty String values with null

### setRestrictedMappedColumns

    public void setRestrictedMappedColumns(String... columns)

  restricts the columns that are actually retrieved when instantiating the RowItem; the other columns can still be queried upon, but they will not be available upon creating the instance. Note that if a non-null, non-empty array is given, the id-column must always be included for retrieval! Restricting columns can significantly improve performance if there are many columns in a row that cannot be excluded from the general table query since these should be available for filtering; in that case, it helps to prevent the columns from being retrieved into the row with this method.

### getRestrictMappedColumns

    public String[] getRestrictMappedColumns()

  Description copied from interface: `ObjectRowMapper`
  allows to limit the columns retrieved from a ResultSet when loading the data from a table query. If the return value is null, all columns are retrieved without restriction. If the return value is an empty array, only the ID column is retrieved. If the return value is a non-empty array, only those columns are retrieved from the query that are contained in this array. The id column is always retrieved.

  Specified by:
    `getRestrictMappedColumns` in interface `ObjectRowMapper<T extends DBEntry>`
  Returns:
    an array of column names that limit which columns are retrieved from a `ResultSet` when extracting the data into a `RowItem`; null may be returned.
  See Also:
    `ObjectRowMapper.instantiate(RowItem)`

### toSQLMap

    public Map<String,Object> toSQLMap(Map<String,Object> restrictions)

  used for convenience to convert values from a filtering map

### javaToSql

    public Object javaToSql(Object value,
                            String column)

  used to convert java values to their sql representation for filtering purposes

### sqlToJava

    public <X> X sqlToJava(Object obj,
                           Class<X> requiredJavaType)

  implementation based on `ConnectionHelper.sqlToJava(Object, Class)`; used in `MappedEntryMapper`

### javaToSql

    public Object javaToSql(Object obj,
                            int sqlType,
                            int precision)

  implementation based on `ConnectionHelper.javaToSql(Object, int, int)`; used in `MappedEntryMapper`

### getMappedValue

    public Object getMappedValue(Object topic,
                                 RowItem ri)

  convenience method: returns null if the topic is not mapped (or if the mapped value is indeed null)

  See Also:
    `isMappedTopic(Object)`

### setMappedValue

    public boolean setMappedValue(Object topic,
                                  Map<String,Object> map,
                                  Object value)

  convenience method: sets the given value corresponding to the topic on the map only if the topic is mapped and the column is not read-only. The value is directly translated using `javaToSql(Object, String)`

  Returns:
    true if the value was actually mapped or false if either the topic or the corresponding column didn't exist

### extractStub

    public <S extends DBEntry> Stub<S> extractStub(RowItem ri,
                                                   Object idTopic,
                                                   Object stringTopic,
                                                   Class<S> type)
                                        throws InconsistentContentException,
                                               ClassNotFoundException

  convenience method

  Throws:
    `InconsistentContentException`
    `ClassNotFoundException`
  See Also:
    `extractReference(RowItem, Object, Object, Object, Class)`

### extractReference

    public DefaultDBReference extractReference(RowItem ri,
                                               Object idTopic,
                                               Object classTopic,
                                               Object stringTopic,
                                               Class<?> defaultClass)
                                        throws InconsistentContentException,
                                               ClassNotFoundException

  convenience method to extract a `DBReference` from topics while optionally being able to provide a defaultClass or an `EntryClassMapper`. If the topic does not exist but is a String that is an existing column, it is used as such.

  Throws:
    `InconsistentContentException`
    `ClassNotFoundException`
  See Also:
    `mapReference(DBReference, Map, Object, Object, Object)`, `setEntryClassMapper(EntryClassMapper)`

### mapReference

    public void mapReference(DBReference ref,
                             Map<String,Object> map,
                             Object idTopic,
                             Object classTopic,
                             Object stringTopic)

  #see `mapReference(DBReference, Map, Object, Object, Object, Class)`

### mapReference

    public void mapReference(DBReference ref,
                             Map<String,Object> map,
                             Object idTopic,
                             Object classTopic,
                             Object stringTopic,
                             Class<?> refType)

  convenience method to map a `DBReference` to the given topics while optionally being able to provide an `EntryClassMapper` If the topic does not exist but is a String that is an existing column, it is used as such.

  Parameters:
    `ref` - the reference to be mapped
    `map` - the column map that is filled by this method
    `idTopic` - the topic that specifies the id column for the reference id
    `classTopic` - the topic that specifies the class column for the reference class
    `stringTopic` - the topic that specifies the string column for the reference string
    `refType` - if non-null, the method will check whether the ref class confirms to the specified type if no classTopic was given for mapping
  See Also:
    `extractReference(RowItem, Object, Object, Object, Class)`, `setEntryClassMapper(EntryClassMapper)`

### checkExistence

    protected void checkExistence(DBReference ref)
                           throws DatabaseException

  Throws:
    `DatabaseException`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads