com.webobjects.eoaccess
Class EODatabaseDataSource

java.lang.Object
  com.webobjects.eocontrol.EODataSource
      com.webobjects.eoaccess.EODatabaseDataSource

All Implemented Interfaces:

EOKeyValueArchiving, EOKeyValueArchiving.Awaking, NSCoding, Serializable

public class EODatabaseDataSource
extends EODataSource
implements Serializable, EOKeyValueArchiving, EOKeyValueArchiving.Awaking, NSCoding

EODatabaseDataSource is a concrete subclass of EODataSource, defined in EOControl. EODatabaseDataSource fetches objects based on an EOModel, using an EODatabaseContext that services the data source's EOEditingContext. An EODatabaseDataSource can be set up to fetch all objects for its root entity or to fetch objects matching a particular EOFetchSpecification, and to further filter its fetching with an auxiliary qualifier.

EODatabaseDataSource implements all the functionality defined by EODataSource. In addition to fetching objects, it can insert and delete them (provided the entity isn't read-only). As with other data sources, EODatabaseDataSource can also provide a detail data source.

See Also:

EODataSource, EODetailDataSource, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.webobjects.eocontrol.EOKeyValueArchiving

EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSCoding

NSCoding.Support

Constructor Summary

EODatabaseDataSource(EOEditingContext anEditingContext, String anEntityName)
Constructs a new EODatabaseDataSource to fetch all objects for the EOEntity specified by anEntityName into anEditingContext .

EODatabaseDataSource(EOEditingContext anEditingContext, String anEntityName, String fetchSpecificationName)
Constructs a new EODatabaseDataSource to fetch objects into anEditingContext for the EOEntity specified by anEntityName using the fetch specification fetchSpecificationName.

Method Summary

EOQualifier	auxiliaryQualifier() Returns the auxiliary EOQualifier used to further restrict the fetch criteria defined by the receiver's EOFetchSpecification.
void	awakeFromKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver) Finishes initialization of a data source unarchived from EOKeyValueArchiving.
void	awakeFromNib() Finishes initialization of a data source from a nib file.
EOClassDescription	classDescriptionForObjects() Returns the class description for the root entity of the receiver.
Class	classForCoder() Conformance to NSCoding.
Object	createObject() Creates a new object, inserts it in the receiver's collection of objects if appropriate, and returns the object.
EODatabaseContext	databaseContext() Returns the EODatabaseContext that is used to access the external database.
EODataSource	dataSourceQualifiedByKey(String key) Returns a detail data source that provides the destination objects of the relationship named by key.
static Object	decodeObject(NSCoder coder) Decodes and returns an EODatabaseDataSource using coder.
static Object	decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver) Conformance to EOKeyValueArchiving.
void	deleteObject(Object object) Deletes object from the data source.
EOEditingContext	editingContext() Returns the EOEditingContext into which objects from this data source are fetched.
void	encodeWithCoder(NSCoder coder) Conformance to NSCoding.
void	encodeWithKeyValueArchiver(EOKeyValueArchiver archiver) Conformance to EOKeyValueArchiving.
EOEntity	entity() Returns the root entity of the receiver.
NSArray	fetchObjects() Fetches and returns an array of objects using the fetch specification and editing context associated with this datasource.
EOFetchSpecification	fetchSpecification() Returns the receiver's EOFetchSpecification or null if no fetch specification is set.
EOFetchSpecification	fetchSpecificationForFetch() Returns a copy of the effective fetch specification, which is the union of the primary fetch specification and the auxiliary qualifier.
String	fetchSpecificationName() Returns the name of the receiver's fetch specification or null if the data source is not using a named fetch specification.
void	insertObject(Object object) The default implementation does nothing.
boolean	isFetchEnabled() Returns true if fetching is enabled, false otherwise.
NSArray	qualifierBindingKeys() Returns an array of strings which is a union of the binding keys from the fetch specification's qualifier and the data source's auxiliary qualifier, or NSArray.EmptyArray if there are no bindings.
NSDictionary	qualifierBindings() Returns a dictionary of bindings to be used for variable replacement on the fetch specification's qualifier and the auxiliary qualifier before the fetch is executed.
void	qualifyWithRelationshipKey(String key, Object sourceObject) Sets the primary qualifier for the fetch specification for the relationship named key owned by the enterprise object sourceObject.
void	setAuxiliaryQualifier(EOQualifier newQualifier) Sets the auxiliary qualifier to newQualifier.
void	setEditingContext(EOEditingContext editingContext) Used internally.
void	setFetchEnabled(boolean yn) Controls whether objects can be fetched by the receiver.
void	setFetchSpecification(EOFetchSpecification fetchSpec) Sets the fetch specification used when supplying objects to fetchSpec.
void	setFetchSpecificationByName(String fetchSpecificationName) Retrieves the fetch specification identified by fetchSpecificationName from the root EOEntity for the receiver and sets it as the receiver's fetch specification.
void	setParentDataSourceRelationshipKey(EODataSource parent, String key) Called from Interface Builder to reset the parent entity.
void	setQualifierBindings(NSDictionary bindings) Sets a dictionary of bindings to be used for variable replacement on the fetch specification's qualifier and the auxiliary qualifier before the fetch is executed.

Methods inherited from class java.lang.Object

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

Constructor Detail

EODatabaseDataSource

public EODatabaseDataSource(EOEditingContext anEditingContext,
                            String anEntityName,
                            String fetchSpecificationName)

Constructs a new EODatabaseDataSource to fetch objects into anEditingContext for the EOEntity specified by anEntityName using the fetch specification fetchSpecificationName. Finds the EOObjectStoreCoordinator for anEditingContext and searches for a channel that services the model of the entity. If one exists, the EODatabaseDataSource uses it. Otherwise, a new one is created for this EODatabaseDataSource.

fetchSpecificationName is used to find the fetch specification in the entity. If fetchSpecificationName is null, a new fetch specification is instantiated that will fetch all objects of the entity.

Parameters:

anEditingContext - The EOEditingContext into which to fetch objects.

anEntityName - The EOEntity for this data source.

fetchSpecificationName - The criteria to select and order a group of database records, or null.

EODatabaseDataSource

public EODatabaseDataSource(EOEditingContext anEditingContext,
                            String anEntityName)

Constructs a new EODatabaseDataSource to fetch all objects for the EOEntity specified by anEntityName into anEditingContext . Finds the EOObjectStoreCoordinator for anEditingContext and searches for a channel that services the model of the entity. If one exists, the EODatabaseDataSource uses it. Otherwise, a new one is created for this EODatabaseDataSource.

Parameters:

anEditingContext - The EOEditingContext into which to fetch objects.

anEntityName - The EOEntity for this data source.

Method Detail

classForCoder

public Class classForCoder()

Conformance to NSCoding.

Specified by:

classForCoder in interface NSCoding

Returns:

The class for NSCoding.

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Conformance to NSCoding.

Specified by:

encodeWithCoder in interface NSCoding

Parameters:

coder - An NSCoder object to encode the receiver.

See Also:

NSCoder

decodeObject

public static Object decodeObject(NSCoder coder)

Decodes and returns an EODatabaseDataSource using coder. For NSCoding conformance.

Parameters:

coder - The NSCoder object to decode the data source.

Returns:

The decoded EODatabaseDataSource object.

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)

Conformance to EOKeyValueArchiving.

Specified by:

encodeWithKeyValueArchiver in interface EOKeyValueArchiving

Parameters:

archiver - The EOKeyValueArchiver object with which to encode the receiver.

See Also:

EOKeyValueArchiver

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

Conformance to EOKeyValueArchiving.

Parameters:

unarchiver - The EOKeyValueArchiver object with which to encode the receiver.

Returns:

The unarchived EODatabaseDataSource object.

awakeFromKeyValueUnarchiver

public void awakeFromKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

Finishes initialization of a data source unarchived from EOKeyValueArchiving. For conformance to EOKeyValueArchiving.Awaking.

Specified by:

awakeFromKeyValueUnarchiver in interface EOKeyValueArchiving.Awaking

Parameters:

unarchiver - The EOKeyValueUnarchiver that decoded the receiver.

See Also:

EOKeyValueUnarchiver, EOKeyValueArchiving.FinishInitialization

awakeFromNib

public void awakeFromNib()

Finishes initialization of a data source from a nib file.

setEditingContext

public void setEditingContext(EOEditingContext editingContext)

Used internally. You never need to invoke this method.

editingContext

public EOEditingContext editingContext()

Returns the EOEditingContext into which objects from this data source are fetched.

Overrides:

editingContext in class EODataSource

Returns:

The editing context into which objects are fetched.

createObject

public Object createObject()

Description copied from class: EODataSource

Creates a new object, inserts it in the receiver's collection of objects if appropriate, and returns the object. Returns null if the receiver can't create the object or can't insert it. You should invoke insertObject after this method to actually add the new object to the receiver.

As a convenience, EODataSource's implementation sends the receiver's EOClassDescription a createInstanceWithEditingContext message to create the object. If this succeeds and the receiver has an EOEditingContext, it sends the EOEditingContext an insertObject message to register the new object with the EOEditingContext (note that this does not insert the object into the EODataSource). Subclasses that don't use EOClassDescriptions or EOEditingContexts should override this method without invoking the superclass's implementation.

Overrides:

createObject in class EODataSource

Returns:

null if the receiver can't create the object or can't insert it, otherwise returns the object

See Also:

EODataSource.insertObject(Object object), EOClassDescription.createInstanceWithEditingContext( EOEditingContext editingContext, EOGlobalID globalID), EODataSource.classDescriptionForObjects(), EODataSource.editingContext()

entity

public EOEntity entity()

Returns the root entity of the receiver. The objects this data source supplies are fetched for this entity.

Returns:

The root entity for this data source.

databaseContext

public EODatabaseContext databaseContext()

Returns the EODatabaseContext that is used to access the external database. This is either the root EOObjectStore for the editing context, or, if the root is an EOCooperatingObjectStore, it is the database context under that cooperating object store that services the EOModel containing the root EOEntity for this data source.

Returns:

The database context that used to access the database.

fetchSpecification

public EOFetchSpecification fetchSpecification()

Returns the receiver's EOFetchSpecification or null if no fetch specification is set. The fetch specification for a data source can be set with either setFetchSpecification or setFetchSpecificationByName.

Returns:

The fetch specification which is used by the receiver to fetch objects, or null.

See Also:

EODatabaseDataSource.setFetchSpecification(EOFetchSpecification fetchSpec), EODatabaseDataSource.setFetchSpecificationByName(String fetchSpecificationName)

setFetchSpecification

public void setFetchSpecification(EOFetchSpecification fetchSpec)

Sets the fetch specification used when supplying objects to fetchSpec. The primary EOQualifier is conjoined with the auxiliary EOQualifier when objects are fetched. This method also sets the fetchSpecificationName to null. To use a named fetch specification from an entity, invoke setFetchSpecificationByName.

Parameters:

fetchSpec - The criteria to select and order a group of database records.

See Also:

EODatabaseDataSource.setAuxiliaryQualifier(EOQualifier aQualifier), EODatabaseDataSource.fetchSpecificationForFetch(), (String fetchSpecificationName), EOFetchSpecification

setFetchSpecificationByName

public void setFetchSpecificationByName(String fetchSpecificationName)

Retrieves the fetch specification identified by fetchSpecificationName from the root EOEntity for the receiver and sets it as the receiver's fetch specification. Sets the receiver's fetch specification name to fetchSpecificationName. Throws an exception if unable to retrieve the named fetch specification from the root entity.

Parameters:

fetchSpecificationName - The name of the fetch specification to set as the receiver's fetch specification, obtained from the root entity.

Throws:

EOObjectNotAvailableException - if the root entity does not have a fetch specification named fetchSpecificationName.

See Also:

EODatabaseDataSource.fetchSpecification(), EODatabaseDataSource.fetchSpecificationName()

fetchSpecificationName

public String fetchSpecificationName()

Returns the name of the receiver's fetch specification or null if the data source is not using a named fetch specification.

Returns:

The name of the fetchspecification or null.

See Also:

EODatabaseDataSource.setFetchSpecification(EOFetchSpecification fetchSpec), EODatabaseDataSource.setFetchSpecificationByName(String fetchSpecificationName)

setAuxiliaryQualifier

public void setAuxiliaryQualifier(EOQualifier newQualifier)

Sets the auxiliary qualifier to newQualifier. The auxiliary qualifier usually adds restricting conditions to the primary qualifier and is useful for narrowing the scope of a data source without altering its primary qualifier. This is especially useful for setting a qualifier on a qualified peer data source, since a peer's primary qualifier specifies the matching criteria for the relationship for which it fetches.

Parameters:

newQualifier - The new auxiliary EOQualifier.

See Also:

EODatabaseDataSource.fetchSpecificationForFetch(), EODatabaseDataSource.fetchSpecification()

auxiliaryQualifier

public EOQualifier auxiliaryQualifier()

Returns the auxiliary EOQualifier used to further restrict the fetch criteria defined by the receiver's EOFetchSpecification.

Returns:

The auxiliary EOQualifier.

qualifierBindingKeys

public NSArray qualifierBindingKeys()

Returns an array of strings which is a union of the binding keys from the fetch specification's qualifier and the data source's auxiliary qualifier, or NSArray.EmptyArray if there are no bindings.

Returns:

An array of all the binding keys from both the primary and the auxiliary qualifier, or NSArray.EmptyArray.

setQualifierBindings

public void setQualifierBindings(NSDictionary bindings)

Sets a dictionary of bindings to be used for variable replacement on the fetch specification's qualifier and the auxiliary qualifier before the fetch is executed.

Parameters:

bindings - NSDictionary of qualifier bindings.

See Also:

EODatabaseDataSource.qualifierBindings()

qualifierBindings

public NSDictionary qualifierBindings()

Returns a dictionary of bindings to be used for variable replacement on the fetch specification's qualifier and the auxiliary qualifier before the fetch is executed.

Returns:

The dictionary of qualifier bindings.

setFetchEnabled

public void setFetchEnabled(boolean yn)

Controls whether objects can be fetched by the receiver. If yn is true, the method fetchObjects fetches objects from the external data source when invoked. If false, fetchObjects does not perform a fetch and returns an empty array.

Fetching is typically disabled when the data source is acting as a peer in a master-peer configuration and the master does not have an object selected. For example, EODatabaseDataSource's implementation of qualifyWithRelationshipKey invokes this method to enable or disable fetching based on whether a master object is provided.

Parameters:

yn - Boolean flag to determine whether fetching is enabled.

See Also:

EODatabaseDataSource.isFetchEnabled(), EODatabaseDataSource.qualifyWithRelationshipKey(String key, Object sourceObject)

isFetchEnabled

public boolean isFetchEnabled()

Returns true if fetching is enabled, false otherwise. Fetching is typically disabled in a master-peer configuration whenno object is selected in the master.

Returns:

true if fetching is enabled, false otherwise.

See Also:

EODatabaseDataSource.setFetchEnabled(boolean yn)

classDescriptionForObjects

public EOClassDescription classDescriptionForObjects()

Returns the class description for the root entity of the receiver.

Overrides:

classDescriptionForObjects in class EODataSource

Returns:

The class description for the root entity.

fetchSpecificationForFetch

public EOFetchSpecification fetchSpecificationForFetch()

Returns a copy of the effective fetch specification, which is the union of the primary fetch specification and the auxiliary qualifier. Modifying the returned fetch specification will not affect a subsequent call to fetchObjects. To permanently modify fetching behavior, use setFetchSpecification and/or setAuxiliaryQualifier to change the receiver's fetch specification and auxiliary qualifier.

Returns:

A copy of the effective fetch specification, or null.

See Also:

EODatabaseDataSource.fetchObjects(), EODatabaseDataSource.setFetchSpecification(EOFetchSpecification fetchSpec), EODatabaseDataSource.setAuxiliaryQualifier(EOQualifier aQualifier)

fetchObjects

public NSArray fetchObjects()

Fetches and returns an array of objects using the fetch specification and editing context associated with this datasource. Returns an NSArray.EmptyArray if fetching is not enabled; returns null if the receiver's fetch specification is null.

Overrides:

fetchObjects in class EODataSource

Returns:

An array of objects fetched from the datasource, an empty array, or null.

See Also:

EODatabaseDataSource.isFetchEnabled(), EODatabaseDataSource.setFetchEnabled(boolean flag)

insertObject

public void insertObject(Object object)

The default implementation does nothing.

Specified by:

insertObject in class EODataSource

Parameters:

object - An Enterprise Object to insert in the current editing context.

deleteObject

public void deleteObject(Object object)

Deletes object from the data source. If the receiver registers undos for the deletion, the receiver may receive a redundant insertObject call.

Specified by:

deleteObject in class EODataSource

Parameters:

object - An Enterprise Object to delete from the data source.

dataSourceQualifiedByKey

public EODataSource dataSourceQualifiedByKey(String key)

Returns a detail data source that provides the destination objects of the relationship named by key. The returned detail data source can be qualified by using qualifyWithRelationshipKey to set a specific master object or to change the relationship key.

Specified by:

dataSourceQualifiedByKey in class EODataSource

Parameters:

key - The name of the relationship.

Returns:

The detail data source for the relationship identified by key.

See Also:

EODataSource.qualifyWithRelationshipKey( String key, Object sourceObject)

qualifyWithRelationshipKey

public void qualifyWithRelationshipKey(String key,
                                       Object sourceObject)

Sets the primary qualifier for the fetch specification for the relationship named key owned by the enterprise object sourceObject. Throws an exception if:

• unable to find the source entity for sourceObject
• the source entity for sourceObject has no relationship named key
• unable to construct a qualifier for the relationship named key

Specified by:

qualifyWithRelationshipKey in class EODataSource

Parameters:

key - The name of the relationship to qualify.

sourceObject - The owner of the relationship named key. this must be an EOEnterpriseObject

Throws:

IllegalStateException - unable to find source entity or relationship or unable to build the qualifier.

See Also:

EODataSource.dataSourceQualifiedByKey(String key)

setParentDataSourceRelationshipKey

public void setParentDataSourceRelationshipKey(EODataSource parent,
                                               String key)

Called from Interface Builder to reset the parent entity. You should never invoke this method yourself.

Parameters:

parent - The master of the detail data source.

key - The name of the relationship.

See Also:

EODatabaseDataSource.qualifyWithRelationshipKey(String key, Object sourceObject)