Holger's Java API

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

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

All Implemented Interfaces:
  DBClassStore<T>, TransactionRequired, MappingInfo, ProcessorHook<T,DatabaseException>

Direct Known Subclasses:
  DetailRowStore, GenericPropertyEntryStore, RelationshipStore, UserImplStore

    public class JDBCRowStore<T extends DBEntry>

extends Object
implements DBClassStore<T>, MappingInfo, ProcessorHook<T,DatabaseException>

provides JDBC persistence for Objects that have a corresponding ObjectRowMapper. Note that this class should not be used by itself, but always through a Proxy wrapped by a SQLDatabase, so that all methods are properly synchronized via the transaction.

Author:
  Holger Antelmann
See Also:
  `SQLDatabase`, `BaseRowMapper`

Nested Class Summary

Nested classes/interfaces inherited from interface com.antelmann.db.DBClassStore
`DBClassStore.DBMethod`

Field Summary
`protected Database<Connection>` `database`
`protected boolean` `ensureTransactionsOnFetch` when set to true, the fetch-methods ensure a synchronized transactional context; false is the default
`protected ConnectionHelper` `helper`
`protected ObjectRowMapper<T>` `mapper`

Constructor Summary
`JDBCRowStore(Database<Connection> database, ObjectRowMapper<T> mapper, Class<T> typeClass)` typeClass is used to specify the original class for the Stub objects
`JDBCRowStore(Database<Connection> database, ObjectRowMapper<T> mapper, Class<T> typeClass, boolean ignoreInvalidProperties)`
`JDBCRowStore(Database<Connection> database, ObjectRowMapper<T> mapper, Class<T> typeClass, boolean ignoreInvalidProperties, boolean fastDelete)`

Method Summary
`void` `add(Processor<T,? extends DatabaseException> processor)`
`protected void` `checkTransaction()` throws the exception if there is no active transaction
`boolean` `containsID(Object id)` determines whether the given ID is present in this store.
`int` `deleteEntries(Filter<? super T> filter)` supports SQLMapFilter for more effective deletion.
`boolean` `deleteEntry(Object id)` removes the entry with the given ID from this store in the database.
`DBEnumeration<T>` `fetch(Filter<? super T> filter)` Depending of the capabilities of the mapper in use, this method can support various special filters.
`DBEnumeration<Stub<T>>` `fetchStubs(Filter<? super Stub<?>> filter)` This implementation supports SQLStubFilter and SQLDirectQueryEntryFilter objects; but otherwise, it doesn't filter in any more intelligent way than leaving the filtering to the AbstractIterator.
`Object` `generateNewID()` returns a value supplied by the mapper
`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.
`Database<Connection>` `getDatabase()` provides access to the database instance that also coordinates the transaction management.
`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
`T` `getEntry(Object id)` returns the DBEntry based on its ID.
`Class<T>` `getEntryClass()` returns the runtime class type this store represents
`String` `getIDColumn()` specifies the column where the ID of the entry is mapped to
`ObjectRowMapper<T>` `getMapper()`
`String` `getMappingForTopic(Object topic)` allows to determine whether a specific given topic maps to a distinct table, query or column name.
`int` `getSQLTypeforColumn(String column)` allows to determine the SQL-type for a given column name
`Stub<T>` `getStub(Object id)` returns a Stub representing the resource for the given ID or null.
`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.
`void` `insert(T entry)` it is suggested to create the entry with an ID obtained through `generateNewID()` before passing it into this method.
`Object` `insertAsNew(T entry)` inserts the given entry using an ID generated by `generateNewID` while ignoring the ID of the given entry.
`boolean` `isFastDelete()` if set to true, the method deleteResources(Filter<T>) will - in case of a PropertyEntryFilter or a SQLMapFilter - delete the affected rows directly via ConnectionHelper - disregarding what the mapper may define.
`boolean` `isIgnoreInvalidProperties()`
`boolean` `remove(Processor<T,? extends DatabaseException> processor)`
`JDBCRowStore<T>` `setFastDelete(boolean fastDelete)` allows to set a flag that enables this implementation to directly delete on the JDBC level - if applicable.
`void` `setIgnoreInvalidProperties(boolean ignoreInvalidProperties)`
`int` `size(Filter<? super T> filter)` supports special performance optimization for SQLMapFilter and some other.
`static String` `trimIdString(String idColumn)` allows to strip the table name from the column name for cases where the id column needed to be specified as [table].
`void` `update(T entry)` updates the given entry in the database.

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

Field Detail

### database

    protected Database<Connection> database

### helper

    protected ConnectionHelper helper

### mapper

    protected ObjectRowMapper<T extends DBEntry> mapper

### ensureTransactionsOnFetch

    protected boolean ensureTransactionsOnFetch

  when set to true, the fetch-methods ensure a synchronized transactional context; false is the default

  See Also:
    `DBUtils.ensureActive(com.antelmann.db.DBTransaction)`, `AbstractDatabase.setEnsureTransactions(boolean)`

Constructor Detail

### JDBCRowStore

    public JDBCRowStore(Database<Connection> database,
                        ObjectRowMapper<T> mapper,
                        Class<T> typeClass)

  typeClass is used to specify the original class for the Stub objects

### JDBCRowStore

    public JDBCRowStore(Database<Connection> database,
                        ObjectRowMapper<T> mapper,
                        Class<T> typeClass,
                        boolean ignoreInvalidProperties)

### JDBCRowStore

    public JDBCRowStore(Database<Connection> database,
                        ObjectRowMapper<T> mapper,
                        Class<T> typeClass,
                        boolean ignoreInvalidProperties,
                        boolean fastDelete)

Method Detail

### getDatabase

    public Database<Connection> getDatabase()

  Description copied from interface: `DBClassStore`
  provides access to the database instance that also coordinates the transaction management.

  Specified by:
    `getDatabase` in interface `DBClassStore<T extends DBEntry>`

### getEntryClass

    public Class<T> getEntryClass()

  Description copied from interface: `DBClassStore`
  returns the runtime class type this store represents

  Specified by:
    `getEntryClass` in interface `DBClassStore<T extends DBEntry>`

### getMapper

    public ObjectRowMapper<T> getMapper()

### getDisplayColumn

    public 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`

### getIDColumn

    public 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`

### getTableName

    public 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 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()`

### getMappingForTopic

    public String getMappingForTopic(Object topic)

  Description copied from interface: `MappingInfo`
  allows to determine whether a specific given topic maps to a distinct table, query or column name.

  Specified by:
    `getMappingForTopic` in interface `MappingInfo`
  Returns:
    either a table name, a column name, a query string or null - depending on the given topic

### 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()`

### 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

### 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

### containsID

    public boolean containsID(Object id)
                       throws DatabaseException

  Description copied from interface: `DBClassStore`
  determines whether the given ID is present in this store.

  Specified by:
    `containsID` in interface `DBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException`

### isFastDelete

    public boolean isFastDelete()

  if set to true, the method deleteResources(Filter<T>) will - in case of a PropertyEntryFilter or a SQLMapFilter - delete the affected rows directly via ConnectionHelper - disregarding what the mapper may define. If false (the default), you can more easily customize the deletion process as then - in the case above - `deleteEntries(Filter)` will call `deleteEntry(Object)` for every affected row.

  See Also:
    `setFastDelete(boolean)`, `ObjectRowMapper.verifyBeforeDelete(Object)`

### setFastDelete

    public JDBCRowStore<T> setFastDelete(boolean fastDelete)

  allows to set a flag that enables this implementation to directly delete on the JDBC level - if applicable. Note that while this option provides drastic performance improvements on `deleteEntries(Filter)` when set to true, it can also be dangerous if a mapper relies on `ObjectRowMapper.verifyBeforeDelete(Object)` or a subclass overrides `deleteEntry(Object)`; therefore, use this option with thought and caution!

  Returns:
    this
  See Also:
    `isFastDelete()`

### isIgnoreInvalidProperties

    public boolean isIgnoreInvalidProperties()

### setIgnoreInvalidProperties

    public void setIgnoreInvalidProperties(boolean ignoreInvalidProperties)

### deleteEntry

    public boolean deleteEntry(Object id)
                        throws DatabaseException

  Description copied from interface: `DBClassStore`
  removes the entry with the given ID from this store in the database.

  Specified by:
    `deleteEntry` in interface `DBClassStore<T extends DBEntry>`
  Returns:
    true only if the DBEntry with the given ID was actually found and deleted.
  Throws:
    `DatabaseException`

### deleteEntries

    public int deleteEntries(Filter<? super T> filter)
                      throws DatabaseException

  supports SQLMapFilter for more effective deletion. Depending on the protected member variable fastDelete this method will act differently in case of a PreparedStatementFilter, SQLMapFilter or SQLDirectQueryEntryFilter as parameter. Note that if fastDelete is true, the internalFilter of a SQLMapFilter or PreparedStatementEntryFilter is ignored!

  Specified by:
    `deleteEntries` in interface `DBClassStore<T extends DBEntry>`
  Returns:
    the number of objects that were deleted
  Throws:
    `DatabaseException`
  See Also:
    `SQLDirectQueryEntryFilter`, `PreparedStatementEntryFilter`, `SQLMapFilter`, `fastDelete`

### insert

    public void insert(T entry)
                throws DatabaseException

  Description copied from interface: `DBClassStore`
  it is suggested to create the entry with an ID obtained through `generateNewID()` before passing it into this method. The ID of the entry must not already exist in the database.

  Specified by:
    `insert` in interface `DBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException`
  See Also:
    `DBClassStore.generateNewID()`

### insertAsNew

    public Object insertAsNew(T entry)
                       throws DatabaseException,
                              UnsupportedOperationException

  Description copied from interface: `DBClassStore`
  inserts the given entry using an ID generated by `generateNewID` while ignoring the ID of the given entry. With this method, the same Object (with the same ID) can be inserted multiple times, stored with a new ID on each call; the ID creation is handled automatically. This is an optional feature that might not be implemented in all cases.

  Specified by:
    `insertAsNew` in interface `DBClassStore<T extends DBEntry>`
  Returns:
    the newly created ID of the object used as ID for the given entry to be inserted
  Throws:
    `DatabaseException`
    `UnsupportedOperationException`
  See Also:
    `DBEntry.getID()`, `DBClassStore.generateNewID()`

### update

    public void update(T entry)
                throws DatabaseException

  Description copied from interface: `DBClassStore`
  updates the given entry in the database.

  Specified by:
    `update` in interface `DBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException` - if the database was not able to perform the update or it the entry didn't exist in the database before calling this method

### getEntry

    public T getEntry(Object id)
                               throws DatabaseException

  Description copied from interface: `DBClassStore`
  returns the DBEntry based on its ID.

  Specified by:
    `getEntry` in interface `DBClassStore<T extends DBEntry>`
  Parameters:
    `id` - the ID that is retrieved from `Resource.getID()`
  Returns:
    the associated DBEntry or null if the id is unknown
  Throws:
    `DatabaseException`
  See Also:
    `DBEntry.getID()`

### getStub

    public Stub<T> getStub(Object id)
                                    throws DatabaseException

  Description copied from interface: `DBClassStore`
  returns a Stub representing the resource for the given ID or null. This method allows to display the object w/o having to retrieve the full DBEntry.

  Specified by:
    `getStub` in interface `DBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException`

### checkTransaction

    protected void checkTransaction()
                             throws TransactionException

  throws the exception if there is no active transaction

  Throws:
    `TransactionException`

### fetch

    public DBEnumeration<T> fetch(Filter<? super T> filter)
                                           throws DatabaseException

  Depending of the capabilities of the mapper in use, this method can support various special filters. If the iteration fails at any point, an IterationException is thrown.

  Specified by:
    `fetch` in interface `DBClassStore<T extends DBEntry>`
  Parameters:
    `filter` - may be null, in which case all entries from are returned.
  Throws:
    `DatabaseException`
  See Also:
    `OffsetFilter`, `IterationException`, `BaseRowMapper.getResultSet(Filter)`

### fetchStubs

    public DBEnumeration<Stub<T>> fetchStubs(Filter<? super Stub<?>> filter)
                                                      throws DatabaseException

  This implementation supports SQLStubFilter and SQLDirectQueryEntryFilter objects; but otherwise, it doesn't filter in any more intelligent way than leaving the filtering to the AbstractIterator. if the iteration fails at any point, an IterationException is thrown.

  Specified by:
    `fetchStubs` in interface `DBClassStore<T extends DBEntry>`
  Throws:
    `DatabaseException`
  See Also:
    `OffsetFilter`, `SQLStubFilter`, `SQLDirectQueryEntryFilter`, `IterationException`

### generateNewID

    public Object generateNewID()
                         throws DatabaseException,
                                UnsupportedOperationException

  returns a value supplied by the mapper

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

### size

    public int size(Filter<? super T> filter)
             throws DatabaseException

  supports special performance optimization for SQLMapFilter and some other.

  Specified by:
    `size` in interface `DBClassStore<T extends DBEntry>`
  Parameters:
    `filter` - if non-null, only those elements will be counted that are applicable to the filter
  Throws:
    `DatabaseException`

### add

    public void add(Processor<T,? extends DatabaseException> processor)

  Specified by:
    `add` in interface `ProcessorHook<T extends DBEntry,DatabaseException>`

### remove

    public boolean remove(Processor<T,? extends DatabaseException> processor)

  Specified by:
    `remove` in interface `ProcessorHook<T extends DBEntry,DatabaseException>`

### trimIdString

    public static String trimIdString(String idColumn)

  allows to strip the table name from the column name for cases where the id column needed to be specified as [table].[id] due a query

  See Also:
    `MappingInfo.getTableQuery()`

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