Holger's Java API

## com.antelmann.db
Class CollectionClassStore<T extends DBEntry>

    java.lang.Object
      com.antelmann.db.CollectionClassStore<T>

All Implemented Interfaces:
  DBClassStore<T>, TransactionRequired, Serializable

    public class CollectionClassStore<T extends DBEntry>

extends Object
implements DBClassStore<T>, Serializable

a transient DBClassStore implementation based on a simple collection of DBEntries. The entries are optionally serialized when put into the embedded collection. Only if serialization is used, this store guarantees transactional integrity of the data; a non-serialized store is much faster, though, so it is ideal for read-only use. By adding itself as a TransactionListener to the given Database, it follows the logic of commits and aborts properly. Note that this implementation is not storing any data persistently!

Since:
  8. August 2007, 15:45
Author:
  Holger Antelmann
See Also:
  `AbstractDatabase`, Serialized Form

Nested Class Summary

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

Constructor Summary
`CollectionClassStore(Database<?> db, boolean serialize, Class<T> type, T... entries)`
`CollectionClassStore(Database<?> db, Class<T> type, boolean serialize)` use serialization for transactional consistent updates and leave it out for read-only stores.
`CollectionClassStore(Database<?> db, Class<T> type, boolean serialize, Collection<T> col)`

Method Summary
`boolean` `containsID(Object id)` determines whether the given ID is present in this store.
`int` `deleteEntries(Filter<? super T> filter)` deletes all DBEntry objects that match the given filter; if the filter is null, all resources are deleted.
`boolean` `deleteEntry(Object id)` removes the entry with the given ID from this store in the database.
`DBEnumeration<T>` `fetch(Filter<? super T> filter)` allows to retrieve the entries of this storage via iteration.
`DBEnumeration<Stub<T>>` `fetchStubs(Filter<? super Stub<?>> filter)` the display value of the returned Stub is based on the toString() method of the DBEntry instance
`void` `finalize()` allow this instance to be garbage-collected by removing it from the database as a listener
`Object` `generateNewID()` this method is to generate unique new IDs for the DBEntry at hand - if the application has no other specific way of providing new IDs for this implementation.
`Database<?>` `getDatabase()` provides access to the database instance that also coordinates the transaction management.
`T` `getEntry(Object id)` returns the DBEntry based on its ID.
`Class<T>` `getEntryClass()` returns the runtime class type this store represents
`IDFactory` `getIdFactory()`
`Stub<T>` `getStub(Object id)` returns a Stub representing the resource for the given ID or null.
`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)` always throws UnsupportedOperationException
`boolean` `isSerialized()`
`void` `put(T entry)`
`void` `remove(T entry)`
`void` `setIdFactory(IDFactory idFactory)`
`int` `size(Filter<? super T> filter)` returns the total number of T elements in this store based on the given filter (which may be null)
`void` `update(T entry)` updates the given entry in the database.

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

Constructor Detail

### CollectionClassStore

    public CollectionClassStore(Database<?> db,
                                Class<T> type,
                                boolean serialize)

  use serialization for transactional consistent updates and leave it out for read-only stores.

### CollectionClassStore

    public CollectionClassStore(Database<?> db,
                                Class<T> type,
                                boolean serialize,
                                Collection<T> col)
                         throws DatabaseException

Throws:
  `DatabaseException`

### CollectionClassStore

    public CollectionClassStore(Database<?> db,
                                boolean serialize,
                                Class<T> type,
                                T... entries)
                         throws DatabaseException

Throws:
  `DatabaseException`

Method Detail

### put

    @Warning(value="this method works directly on the committed data and disregards any transactional boundaries")
    public void put(T entry)
             throws DatabaseException,
                    IllegalStateException

  Throws:
    `DatabaseException`
    `IllegalStateException`

### remove

    @Warning(value="this method works directly on the committed data and disregards any transactional boundaries")
    public void remove(T entry)
                throws IllegalStateException

  Throws:
    `IllegalStateException`

### getIdFactory

    public IDFactory getIdFactory()

### setIdFactory

    public void setIdFactory(IDFactory idFactory)

### isSerialized

    public boolean isSerialized()

### finalize

    public void finalize()
                  throws Throwable

  allow this instance to be garbage-collected by removing it from the database as a listener

  Overrides:
    `finalize` in class `Object`
  Throws:
    `Throwable`

### getDatabase

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

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

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

  Description copied from interface: `DBClassStore`
  deletes all DBEntry objects that match the given filter; if the filter is null, all resources are deleted. Calling this method does not necessarily entail that `DBClassStore.deleteEntry(Object)` is called for each entry passing the filter (although stores may choose to do so)! Consequently, if a store's implementation does not call `DBClassStore.deleteEntry(Object)` on each instance, calling this method may result in changes that are hard to monitor for versioning purposes.

  Specified by:
    `deleteEntries` in interface `DBClassStore<T extends DBEntry>`
  Returns:
    the number of objects that were deleted
  Throws:
    `DatabaseException`
  See Also:
    `DBClassStore.deleteEntry(Object)`

### generateNewID

    public Object generateNewID()
                         throws DatabaseException,
                                UnsupportedOperationException

  Description copied from interface: `DBClassStore`
  this method is to generate unique new IDs for the DBEntry at hand - if the application has no other specific way of providing new IDs for this implementation. Note that not every implementation may embrace this method of providing DBEntry IDs; but this method may be preferred if the ID is merely to distinguish the Resources in the database (rather than being derived for another purpose as well). Not every call must necessarily return a new value, but it must return an ID not yet present in the persistent storage. In particular, an unused ID (i.e. returned earlier for creating an object, but that object was never inserted and committed into the database) may be returned again in a subsequent call in another transaction. Within one transaction, however, the returned ID must be different on each call. As a returned ID may not be actually be used, it would be unwise to rely on the return value to generate IDs that are required to provide for consecutive counters. An implementing class should document the exact behavior, so that the implications of usage are clear for that specific class - as they may be different (sometimes, each call to this method generates a unique value, sometimes that is only guaranteed within the same transaction). Generally, it is advisable, to always create unique IDs that are valid over transaction boundaries.

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

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

  always throws UnsupportedOperationException

  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

### fetch

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

  Description copied from interface: `DBClassStore`
  allows to retrieve the entries of this storage via iteration. Note that the order of the entries is undefined, unless a specially designed filter hints a sorting order to an implementing class that additionally supports sorting.

  As all relevant entries may not completely fit into memory, an Enumeration is returned instead of a list. To directly get all entries as a list (and thus avoid concurrency problems), consider using methods from AbstractIterator to quickly retrieve all resources before processing them.

  Be aware that the result of the enumeration may become undefined if data is inserted/deleted/updated while the elements are accessed. To guarantee consistency, all access to the returned Enumeration must be externally synchronized by holding the monitor of the database transaction throughout maintaining the Enumeration.

  Note that you may have IterationExceptions being thrown on calling methods on the returned Enumeration, which are caused by either DatabaseExceptions or InstantiationExceptions on trying to fetch the next element, as not all possible errors may be caught on calling this method (as it possibly cannot instantiate all entries in advance).

  All access to the returned Enumeration must be made within an active transaction.

  As the returned Enumeration may hold resources to the database while iterating, the caller must ensure that these resources can be properly release. This is usually achieved by simply completely iterating through the return value, in which case the DBEnumeration is expected to properly clean up automatically. But in cases where the caller doesn't intend to go all the way through the Enumeration, the caller has to clean up explicitly, which can be done by calling the close() method on the returned DBEnumeration.

  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:
    `AbstractIterator.list(java.util.Enumeration)`, `IterationException`

### fetchStubs

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

  the display value of the returned Stub is based on the toString() method of the DBEntry instance

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

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

### size

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

  Description copied from interface: `DBClassStore`
  returns the total number of T elements in this store based on the given filter (which may be null)

  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`

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