com.webobjects.eoaccess
Class EODatabase

java.lang.Object
  com.webobjects.eoaccess.EODatabase

All Implemented Interfaces:

NSDisposable

public class EODatabase
extends Object
implements NSDisposable

An EODatabase object represents a single database server. It contains an EOAdaptor that is capable of communicating with the database server, a list of EOModels that describe the server's schema, a list of EODatabaseContexts that are connected to the server, and a set of snapshots representing the state of all objects stored in the server.

Each of an EODatabase's EODatabaseContexts forms a separate transaction scope, and is in effect a separate logical user to the server. An EODatabaseContext uses one or more pairs of EODatabaseChannel and EOAdaptorChannel objects to manage data operations (insert, update, delete, and fetch). Adaptors may support a limited number of contexts per database or channels per context, but an application is guaranteed at least one of each.

The Database Level

The EODatabase, EODatabaseContext, and EODatabaseChannel classes form the database level of the Enterprise Objects Framework. The database level is a client of the adaptor level, which is defined by the adaptor classes: EOAdaptor, EOAdaptorContext, and EOAdaptorChannel. Together, the database and adaptor levels make up the access layer of the Enterprise Objects Framework.

The database level acts as an intermediary between the adaptor level and the control layer, which includes an EOObjectStoreCoordinator and an EOEditingContext . The control layer operates in terms of Enterprise Objects, while the adaptor level operates in terms of database rows packaged as NSDictionaries. It is the job of the database level to perform the necessary object-to-relational translation between the two.

There's little need for an application's code to interact directly with an EODatabase object. An EOEditingContext creates its own database level objects, which create their own corresponding adaptor level objects. Once the network of objects is in place, the application might interact with an EODatabase to access its corresponding EOAdaptor object, but additional programmatic interaction is usually unnecessary.

Snapshots

EODatabase's most significant responsibility is to record snapshots for its EODatabaseContexts. A snapshot is a dictionary whose keys are attribute names and whose values are the corresponding, last-known database values. Enterprise Objects Framework records snapshots as it successfully fetches, inserts and updates enterprise objects. Snapshot information is used when changes to Enterprise Objects are saved back out to the database to ensure that row data has not been changed by someone else since it was last recorded by the application.

A snapshot contains entries for a row's primary key, class properties, foreign keys for class property relationships, and attributes used for locking. They are recorded under the globalIDs of their Enterprise Objects.

EODatabase also records snapshots for to-many relationships. These snapshots consist of an NSDictionary of NSDictionaries, in which the top-level dictionary has as its key the globalID of the enterprise object for which to-many relationships are being recorded. The key's value is a dictionary whose keys are the names of the enterprise object's to-many relationships. Each of these keys in turn has as its value an array of globalIDs that identify the objects at the destination of the relationship.

The snapshots made by an EODatabase form the global view of data for nearly every other part of the application, representing the current view of data in the server as far as the application is concerned (though other applications may have made changes). This global view is temporarily overridden locally by EODatabaseContexts, which form their own snapshots as they make changes during a transaction. When an EODatabaseContext commits its top-level transaction, it reconciles all changed snapshots with the global view of the database object, so that other database contexts (except those with open transactions) immediately use the new snapshots as well. EODatabaseContexts automatically use their EODatabase to record snapshots, so there's no need for the application to intervene in an EODatabase's snapshotting mechanism.

Entity Caching

An EODatabase object also performs the function of caching enterprise objects for entities that cache their objects. An EODatabase's entity cache stores the globalIDs of Enterprise Objects for entities that cache their objects. The first time you perform a fetch against such an entity, all of its objects are fetched, regardless of the fetch specification used. The globalIDs of the resulting objects are stored in the EODatabase's entity cache by entity name. Whenever possible, subsequent fetches are performed against the cache (in memory) rather than against the database. With a globalID, Enterprise Objects Framework can look up the values for the corresponding object in its snapshot using EODatabase's or EODatabaseContext's snapshotForGlobalID method.

As an example, suppose that you have an entity named Rating that contains all the valid ratings for Movies (G, PG, R, and so on). Rather than store a Movie's rating directly in the Movie as an attribute, Movie maintains a relationship to a Rating. To specify a rating for a movie, users select the rating from a pop-up list of the possible values. Since the ratings in the Rating entity never change, the Rating entity should cache its objects. The values that populate the rating pop-up list are only fetched once, and there's no need to fetch them again; the relationships between Movies and Ratings can be maintained without subsequent fetches.

The entity cache is managed automatically; you shouldn't have to manipulate it explicitly. However, if you need to access or alter the cache, EODatabase provides several methods for interacting with it.

See Also:

EODatabaseContext, EOGlobalID, EOEntity

Nested Class Summary

static interface

EODatabase.ClassDelegate This interface defines a delegate to the EODatabase class to allow easy subclassing on eth EODatabase.

Constructor Summary

EODatabase(EOAdaptor adaptor)
Creates and returns a new EODatabase object, specifying adaptor as the new EODatabase's adaptor.

EODatabase(EOModel model)
Creates and returns a new EODatabase object, also creating an instance of the EOAdaptor named in model and assigning it as the new EODatabase's adaptor.

Method Summary

EOAdaptor	adaptor() Returns the EOAdaptor used by the receiver for communication with the database server.
void	addModel(EOModel model) Adds model to the receiver's list of EOModels.
boolean	addModelIfCompatible(EOModel model) Returns true if model is already in the receiver's list of EOModels, or if model can be added to the list.
static Object	classDelegate() Returns EODatabase's class delegate.
void	decrementSnapshotCountForGlobalID(EOGlobalID gid) Decrements the reference count for the shared snapshot associated with gid, if the receiver releases unreferenced snapshots.
static void	disableSnapshotRefCounting() Configures EODatabase instances not to release unreferenced snapshots.
void	dispose() Conformance to NSDisposable.
EOEntity	entityForObject(EOEnterpriseObject object) Searches the receiver's list of registered EOModels and returns the first EOEntity found whose name matches the entity name of object.
EOEntity	entityNamed(String entityName) Searches the receiver's list of registered EOModels and returns the first EOEntity found with the name entityName.
void	forgetAllSnapshots() Removes all of the receiver's snapshots and posts an ObjectsChangedInStoreNotification describing the invalidated objects.
void	forgetSnapshotForGlobalID(EOGlobalID gid) Removes the snapshot recorded for the Enterprise Object identified by gid and posts an ObjectsChangedInStoreNotification describing the invalidated object.
void	forgetSnapshotsForGlobalIDs(NSArray array) Removes the snapshots recorded for the Enterprise Objects identified by the globalIDs in array and posts an ObjectsChangedInStoreNotification describing the invalidated objects.
void	handleDroppedConnection() Invoked to initiate clean up when the Framework detects a dropped database connection.
void	incrementSnapshotCountForGlobalID(EOGlobalID gid) Increments the reference count for the shared snapshot associated with gid, if the receiver releases unreferenced snapshots.
void	invalidateResultCache() Invalidates the receiver's result cache.
void	invalidateResultCacheForEntityNamed(String name) Invalidates the result cache containing the globalIDs for the objects associated with the EOEntity identified by name.
NSArray	models() Returns the array of EOModels registered for the receiver.
static EODatabase	newDatabase(EOModel model) Returns a new instance of EODatabase using the class delegate if it exists.
void	recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid) Records snapshot for the Enterprise Object identified by the globalID gid.
void	recordSnapshotForSourceGlobalID(NSArray gids, EOGlobalID gid, String name) For the object identified by gidgids, which is the array of globalIDs identifying the destination objects for the to-many relationship named name.
void	recordSnapshots(NSDictionary snapshots) Records the snapshots in snapshots, which is a dictionary whose keys are globalIDs and whose values are the snapshots for the Enterprise Objects identified by those globalIDs.
void	recordToManySnapshots(NSDictionary snapshots) Records a collection of to-many snapshots from a dictionary keyed by globalID.
void	registerContext(EODatabaseContext context) Registers context as one of the receiver's database contexts.
NSArray	registeredContexts() Returns all the EODatabaseContexts that have been registered with the receiver, generally all the database contexts that were created with the receiver as their EODatabase object.
void	removeModel(EOModel model) Removes model from the receiver's list of EOModels.
NSArray	resultCacheForEntityNamed(String name) Returns an array containing the globalIDs of all the objects associated with the EOEntity identified by name.
static void	setClassDelegate(Object delegate) Assigns delegate as EODatabase's class delegate.
void	setResultCache(NSArray cache, String name) Updates the receiver's result cache for name with cache.
void	setTimestampToNow() Sets the internal timestamp to the current system time.
NSDictionary	snapshotForGlobalID(EOGlobalID gid) Returns the snapshot for the Enterprise Object identified by the globalID gid, or null if there isn't a snapshot.
NSDictionary	snapshotForGlobalID(EOGlobalID gid, long timestamp) Returns the snapshot for the Enterprise Object identified by the globalID gid, provided the snapshot's timestamp is greater than or equal to timestamp.
NSArray	snapshotForSourceGlobalID(EOGlobalID gid, String name) Returns the to-many snapshot for the relationship named name belonging to the Enterprise Object identified by the globalID gid, or null if there is no to-many snapshot.
NSArray	snapshotForSourceGlobalID(EOGlobalID gid, String name, long timestamp) Returns the to-many snapshot for the globalID gid and relationship name, provided that the timestamp of the snapshot is greater than or equal to timestamp.
NSDictionary	snapshots() Returns a dictionary of all of the receiver's snapshots, keyed by globalID.
long	timestampForGlobalID(EOGlobalID gid) Returns the timestamp of the snapshot for the object identified by the globalID gid, or DistantPastTimeInterval if there isn't a snapshot.
long	timestampForSourceGlobalID(EOGlobalID gid, String name) Returns the timestamp of the to-many snapshot for the relationship specified by name and the object identified by gid.
void	unregisterContext(EODatabaseContext context) Removes context as one of the receiver's database contexts.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EODatabase

public EODatabase(EOAdaptor adaptor)

Creates and returns a new EODatabase object, specifying adaptor as the new EODatabase's adaptor. Throws an exception if adaptor is null.

Typically, you don't need to programmatically create EODatabase objects. Rather, they are created automatically by the control layer. If you do need to create an EODatabase programmatically, never associate more than one EODatabase with a given EOAdaptor. In general, create an EODatabase with an EOModel instead of an EOAdaptor.

Parameters:

adaptor - The adaptor for the new EODatabase instance.

Throws:

IllegalArgumentException - if adaptor is null.

See Also:

EODatabase.addModel(EOModel aModel), EOModel.adaptorName()

EODatabase

public EODatabase(EOModel model)

Creates and returns a new EODatabase object, also creating an instance of the EOAdaptor named in model and assigning it as the new EODatabase's adaptor.

Typically, you don't need to programmatically create EODatabase objects. Rather, they are created automatically by the control layer.

Parameters:

model - An EOModel which specifies the adaptor to create and associate with the new EODatabase object.

See Also:

EODatabase.addModel(EOModel aModel), EODatabase.adaptor(), EOModel.adaptorName()

Method Detail

setClassDelegate

public static void setClassDelegate(Object delegate)

Assigns delegate as EODatabase's class delegate. The class delegate is optional; it allows modification of the creation of theEODatabase for a model.

Parameters:

delegate - The object to set as EODatabase's class delegate.

See Also:

EODatabase.classDelegate(), EODatabase.ClassDelegate

classDelegate

public static Object classDelegate()

Returns EODatabase's class delegate.

Returns:

EODatabase's class delegate.

See Also:

EODatabase.setClassDelegate(Object anObject), EODatabase.ClassDelegate

newDatabase

public static EODatabase newDatabase(EOModel model)

Returns a new instance of EODatabase using the class delegate if it exists.

Parameters:

model - An EOModel which specifies the adaptor to create and associate with the new EODatabase object.

Returns:

new instance of EODatabase

dispose

public void dispose()

Conformance to NSDisposable.

Specified by:

dispose in interface NSDisposable

adaptor

public EOAdaptor adaptor()

Returns the EOAdaptor used by the receiver for communication with the database server. The application can interact directly with the EOAdaptor, but should avoid altering its state (for example, by starting a transaction with one of its adaptor contexts).

Returns:

The EOAdaptor used by the receiver to communicate with the database.

See Also:

EODatabase.EODatabase(EOAdaptor anAdaptor), EODatabase.EODatabase(EOModel aModel)

setTimestampToNow

public void setTimestampToNow()

Sets the internal timestamp to the current system time. Used for recording subsequent snapshots.

resultCacheForEntityNamed

public NSArray resultCacheForEntityNamed(String name)

Returns an array containing the globalIDs of all the objects associated with the EOEntity identified by name.

Parameters:

name - The entity name.

Returns:

The globalIDs of the objects associated with name.

See Also:

EODatabase.invalidateResultCache(), EODatabase.invalidateResultCacheForEntityNamed(String entityName)

setResultCache

public void setResultCache(NSArray cache,
                           String name)

Updates the receiver's result cache for name with cache. cache is an array of the globalIDs for all the Enterprise Objects associated with the EOEntity identified by name.

This method is invoked automatically; you should never invoke it directly.

Parameters:

cache - The globalIDs for all objects associated with the entity named name.

name - The name of the EOEntity associated with cache.

See Also:

EODatabase.invalidateResultCache(), EODatabase.invalidateResultCacheForEntityNamed(String entityName), EODatabase.resultCacheForEntityNamed(String name)

invalidateResultCacheForEntityNamed

public void invalidateResultCacheForEntityNamed(String name)

Invalidates the result cache containing the globalIDs for the objects associated with the EOEntity identified by name.

Parameters:

name - The name of an entity.

See Also:

EODatabase.resultCacheForEntityNamed(String entityName), EODatabase.invalidateResultCache()

invalidateResultCache

public void invalidateResultCache()

Invalidates the receiver's result cache.

See Also:

EODatabase.invalidateResultCacheForEntityNamed(String name), EODatabase.resultCacheForEntityNamed(String entityName)

registeredContexts

public NSArray registeredContexts()

Returns all the EODatabaseContexts that have been registered with the receiver, generally all the database contexts that were created with the receiver as their EODatabase object.

Returns:

An array of all the database contexts registered with the receiver.

See Also:

EODatabase.registeredContexts(), EODatabase.unregisterContext(EODatabaseContext context)

registerContext

public void registerContext(EODatabaseContext context)

Registers context as one of the receiver's database contexts. Throws an exception if context was not constructed with the receiver as its EODatabase, or if context is already registered with the receiver.

You should never invoke this method directly; it is invoked automatically by the EODatabaseContext constructor.

Parameters:

context - The database context to register with the receiver.

Throws:

IllegalStateException - if context was not instantiated with the receiver as its EODatabase, or if context is already registered.

See Also:

EODatabase.registeredContexts(), EODatabase.unregisterContext(EODatabaseContext context)

unregisterContext

public void unregisterContext(EODatabaseContext context)

Removes context as one of the receiver's database contexts. Throws an exception if context is not registered with the receiver.

An EODatabaseContext automatically invokes this method when it is finalized. You should never invoke this method directly.

Parameters:

context - The database context to remove from the list of the receiver's registered database contexts.

Throws:

IllegalStateException - if context is not registered with the receiver.

See Also:

EODatabase.registeredContexts(), EODatabase.registerContext(EODatabaseContext context)

addModel

public void addModel(EOModel model)

Adds model to the receiver's list of EOModels. This allows EODatabases to load entities and their properties only as they are needed, by dividing them among separate EOModels. model must use the same EOAdaptor as the receiver and use the same connection dictionary as the receiver's other EOModels.

Parameters:

model - An EOModel to add to the receiver's list of models.

See Also:

EODatabase.addModelIfCompatible(EOModel model), EODatabase.models(), EODatabase.removeModel(EOModel aModel), EOModel

addModelIfCompatible

public boolean addModelIfCompatible(EOModel model)

Returns true if model is already in the receiver's list of EOModels, or if model can be added to the list. To be added to the list of models, the following conditions must be met:

• model is not in the receiver's model list, and
• model specifies the same adaptor name as the receiver, and
• the adaptor responds true to canServiceModel

Otherwise, returns false.

Parameters:

model - A model to add to the receiver's list of EOModels.

Returns:

true if model is already in the list or can be added.

See Also:

EODatabase.addModel(EOModel model), EODatabase.models(), EODatabase.removeModel(EOModel aModel), EODatabase.adaptor()

removeModel

public void removeModel(EOModel model)

Removes model from the receiver's list of EOModels. Throws an exception if model isn't registered as one of the receiver's models.

Parameters:

model - A model to remove from the receiver's list of registered EOModels.

Throws:

IllegalArgumentException - if model isn't registered as one of the receiver's models.

See Also:

EODatabase.models(), EODatabase.addModel(EOModel aModel), EODatabase.addModelIfCompatible(EOModel aModel)

models

public NSArray models()

Returns the array of EOModels registered for the receiver.

Returns:

The receiver's registered models.

See Also:

EODatabase.EODatabase(EOAdaptor anAdaptor), EODatabase.EODatabase(EOModel aModel), EODatabase.addModel(EOModel aModel), EODatabase.addModelIfCompatible(EOModel aModel)

entityNamed

public EOEntity entityNamed(String entityName)

Searches the receiver's list of registered EOModels and returns the first EOEntity found with the name entityName. Returns null if no entity can be found that corresponds to entityName.

Parameters:

entityName - The name of the entity to search for in the receiver's registered models.

Returns:

The first entity named entityName found in the receiver's model list, or null.

See Also:

EODatabase.entityForObject(EOEnterpriseObject object)

entityForObject

public EOEntity entityForObject(EOEnterpriseObject object)

Searches the receiver's list of registered EOModels and returns the first EOEntity found whose name matches the entity name of object. Returns null if no entity can be found that corresponds to object.

Parameters:

object - A EOEnterpriseObject whose entity name is used to search for a corresponding EOEntity among the receiver's registered models.

Returns:

The entity corresponding to object, or null.

See Also:

EODatabase.entityNamed(String entityName)

handleDroppedConnection

public void handleDroppedConnection()

Invoked to initiate clean up when the Framework detects a dropped database connection. EODatabase cleans up by sending handleDroppedConnection first to its adaptor, and then to each of its registered database contexts. When the cleanup procedure is complete, the Framework can automatically reconnect to the database.

Never invoke this method yourself; it is invoked automatically by the Framework.

See Also:

EODatabaseContext.handleDroppedConnection(), EOAdaptor.handleDroppedConnection()

recordSnapshotForGlobalID

public void recordSnapshotForGlobalID(NSDictionary snapshot,
                                      EOGlobalID gid)

Records snapshot for the Enterprise Object identified by the globalID gid.

Parameters:

snapshot - A dictionary whose keys are attribute names and whose values are the corresponding last-known database values for the attributes.

gid - The globalID (unique identifier) of the enterprise object being snapshotted.

See Also:

EODatabase.recordSnapshots(NSDictionary snapshots), EODatabase.forgetSnapshotForGlobalID(EOGlobalID gid), EOEntity.globalIDForRow(NSDictionary row), EOGlobalID

recordSnapshots

public void recordSnapshots(NSDictionary snapshots)

Records the snapshots in snapshots, which is a dictionary whose keys are globalIDs and whose values are the snapshots for the Enterprise Objects identified by those globalIDs.

Parameters:

snapshots - A dictionary of snapshots to record, keyed by globalID.

See Also:

EODatabase.recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid), EODatabase.forgetSnapshotForGlobalID(EOGlobalID gid), EOGlobalID

recordToManySnapshots

public void recordToManySnapshots(NSDictionary snapshots)

Records a collection of to-many snapshots from a dictionary keyed by globalID. The snapshots parameter should be a dictionary of NSDictionaries. The top-level dictionary has as its key the globalID of the Enterprise Object for which to-many relationship snapshots are being recorded. That key's value is a dictionary whose keys are the names of the Enterprise Object's to- many relationships, and whose values are arrays of globalIDs that identify the objects at the destination of each relationship.

Parameters:

snapshots - A dictionary of dictionaries, keyed by globalIDs, representing the snapshots for the to-many relationships of the Enterprise Object identifed by the top-level key.

See Also:

EODatabase.recordSnapshotForSourceGlobalID(NSArray gids, EOGlobalID gid, String name), EODatabase.recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid), EODatabase.snapshotForSourceGlobalID(EOGlobalID gid, String name)

recordSnapshotForSourceGlobalID

public void recordSnapshotForSourceGlobalID(NSArray gids,
                                            EOGlobalID gid,
                                            String name)

For the object identified by gidgids, which is the array of globalIDs identifying the destination objects for the to-many relationship named name.

Parameters:

gids - Identifies the objects at the destination of the relationship.

gid - Identifies the Enterprise Object whose to-many relationship is being snapshotted.

name - The name of the to-many relationship being snapshotted.

See Also:

EODatabase.snapshotForSourceGlobalID(EOGlobalID gid, String name, long timestamp), EODatabase.snapshotForSourceGlobalID(EOGlobalID gid, String name), EODatabase.forgetSnapshotForGlobalID(EOGlobalID gid), EODatabase.recordSnapshots(NSDictionary snapshots), EODatabase

snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID(EOGlobalID gid,
                                         String name)

Returns the to-many snapshot for the relationship named name belonging to the Enterprise Object identified by the globalID gid, or null if there is no to-many snapshot. A to-many snapshot is an array of globalIDs which identify the objects at the destination of a to-many relationship.

Parameters:

gid - The globalID for the Enterprise Object that owns the relationship name.

name - The name of the to-many relationship whose snapshot to return.

Returns:

The to-many snapshot for gid and name, or null.

snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID(EOGlobalID gid,
                                         String name,
                                         long timestamp)

Returns the to-many snapshot for the globalID gid and relationship name, provided that the timestamp of the snapshot is greater than or equal to timestamp. Returns null if there isn't a to-many snapshot for gid and name, or if the snapshot's timestamp is earlier (less) than the reference timestamp.

Parameters:

gid - The globalID for the Enterprise Object that owns the relationship name.

name - The name of the to-many relationship whose snapshot to return.

timestamp - The reference timestamp to compare with the snapshot's timestamp.

Returns:

The to-many snapshot for gid and name, or null.

See Also:

EODatabase.snapshotForSourceGlobalID(EOGlobalID gid, String name), EODatabase.timestampForSourceGlobalID(EOGlobalID gid, String name)

timestampForSourceGlobalID

public long timestampForSourceGlobalID(EOGlobalID gid,
                                       String name)

Returns the timestamp of the to-many snapshot for the relationship specified by name and the object identified by gid. Returns DistantPastTimeInterval if there isn't a snapshot.

Parameters:

gid - The globalID for the Enterprise Object that owns the relationship name.

name - The name of the to-many relationship whose snapshot to return.

Returns:

The timestamp of the to-many snapshot for gid and name, or DistantPastTimeInterval.

See Also:

EODatabase.snapshotForSourceGlobalID(EOGlobalID gid, String name, long timestamp)

forgetSnapshotForGlobalID

public void forgetSnapshotForGlobalID(EOGlobalID gid)

Removes the snapshot recorded for the Enterprise Object identified by gid and posts an ObjectsChangedInStoreNotification describing the invalidated object.

Parameters:

gid - The globalID for an Enterprise Object.

See Also:

EODatabase.forgetSnapshotsForGlobalIDs(NSArray array), EODatabase.forgetAllSnapshots(), EODatabase.recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid), EOObjectStore

forgetSnapshotsForGlobalIDs

public void forgetSnapshotsForGlobalIDs(NSArray array)

Removes the snapshots recorded for the Enterprise Objects identified by the globalIDs in array and posts an ObjectsChangedInStoreNotification describing the invalidated objects.

Parameters:

array - An array of globalIDs for objects whose snapshots to remove.

See Also:

EODatabase.forgetSnapshotForGlobalID(EOGlobalID gid), EODatabase.forgetAllSnapshots(), EODatabase.recordSnapshots(NSDictionary snapshots), EOObjectStore

forgetAllSnapshots

public void forgetAllSnapshots()

Removes all of the receiver's snapshots and posts an ObjectsChangedInStoreNotification describing the invalidated objects.

See Also:

EODatabase.forgetSnapshotForGlobalID(EOGlobalID gid), EODatabase.forgetSnapshotsForGlobalIDs(NSArray array), EODatabase.recordSnapshotForGlobalID(NSDictionary aSnapshot, com.webobjects.eocontrol.EOGlobalID globalID), EODatabase.recordSnapshots(NSDictionary snapshots), EODatabase.recordSnapshotForSourceGlobalID(NSArray globalIDs, com.webobjects.eocontrol.EOGlobalID globalID, String name), EODatabase.recordToManySnapshots(NSDictionary snapshots), EOObjectStore

timestampForGlobalID

public long timestampForGlobalID(EOGlobalID gid)

Returns the timestamp of the snapshot for the object identified by the globalID gid, or DistantPastTimeInterval if there isn't a snapshot.

Parameters:

gid - The globalID for an Enterprise Object.

Returns:

The timestamp of the snapshot for gid, or DistantPastTimeInterval.

See Also:

EOGlobalID

snapshotForGlobalID

public NSDictionary snapshotForGlobalID(EOGlobalID gid)

Returns the snapshot for the Enterprise Object identified by the globalID gid, or null if there isn't a snapshot.

Parameters:

gid - The globalID for an Enterprise Object.

Returns:

The snapshot associated with gid, or null.

See Also:

EODatabase.recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid), EODatabase.forgetSnapshotForGlobalID(EOGlobalID gid)

snapshotForGlobalID

public NSDictionary snapshotForGlobalID(EOGlobalID gid,
                                        long timestamp)

Returns the snapshot for the Enterprise Object identified by the globalID gid, provided the snapshot's timestamp is greater than or equal to timestamp. Returns null if there isn't a snapshot for gid or if the snapshot's timestamp is earlier (less) than the reference timestamp.

Parameters:

gid - The globalID for an Enterprise Object.

timestamp - A reference timestamp to compare with the snapshot's timestamp.

Returns:

The snapshot for gid, or null.

See Also:

EODatabase.recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid), EODatabase.forgetSnapshotForGlobalID(EOGlobalID gid)

snapshots

public NSDictionary snapshots()

Returns a dictionary of all of the receiver's snapshots, keyed by globalID.

Returns:

A dictionary of all of the receiver's snapshots.

See Also:

EODatabase.recordSnapshotForSourceGlobalID(NSArray gids, EOGlobalID gid, String name), EODatabase.recordToManySnapshots(NSDictionary snapshots)

incrementSnapshotCountForGlobalID

public void incrementSnapshotCountForGlobalID(EOGlobalID gid)

Increments the reference count for the shared snapshot associated with gid, if the receiver releases unreferenced snapshots. Throws an exception if there is no snapshot recorded for gid.

If snapshot releasing is turned off, this method does nothing.

Parameters:

gid - The globalID for an Enterprise Object.

Throws:

IllegalStateException - if there is no snapshot for gid.

See Also:

EODatabase.decrementSnapshotCountForGlobalID(EOGlobalID gid), EODatabase.recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid)

decrementSnapshotCountForGlobalID

public void decrementSnapshotCountForGlobalID(EOGlobalID gid)

Decrements the reference count for the shared snapshot associated with gid, if the receiver releases unreferenced snapshots. If no more objects refer to the snapshot, removes it from the snapshot table. Throws an exception if the snapshot reference count is already zero or if there is no snapshot recorded for gid.

If snapshot releasing is turned off, this method does nothing.

Parameters:

gid - The globalID for an enteprise object.

Throws:

IllegalStateException - if the snapshot reference count is zero or there is no snapshot for gid.

See Also:

EODatabase.incrementSnapshotCountForGlobalID(EOGlobalID gid), EODatabase.recordSnapshotForGlobalID(NSDictionary snapshot, EOGlobalID gid)

disableSnapshotRefCounting

public static void disableSnapshotRefCounting()

Configures EODatabase instances not to release unreferenced snapshots.