com.webobjects.eoaccess
Class EOModelGroup

java.lang.Object
  |
  +--com.webobjects.eoaccess.EOModelGroup

public class EOModelGroup

extends Object

An EOModelGroup represents an aggregation of related models. When a model in the group needs to resolve a relationship to an entity in another model, it looks for that model in its group. Model groups allow applications to load entities and their properties only as they're needed, by distributing them among separate EOModels.

The default model group contains all models for an application, as well as any frameworks the application references. It is automatically created on demand. The entity name space among all of these models is global; consequently, the same entity name should not appear in any two of models in the group. All cross-model information is represented in the models by entity name only. Binding the entity name to an actual entity is done at runtime within the EOModelGroup.

In the majority of applications, the automatically created default model group is sufficient. If different model grouping semantics are needed, programmers can create their own model group instance, add whatever models they like, and then replace the default model group with their custom model group.

Setting Up A Model Group Programmatically

The following code demonstrates programmatic creation of a model group.

     String modelPath;//Assume this exists
     EOModelGroup group =new EOModelGroup();
     group.addModelWithPath(modelPath);
     EOModelGroup.setDefaultGroup(group);
 

Accessing Models Within a Model Group

Each model lives within a group and can form connections to other models in its group. EOModeler puts models with identical names in separate groups to allow you to load two models with the same name at the same time.

A model can find a related model by name using the statement this.modelGroup().modelNamed(name);.

A data source can locate a model using the statement: EOModelGroup.defaultGroup().modelNamed(name);.

EOModelGroup Delegates

Your EOModelGroup object should have a delegate which can influence how it finds and loads models. In addition to the delegates you assign to EOModelGroup instances, the EOModelGroup class itself can have a delegate. The class delegate implements a single method, defaultModelGroup. The instance delegate can implement the methods defined in the EOModelGroup.Delegate interface.

Note that the following delegate methods are set on EOModelGroup, rather than EOEntity, to provide a single point in the code where you can alter the database-to-objects mapping.

• classForObjectWithGlobalID
• failedToLookupClassNamed
• relationshipForRow
• subEntityForEntity

See Also:

EOModelGroup.ClassDelegate.defaultModelGroup(), EOModelGroup.Delegate.classForObjectWithGlobalID(EOEntity entity, EOGlobalID gid), EOModelGroup.Delegate.subEntityForEntity(EOEntity entity, NSDictionary dic), EOModelGroup.ClassDelegate, EOModelGroup, EOModel

Inner Class Summary

static interface	EOModelGroup.ClassDelegate This interface defines a delegate to the EOModelGroup class to allow modification of the creation of the default model group.
static interface	EOModelGroup.Delegate This interface defines a delegate to EOModelGroup to allow instances to modify how the model group finds and loads models.

Field Summary

static String	ModelAddedNotification Posted by an EOModelGroup when an EOModel is added to the group.
static String	ModelInvalidatedNotification Posted by an EOModelGroup when an EOModel is removed from the group.

Constructor Summary

EOModelGroup()
Creates and returns a new EOModelGroup.

Method Summary

void	addModel(EOModel model) Adds model to the receiving model group, sets the receiving model group as model's model group, and posts a ModelAddedNotification.
EOModel	addModelWithPath(String path) Creates and returns a new EOModel object from the contents of the model archive identified by path; may return null.
static Object	classDelegate() Returns EOModelGroup's class delegate.
static EOModelGroup	defaultGroup() Returns the default EOModelGroup, which is the same as the global EOModelGroup unless you have either explicitly set a default model group with setDefaultGroup or implemented the class delegate method defaultModelGroup to return a non-null value.
Object	delegate() Returns the receiver's instance delegate, which is different than the EOModelGroup class delegate.
NSArray	entitiesWithSharedObjects() Returns an array of entities that have objects to load into a shared editing context.
EOEntity	entityForObject(EOEnterpriseObject object) Returns the EOEntity associated with object from any of the models in the receiver that handle object, or null if none of the models in the receiver handle object.
EOEntity	entityNamed(String name) Searches each of the EOModels in the receiver for the entity specified by name, and returns the entity, if found, or null if unable to find the specified entity.
EOFetchSpecification	fetchSpecificationNamed(String fetchSpecName, String entityName) Returns the fetch specification identifed by fetchSpecName from the entity specified by entityName in the receiving model group.
static EOModelGroup	globalModelGroup() Returns an EOModelGroup composed of all models in the resource directory of the application, as well as those in all frameworks loaded into the application.
void	loadAllModelObjects() Invokes loadAllModelObjects on each of the receiver's EOModels, thereby loading any EOEntities, EOAttributes, EORelationships, and EOStoredProcedures that haven't yet been loaded from each of the EOModels in the receiver.
static EOModelGroup	modelGroupForObjectStoreCoordinator(EOObjectStoreCoordinator objectCoord) Returns the EOModelGroup used by the EOObjectStoreCoordinator objectCoord.
EOModel	modelNamed(String name) Returns the EOModel identifed by name if it is part of the receiving model group, or null if the receiver doesn't contain an EOModel with the specified name.
NSArray	modelNames() Returns an array containing the names of all of the EOModels in the receiver, or an empty array if the receiver contains no EOModels.
NSArray	models() Returns an array containing the receiver's EOModels, or an empty array if the receiver contains no EOModels.
EOModel	modelWithPath(String path) Returns the EOModel whose path is identical to path or null if the receiver does not contain an EOModel with the specified path.
void	removeModel(EOModel model) Removes model from the receiving model group and unbinds any references to model from other EOModels in the group.
static void	setClassDelegate(Object delegate) Assigns delegate as EOModelGroup's class delegate.
static void	setDefaultGroup(EOModelGroup group) Sets the default model group to group.
void	setDelegate(Object delegate) Sets the receiver's instance delegate to delegate.
static void	setModelGroupForObjectStoreCoordinator(EOObjectStoreCoordinator objectCoord, EOModelGroup group) Assigns group as the working model group for the EOObjectStoreCoordinator objectCoord.
EOStoredProcedure	storedProcedureNamed(String name) Searches each of the EOModels in the receiver for the stored procedure specified by name, and returns the stored procedure, if found, or null if unable to find the specified stored procedure.
String	toString() Returns a string representation of the model group.

Methods inherited from class java.lang.Object

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

Field Detail

ModelAddedNotification

public static final String ModelAddedNotification

Posted by an EOModelGroup when an EOModel is added to the group. This notification is sent, for instance, inside Interface Builder when the user has saved changes to a model in EOModeler and the objects in Interface Builder must be resynchronized. The old model is invalidated and recipients of the notification (like data sources) can invoke modelNamed to re-fetch their models.

Notification Object	The newly added model.
Userinfo	None

See Also:

modelNamed(String modelName)

ModelInvalidatedNotification

public static final String ModelInvalidatedNotification

Posted by an EOModelGroup when an EOModel is removed from the group. This notification is sent, for instance, inside Interface Builder when the user has saved changes to a model in EOModeler and the objects in Interface Builder must be resynchronized. The old model is invalidated and recipients of the notification (like data sources) can invoke modelNamed to re-fetch their models.

Notification Object	The invalidated model.
Userinfo	None

See Also:

modelNamed(String modelName)

Constructor Detail

EOModelGroup

public EOModelGroup()

Creates and returns a new EOModelGroup.

Method Detail

addModel

public void addModel(EOModel model)

Adds model to the receiving model group, sets the receiving model group as model's model group, and posts a ModelAddedNotification. Throws an exception if the receiver already contains an EOModel with the same name as model, of if there is a name conflict between entities in model and entities in any of the model group's other models.

Parameters:

model - A model to add to the receiver.

Throws:

IllegalStateException - if there is a name conflict between model and the receiver's current models, or between entities in model and entities in the receiver's current models.

See Also:

ModelAddedNotification

addModelWithPath

public EOModel addModelWithPath(String path)

Creates and returns a new EOModel object from the contents of the model archive identified by path; may return null. If a model can be created from path, adds the newly created model to the receiver.

Parameters:

path - The path to an EOModel archive.

Returns:

The new EOModel created from the archive at path, or null.

classDelegate

public static Object classDelegate()

Returns EOModelGroup's class delegate.

Returns:

EOModelGroup's class delegate.

See Also:

setClassDelegate(Object anObject), EOModelGroup.ClassDelegate

defaultGroup

public static EOModelGroup defaultGroup()

Returns the default EOModelGroup, which is the same as the global EOModelGroup unless you have either explicitly set a default model group with setDefaultGroup or implemented the class delegate method defaultModelGroup to return a non-null value.

Note: In WebObjects applications, the WOApplication instance assigns the WOApplication class as the EOModelGroup's class delegate. Its implementation of defaultModelGroup can return a different default model group than the one returned by this method.

Returns:

The default model group.

See Also:

classDelegate(), setDefaultGroup(EOModelGroup group), EOModelGroup.ClassDelegate.defaultModelGroup(), globalModelGroup()

delegate

public Object delegate()

Returns the receiver's instance delegate, which is different than the EOModelGroup class delegate. Each EOModelGroup object can have its own delegate in addition to the delegate that's assigned to the EOModelGroup class.

Returns:

The receiver's instance delegate.

See Also:

EOModelGroup.ClassDelegate, classDelegate(), setClassDelegate(Object anObject), EOModelGroup.Delegate

entitiesWithSharedObjects

public NSArray entitiesWithSharedObjects()

Returns an array of entities that have objects to load into a shared editing context.

Returns:

An array of entities that have objects to load into a shared editing context.

See Also:

EOEditingContext

entityForObject

public EOEntity entityForObject(EOEnterpriseObject object)

Returns the EOEntity associated with object from any of the models in the receiver that handle object, or null if none of the models in the receiver handle object.

Parameters:

object - An object for which to search in the receiver's models.

Returns:

The EOEntity associated with object, or null.

See Also:

EOModel.entityForObject(EOEnterpriseObject object)

entityNamed

public EOEntity entityNamed(String name)

Searches each of the EOModels in the receiver for the entity specified by name, and returns the entity, if found, or null if unable to find the specified entity.

Parameters:

name - The name of an entity for which to search in the receiver's models.

Returns:

The entity specified by name, or null.

See Also:

EOModel.entityNamed(String name)

fetchSpecificationNamed

public EOFetchSpecification fetchSpecificationNamed(String fetchSpecName,
                                                    String entityName)

Returns the fetch specification identifed by fetchSpecName from the entity specified by entityName in the receiving model group.

Parameters:

fetchSpecName - The name of a fetch specification for which to search in the entity named entityName.

entityName - The name of an EOEntity to search for a fetch specification named fetchSpecName.

Returns:

The specified fetch specification.

globalModelGroup

public static EOModelGroup globalModelGroup()

Returns an EOModelGroup composed of all models in the resource directory of the application, as well as those in all frameworks loaded into the application.

Returns:

An EOModelGroup comprising all available models.

See Also:

defaultGroup()

loadAllModelObjects

public void loadAllModelObjects()

Invokes loadAllModelObjects on each of the receiver's EOModels, thereby loading any EOEntities, EOAttributes, EORelationships, and EOStoredProcedures that haven't yet been loaded from each of the EOModels in the receiver.

See Also:

EOModel.loadAllModelObjects()

modelGroupForObjectStoreCoordinator

public static EOModelGroup modelGroupForObjectStoreCoordinator(EOObjectStoreCoordinator objectCoord)

Returns the EOModelGroup used by the EOObjectStoreCoordinator objectCoord.

Parameters:

objectCoord - A EOObjectStoreCoordinator.

Returns:

The EOModelGroup used by objectCoord.

See Also:

setModelGroupForObjectStoreCoordinator( EOObjectStoreCoordinator objectCoord, EOModelGroup group)

modelNamed

public EOModel modelNamed(String name)

Returns the EOModel identifed by name if it is part of the receiving model group, or null if the receiver doesn't contain an EOModel with the specified name.

Parameters:

name - The name of an EOModel for which to search in the receiver.

Returns:

The model identified by name, or null.

See Also:

setModelGroupForObjectStoreCoordinator( EOObjectStoreCoordinator objectCoord, EOModelGroup group)

modelNames

public NSArray modelNames()

Returns an array containing the names of all of the EOModels in the receiver, or an empty array if the receiver contains no EOModels. The order of the model names in the array isn't defined.

Returns:

An array of the names of all of the receiver's models.

modelWithPath

public EOModel modelWithPath(String path)

Returns the EOModel whose path is identical to path or null if the receiver does not contain an EOModel with the specified path. Paths are standardized before performing a String comparison to determine equality.

Parameters:

path - The path to an EOModel archive.

Returns:

The EOModel created from path, or null.

See Also:

EOModel.path()

models

public NSArray models()

Returns an array containing the receiver's EOModels, or an empty array if the receiver contains no EOModels. The order of the models in the array isn't defined.

Returns:

An array of all the receiver's EOModels, or an empty array.

removeModel

public void removeModel(EOModel model)

Removes model from the receiving model group and unbinds any references to model from other EOModels in the group. Posts a ModelInvalidatedNotification to the default notification center after removing model.

Parameters:

model - An EOModel to remove from the receiver.

See Also:

ModelInvalidatedNotification, models()

setClassDelegate

public static void setClassDelegate(Object delegate)

Assigns delegate as EOModelGroup's class delegate. The class delegate is optional; it allows modification of the creation of the default model group.

Parameters:

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

See Also:

classDelegate(), EOModelGroup.ClassDelegate

setDefaultGroup

public static void setDefaultGroup(EOModelGroup group)

Sets the default model group to group. If you have implemented the defaultModelGroup class delegate method to return a non-null value, the delegate's return value overrides the value set by this method.

Parameters:

group - A model group to set as the receiver's default model group.

See Also:

EOModelGroup.ClassDelegate.defaultModelGroup(), defaultGroup(), setClassDelegate(Object anObject)

setDelegate

public void setDelegate(Object delegate)

Sets the receiver's instance delegate to delegate. The EOModelGroup class may also have a class delegate set, which is independent of the instance delegate.

Parameters:

delegate - The object to set as the receiver's instance delegate.

See Also:

delegate(), classDelegate(), EOModelGroup.Delegate, EOModelGroup.ClassDelegate

setModelGroupForObjectStoreCoordinator

public static void setModelGroupForObjectStoreCoordinator(EOObjectStoreCoordinator objectCoord,
                                                          EOModelGroup group)

Assigns group as the working model group for the EOObjectStoreCoordinator objectCoord. By default, an EOObjectStoreCoordinator uses the default model group. You might want to assign a different model group to an EOObjectStoreCoordinator if you need to scope models to particular coordinators, if different models have the same name, or if different entities in some models have the same name.

Parameters:

objectCoord - An object store coordinator.

group - The model group to be used by objectCoord.

See Also:

defaultGroup(), modelGroupForObjectStoreCoordinator( EOObjectStoreCoordinator objectCoord)

storedProcedureNamed

public EOStoredProcedure storedProcedureNamed(String name)

Searches each of the EOModels in the receiver for the stored procedure specified by name, and returns the stored procedure, if found, or null if unable to find the specified stored procedure.

Parameters:

name - The name of a stored procedure for which to search in the receiver's models.

Returns:

The stored procedure specified by name, or null.

toString

public String toString()

Returns a string representation of the model group.

Overrides:

toString in class Object

Returns:

Returns a string representation of the model group.