Documentation Archive Developer
Search
PATH  Documentation > WebObjects 4.5 > EOAdaptor Reference

Table of Contents

EODatabase


Inherits from: NSObject
Package: com.apple.yellow.eoaccess

Class Description

An EODatabase object represents a single database server. It contains an EOAdaptor which is capable of communicating with the 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.

For more information on the EODatabase class, see the sections:




Constants

EODatabase declares the following constants.


Constant Type Description
DistantPastTimeInterval double The lower bound on timestamps.
GeneralDatabaseException String The name of exceptions raised by the database sublayer when errors occur during interactions with a database server.



Method Types

Constructors
EODatabase
Adding and removing models
addModel
addModelIfCompatible
removeModel
models
Accessing entities
entityForObject
entityNamed
Recording snapshots
recordSnapshotForGlobalID
recordSnapshotForSourceGlobalID
recordSnapshots
recordToManySnapshots:
Forgetting snapshots
forgetSnapshotForGlobalID
forgetSnapshotsForGlobalIDs
forgetAllSnapshots
Accessing snapshots and snapshot timestamps
snapshotForGlobalID
snapshotForSourceGlobalID
snapshots
timestampForGlobalID
timestampForSourceGlobalID
Snapshot reference counting
incrementSnapshotCountForGlobalID
decrementSnapshotCountForGlobalID
disableSnapshotRefcounting
Registering database contexts
registerContext
unregisterContext
registeredContexts
Accessing the adaptor
adaptor
Managing the database connection
handleDroppedConnection
Managing the result cache
invalidateResultCache
invalidateResultCacheForEntityNamed
resultCacheForEntityNamed
setResultCacheForEntityWithName


Constructors


EODatabase

public EODatabase(EOAdaptor anAdaptor)

Creates and returns a new EODatabase object, specifying anAdaptor 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. See the class description for more information. If you do need to create an EODatabase programmatically, you should never associate more than one EODatabase with a given EOAdaptor. In general, create an EODatabase with an EOModel instead of an EOAdaptor.

public EODatabase(EOModel aModel)

Creates and returns a new EODatabase object, also creating an instance of the EOAdaptor named in aModel and assigning that EOAdaptor object 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. See the class description for more information.

See Also: addModel, adaptor, adaptorName (EOModel)



Static Methods


disableSnapshotRefcounting

public static void disableSnapshotRefcounting()

Configures EODatabase instances not to release unreferenced snapshots.


Instance Methods


adaptor

public EOAdaptor adaptor()

Returns the EOAdaptor used by the receiver for communication with the database server. Your 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).

See Also: EODatabase constructors


addModel

public void addModel(EOModel aModel)

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

See Also: addModelIfCompatible, models, removeModel


addModelIfCompatible

public boolean addModelIfCompatible(EOModel aModel)

Adds aModel to the receiver's list of EOModels, checking first to see whether it's compatible with those other EOModels. Returns true if aModel is already in the list or if it's successfully added. Returns false if aModel's adaptor name differs from that of the receivers or if the receiver's adaptor returns false to a canServiceModel: message.

See Also: addModel, models, removeModel


decrementSnapshotCountForGlobalID

public void decrementSnapshotCountForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalId)

If the receiver releases unreferenced snapshots, decrements the reference count for the shared snapshot associated with globalID; and if no more objects refer to the snapshot, removes it from the snapshot table. (If the receiver doesn't release snapshots, this method does nothing.)

entityForObject

public EOEntity entityForObject(Object anObject)

Returns the EOEntity from one of the receiver's Models that's mapped to anObject, or null if there is no such EOEntity. This method works by sending entityForObject: messages to each of the receiver's EOModels and returning the first one found.

See Also: entityNamed


entityNamed

public EOEntity entityNamed(String entityName)

Returns the EOEntity from one of the receiver's Models that's named entityName, or null if there is no such EOEntity. This method works by sending entityNamed: messages to each of the receiver's EOModels and returning the first one found.

See Also: entityForObject


forgetAllSnapshots

public void forgetAllSnapshots()

Clears all of the receiver's snapshots and posts an ObjectsChangedInStoreNotification (defined in the EOControl framework's EOObjectStore class) describing the invalidated object. For a description of snapshots and their role in an application, see the class description.

See Also: forgetSnapshotForGlobalID, forgetSnapshotsForGlobalIDs, recordSnapshotForGlobalID, recordSnapshots, recordSnapshotForSourceGlobalID, recordToManySnapshots:


forgetSnapshotForGlobalID

public void forgetSnapshotForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)

Clears the snapshot made for the enterprise object identified by globalID and posts an ObjectsChangedInStoreNotification (defined in the EOControl framework's EOObjectStore class) describing the invalidated object. For a description of snapshots and their role in an application, see the class description.

See Also: forgetSnapshotsForGlobalIDs, forgetAllSnapshots, recordSnapshotForGlobalID


forgetSnapshotsForGlobalIDs

public void forgetSnapshotsForGlobalIDs(NSArray globalIDs)

Clears the snapshots made for the enterprise objects identified by each of the EOGlobalIDs in globalIDs and posts an ObjectsChangedInStoreNotification (defined in the EOControl framework's EOObjectStore class) describing the invalidated objects. For a description of snapshots and their role in an application, see the class description.

See Also: forgetSnapshotForGlobalID, forgetAllSnapshots, recordSnapshots


handleDroppedConnection

public void handleDroppedConnection()

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

You should never invoke this method; it's invoked automatically by the Framework.


incrementSnapshotCountForGlobalID

public void incrementSnapshotCountForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)

Increments the reference count for the shared snapshot associated with globalID if the receiver releases unreferenced snapshots. (Does nothing if the receiver doesn't release snapshots.)

invalidateResultCache

public void invalidateResultCache()

Invalidates the receiver's result cache. See the class description for more discussion of this topic.

See Also: invalidateResultCacheForEntityNamed, resultCacheForEntityNamed


invalidateResultCacheForEntityNamed

public void invalidateResultCacheForEntityNamed(String entityName)

Invalidates the result cache containing an array of globalIDs for the objects associated with the entity entityName. See the class description for more discussion of this topic.

See Also: invalidateResultCache, resultCacheForEntityNamed


models

public NSArray models()

Returns the receiver's EOModels.

See Also: EODatabase constructor, addModel, addModelIfCompatible, removeModel


recordSnapshotForGlobalID

public void recordSnapshotForGlobalID( NSDictionary aSnapshot, com.apple.yellow.eocontrol.EOGlobalID globalID)

Records aSnapshot under globalID. For a description of snapshots and their role in an application, see the class description.

See Also: globalIDForRow ( EOEntity), recordSnapshots, forgetSnapshotForGlobalID


recordSnapshotForSourceGlobalID

public void recordSnapshotForSourceGlobalID( NSArray globalIDs, com.apple.yellow.eocontrol.EOGlobalID globalID, String name)

For the object identified by globalID, records an NSArray of globalIDs for the to-many relationship named name. These globalIDs identify the objects at the destination of the relationship. For a description of snapshots and their role in an application, see the class description.

See Also: recordSnapshotForGlobalID, recordSnapshots, recordSnapshotForGlobalID, snapshotForSourceGlobalID:relationshipName:


recordSnapshots

public void recordSnapshots(NSDictionary snapshots)

Records the snapshots in snapshots. snapshots is a dictionary whose keys are EOGlobalIDs and whose values are the snapshots for those global IDs. For a description of snapshots and their role in an application, see the class description.

See Also: recordSnapshotForGlobalID, forgetSnapshotsForGlobalIDs


recordToManySnapshots:

public void recordToManySnapshots(NSDictionary snapshots)

Records the objects in snapshots. snapshots should be an NSDictionary of NSDictionaries, in which the top-level dictionary has as its key the globaID 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. For a description of snapshots and their role in an application, see the class description.

See Also: recordSnapshotForSourceGlobalID, recordSnapshotForGlobalID, snapshotForSourceGlobalID:relationshipName:


registerContext

public void registerContext(EODatabaseContext aContext)

Records aContext as one of the receiver's EODatabaseContexts. The receiver must have been specified as aContext's EODatabase in the EODatabaseContext constructor (which invokes this method automatically). You should never need to invoke this method directly.

See Also: unregisterContext, registeredContexts


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.

See Also: registerContext, unregisterContext


removeModel

public void removeModel(EOModel aModel)

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

See Also: addModel, addModelIfCompatible, models


resultCacheForEntityNamed

public NSArray resultCacheForEntityNamed(String entityName)

Returns an array containing the globalIDs of the objects associated with entityName. See the class description for more discussion of this topic.

See Also: invalidateResultCache, invalidateResultCacheForEntityNamed


setResultCacheForEntityWithName

public void setResultCacheForEntityWithName( NSArray cache, String entityName)

Updates the receiver's cache for entityName with cache, an array of EOGlobalID objects, for all the enterprise objects associated with the EOEntity named entityName. This method is invoked automatically, and you should never need to invoke it directly. For more information on this topic, see the class description.

See Also: invalidateResultCache, invalidateResultCacheForEntityNamed, resultCacheForEntityNamed


setTimestampToNow

public void setTimestampToNow()

Sets the internal timestamp to the value returned by NSDate's timeIntervalSinceReferenceDate method. Used for recording subsequent snapshots.

snapshotForGlobalID

public NSDictionary snapshotForGlobalID( com.apple.yellow.eocontrol.EOGlobalID globalID, double timestamp)

public NSDictionary snapshotForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalID)

Returns the snapshot associated with globalID. Returns null if there isn't a snapshot for the globalID or if the corresponding timestamp is less than timestamp. If timestamp isn't provided, DistantPastTimeInterval is used. For a description of snapshots and their role in an application, see the class description.

See Also: recordSnapshotForGlobalID, forgetSnapshotForGlobalID


snapshotForSourceGlobalID

public NSArray snapshotForSourceGlobalID( com.apple.yellow.eocontrol.EOGlobalID globalID, String name, double timestamp)

public NSArray snapshotForSourceGlobalID( com.apple.yellow.eocontrol.EOGlobalID globalID, String name)

Returns the to-many snapshot for globalId and name. A to-many snapshot is an array of globalIDs. These globalIDs identify the objects at the destination of the to-many relationship named name, which is a property of the object identified by globalID. Returns null if there isn't a to-many snapshot for globalId or if the timestamp is less than timestamp. If timestamp isn't provided, DistantPastTimeInterval is used. For a description of snapshots and their role in an application, see the class description.

snapshots

public NSDictionary snapshots()

Returns all of the receiver's snapshots, stored in a dictionary under their EOGlobalIDs.

See Also: recordSnapshotForSourceGlobalID, recordToManySnapshots:


timestampForGlobalID

public double timestampForGlobalID(com.apple.yellow.eocontrol.EOGlobalID globalId)

Returns the timestamp of the snapshot for globalID. Returns EODistantPastTimeInterval if there isn't a snapshot.

timestampForSourceGlobalID

public double timestampForSourceGlobalID( com.apple.yellow.eocontrol.EOGlobalID globalId, String relationshipName)

Returns the timestamp of the to-many snapshot for the relationship specified by relationshipName and the object specified by globalID. Returns EODistantPastTimeInterval if there isn't a snapshot.

unregisterContext

public void unregisterContext(EODatabaseContext aContext)

Removes aContext as one of the receiver's EODatabaseContexts. An EODatabaseContext automatically invokes this method when it's finalized; you should never need to invoke it directly.

See Also: registerContext, registeredContexts



Table of Contents