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