com.antelmann.util
Class Country.Store

java.lang.Object
  com.antelmann.util.Country.Store

All Implemented Interfaces:

DBClassStore<Country>, TransactionRequired

Enclosing class:

Country

public static class Country.Store
extends Object
implements DBClassStore<Country>

provides a convenient read-only store for all existing Country objects without having to hold them all in memory constantly

Nested Class Summary

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

DBClassStore.DBMethod

Constructor Summary

Country.Store(Database<?> db)

Method Summary

boolean	containsID(Object id) determines whether the given ID is present in this store.
int	deleteEntries(Filter<? super Country> 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<Country>	fetch(Filter<? super Country> filter) allows to retrieve the entries of this storage via iteration.
DBEnumeration<Stub<Country>>	fetchStubs(Filter<? super Stub<?>> filter) allows to access objects from this store w/o having to instantiate the entire original objects, but instead use Stubs to be able to display the list properly for selection.
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.
Country	getEntry(Object id) returns the DBEntry based on its ID.
Class<Country>	getEntryClass() returns the runtime class type this store represents
Stub<Country>	getStub(Object id) returns a Stub representing the resource for the given ID or null.
void	insert(Country entry) it is suggested to create the entry with an ID obtained through generateNewID() before passing it into this method.
Object	insertAsNew(Country entry) inserts the given entry using an ID generated by generateNewID while ignoring the ID of the given entry.
int	size(Filter<? super Country> filter) returns the total number of T elements in this store based on the given filter (which may be null)
void	update(Country 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

Constructor Detail

Country.Store

public Country.Store(Database<?> db)

Method Detail

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

Throws:

DatabaseException

deleteEntries

public int deleteEntries(Filter<? super Country> 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<Country>

Returns:

the number of objects that were deleted

Throws:

DatabaseException

See Also:

DBClassStore.deleteEntry(Object)

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

Returns:

true only if the DBEntry with the given ID was actually found and deleted.

Throws:

DatabaseException

fetch

public DBEnumeration<Country> fetch(Filter<? super Country> 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<Country>

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<Country>> fetchStubs(Filter<? super Stub<?>> filter)
                                        throws DatabaseException

Description copied from interface: DBClassStore

allows to access objects from this store w/o having to instantiate the entire original objects, but instead use Stubs to be able to display the list properly for selection. The given filter may be null. Other than that, the same transactional implications apply as for fetch(Filter).

Specified by:

fetchStubs in interface DBClassStore<Country>

Throws:

DatabaseException

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

Throws:

DatabaseException

UnsupportedOperationException

See Also:

SessionIdGenerator, DBEntry.getID()

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

getEntry

public Country getEntry(Object id)
                 throws DatabaseException

Description copied from interface: DBClassStore

returns the DBEntry based on its ID.

Specified by:

getEntry in interface DBClassStore<Country>

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

getEntryClass

public Class<Country> getEntryClass()

Description copied from interface: DBClassStore

returns the runtime class type this store represents

Specified by:

getEntryClass in interface DBClassStore<Country>

getStub

public Stub<Country> 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<Country>

Throws:

DatabaseException

insert

public void insert(Country 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<Country>

Throws:

DatabaseException

See Also:

DBClassStore.generateNewID()

insertAsNew

public Object insertAsNew(Country 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<Country>

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

size

public int size(Filter<? super Country> 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<Country>

Parameters:

filter - if non-null, only those elements will be counted that are applicable to the filter

Throws:

DatabaseException

update

public void update(Country entry)
            throws DatabaseException

Description copied from interface: DBClassStore

updates the given entry in the database.

Specified by:

update in interface DBClassStore<Country>

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