com.webobjects.eoaccess
Class EOModel

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

All Implemented Interfaces:

NSDisposable

public class EOModel

extends Object

implements NSDisposable

An EOModel represents a mapping between a database schema and a set of classes based on the entity-relationship model for an application. The model contains a number of EOEntity objects representing the tables (entities) of the database schema. Each EOEntity object has a number of EOAttribute and EORelationship objects representing the properties (columns or fields) of the table (entity) in the database schema.

An EOModel maintains a mapping between each of its EOEntity objects and a corresponding Enterprise Object class for use with the database level of the Enterprise Objects Framework. You can determine the EOEntity for a particular Enterprise Object with the entityForObject method.

An EOModel is specific to a particular database server, and can store information needed to connect to that server as well as the name of an adaptor framework to load so that the Enterprise Objects Framework can communicate with the database.

Models can be organized into model groups and may have relationships that reference other models in the same model group. The other models may map to different databases and types of servers.

Creating an EOModel Programmatically

EOModel files are usually built using the EOModeler application, but it is possible to build an EOModel file programmatically if needed. The EOAdaptorChannel class declares methods for reading basic schema information from a relational database. You can use this information to build up an EOModel programmatically, and then enhance that model by defining extra relationships, flattening attributes, and so on.

Loading a Model File

EOModel files are typically stored in a project or a framework. To load an EOModel, provide a model file's path to the constructor. Note that loading an EOModel doesn't have the effect of loading all of its entities. EOModel files can be quite large, so to reduce start-up time, entity definitions are only loaded as needed. This incremental model loading is possible because an EOModel actually consists of one index file and two files for each entity. Models have an .eomodeld file wrapper ( which is actually a directory), and the individual entity files within the model are in ASCII format. The index file has the name index.eomodeld, and it contains the connection dictionary, the adaptor name, and a list of all of the entities in the model. This is the file that is loaded when you create a new model from a path.

The two entity files consist of a property list (.plist) file that describes the entity and a fetch specification (.fspec) file that describes any named fetch specifications for that entity.

Some of the EOModel methods contain the string "TableOfContents". An EOModel's table of contents corresponds to its index.eomodeld file, which is used to access the model's entities.

When an entity is loaded, EOModel posts an EntityLoadedNotification.

See Also:

entityForObject(EOEnterpriseObject object)

Field Summary

static String

EntityLoadedNotification The notification posted after an EOEntity is loaded into memory.

Constructor Summary

	EOModel() Creates and returns a new EOModel.
protected	EOModel(NSDictionary propertyList, String path)
protected	EOModel(NSDictionary propertyList, URL url)
	EOModel(String path) Deprecated. use EOModel(URL url) instead.
	EOModel(URL url)

Method Summary

String	adaptorName() Returns the name of the adaptor for the receiver.
void	addEntity(EOEntity entity) Adds entity to the receiver.
void	addStoredProcedure(EOStoredProcedure storedProcedure) Adds storedProcedure to the receiver.
NSArray	availablePrototypeAttributeNames() Returns a list of names of all available prototypes.
void	beautifyNames() Makes all of the receiver's named components conform to a standard convention.
NSDictionary	connectionDictionary() Returns a dictionary containing information used to connect to the database server.
void	dispose() Conformance to NSDisposable.
void	encodeTableOfContentsIntoPropertyList(NSMutableDictionary result) Encodes the receiver into result.
NSArray	entities() Returns an array containing the receiver's entities.
NSArray	entitiesWithSharedObjects() Returns an array of entities that have objects to load into a shared editing context.
EOEntity	entityForObject(EOEnterpriseObject object) Returns the entity associated with object, whether object is an instance of an Enterprise Object class, an instance of EOGenericRecord, or a fault.
EOEntity	entityNamed(String name) Returns the entity named name, or null if no such entity exists in this model.
NSArray	entityNames() Returns an array containing the names of the receiver's entities.
NSArray	externalModelsReferenced() Returns an array containing those models that are referenced by the receiver.
void	loadAllModelObjects() Loads any of the receiver's entities, stored procedures, attributes, and relationships that have not yet been loaded.
EOModelGroup	modelGroup() Returns the model group to which the receiver belongs.
String	name() Returns the receiver's name.
String	path() Deprecated. use pathURL instead.
URL	pathURL() Returns the URL to the EOModel file used to create the receiver, or null if the model wasn't initialized from an URL.
EOAttribute	prototypeAttributeNamed(String name) Returns the prototype attribute identified by name.
NSArray	referencesToProperty(Object property) Returns an array of all properties in the receiver that reference property, whether derived attributes, relationships that reference property, and so on.
void	removeEntity(EOEntity entity) Removes entity from the receiver without performing any referential integrity checking.
void	removeEntityAndReferences(EOEntity entity) Removes entity from the receiver along with any attributes or relationships in other entities that reference entity.
void	removeStoredProcedure(EOStoredProcedure storedProcedure) Removes storedProcedure from the receiver without checking whether any entity uses it.
void	setAdaptorName(String adaptorName) Sets the name of the receiver's adaptor to adaptorName.
void	setConnectionDictionary(NSDictionary connectionDictionary) Sets the dictionary containing information used to connect to the database to connectionDictionary.
void	setModelGroup(EOModelGroup group) Sets the model group to which the receiver should belong.
void	setName(String newName) Sets the name of the receiver to newNname.
void	setUserInfo(NSDictionary dictionary) Sets the receiver's userInfo dictionary to dictionary.
EOStoredProcedure	storedProcedureNamed(String name) Returns the stored procedure named name, or null if the receiver doesn't contain a stored procedure with the given name.
NSArray	storedProcedureNames() Returns an array containing the names of all of the receiver's stored procedures sorted in alphabetical order.
NSArray	storedProcedures() Returns an array containing all of the receiver's stored procedures or an empty array if the receiver has no stored procedures.
String	toString() Returns a string representation of the receiver.
NSDictionary	userInfo() Returns a dictionary of user data.
void	writeToFile(String path) Writes out the model archive representation of the receiver in the location specified by path.

Methods inherited from class java.lang.Object

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

Field Detail

EntityLoadedNotification

public static final String EntityLoadedNotification

The notification posted after an EOEntity is loaded into memory. This notification contains:
Notification Object The entity that was loaded. Userinfo None

Constructor Detail

EOModel

public EOModel()

Creates and returns a new EOModel.

EOModel

public EOModel(String path)

Deprecated. use EOModel(URL url) instead.

Creates a new EOModel object by reading the contents of the model archive identified by path. Sets the EOModel's name and path from the context of the model archive. Throws an IllegalArgumentException if path is null or if unable to read the file at path. Throws a runtime exception if unable for any other reason to initialize the model from the specified file path; the error text indicates the nature of the exception.

Parameters:

path - The path to a model archive.

Throws:

IllegalArgumentException - if path is null or if unable to read the file.

See Also:

EOModel(URL url), name(), path(), (NSMutableDictionary propertyList)

EOModel

public EOModel(URL url)

EOModel

protected EOModel(NSDictionary propertyList,
                  String path)

EOModel

protected EOModel(NSDictionary propertyList,
                  URL url)

Method Detail

adaptorName

public String adaptorName()

Returns the name of the adaptor for the receiver. This name can be used with EOAdaptor's static method adaptorWithName to construct an adaptor.

Returns:

The name of the adaptor for the receiver.

See Also:

EOAdaptor.adaptorWithName(String name)

addEntity

public void addEntity(EOEntity entity)

Adds entity to the receiver. Throws an exception if:

• entity is null.
• entity's EOModel is not the receiver.
• The receiver already has an entity with the same name as entity.

Parameters:

entity - An EOEntity object to add to the receiver.

Throws:

IllegalArgumentException - if entity is null, has a different EOModel, or has the same name as another entity registered with the receiver.

See Also:

entities(), removeEntity(EOEntity name), removeEntityAndReferences(EOEntity entity)

addStoredProcedure

public void addStoredProcedure(EOStoredProcedure storedProcedure)

Adds storedProcedure to the receiver. Throws an exception if:

• storedProcedure is null.
• storedProcedure's EOModel is not the receiver.
• storedProcedure does not have a valid name.
• The receiver already has a stored procedure with the same name as storedProcedure.

Parameters:

storedProcedure - An EOStoredProcedure object to add to the receiver.

Throws:

IllegalArgumentException - if storedProcedure is null, has a different EOModel, has an invalid name, or has the same name as another stored procedure registered with the receiver.

See Also:

removeStoredProcedure(EOStoredProcedure storedProcedure), storedProcedures(), storedProcedureNamed(String name)

availablePrototypeAttributeNames

public NSArray availablePrototypeAttributeNames()

Returns a list of names of all available prototypes.

Returns:

An array of available prototypes' names.

See Also:

prototypeAttributeNamed(String attributeName)

beautifyNames

public void beautifyNames()

Makes all of the receiver's named components conform to a standard convention. Names that conform to this style are all lower-case except for the initial letter of each embedded word other than the first, which is upper-case. Thus, NAME becomes name, and FIRST_NAME becomes firstName.

See Also:

EOEntity.nameForExternalName(String name, String separatorString , boolean initialCaps), name(), EOEntity.beautifyName(), EOAttribute.beautifyName(), EORelationship.beautifyName(), EOStoredProcedure.beautifyName()

connectionDictionary

public NSDictionary connectionDictionary()

Returns a dictionary containing information used to connect to the database server. The connection dictionary is the place to specify default login information for applications using the receiver as their model.

Returns:

The receiver's connection dictionary.

See Also:

EOAdaptor

dispose

public void dispose()

Conformance to NSDisposable.

Specified by:

dispose in interface NSDisposable

encodeTableOfContentsIntoPropertyList

public void encodeTableOfContentsIntoPropertyList(NSMutableDictionary result)

Encodes the receiver into result. This method is used to create an ASCII representation of an EOModel in property list format.

Parameters:

result - The dictionary into which to encode the receiver.

See Also:

EOModel(), EOModel(String path), EOModel(NSDictionary tableOfContents, String path)

entities

public NSArray entities()

Returns an array containing the receiver's entities. Note that this method loads every entity, and thus defeats the benefits of incremental model loading.

Returns:

An array of all the receiver's entities.

See Also:

entityNames()

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 load objects into a shared editing context.

See Also:

EOEditingContext

entityForObject

public EOEntity entityForObject(EOEnterpriseObject object)

Returns the entity associated with object, whether object is an instance of an Enterprise Object class, an instance of EOGenericRecord, or a fault. Returns null if object has no associated entity.

Parameters:

object - An object.

Returns:

The entity associated with object, or null.

entityNamed

public EOEntity entityNamed(String name)

Returns the entity named name, or null if no such entity exists in this model. Posts an EntityLoadedNotification when the entity is loaded. Throws a runtime exception if an error occurs during loading; the error text indicates the nature of the exception.

Parameters:

name - The name of an entity.

Returns:

The entity identified by name, or null.

See Also:

EntityLoadedNotification, entityNames(), entities()

entityNames

public NSArray entityNames()

Returns an array containing the names of the receiver's entities.

Returns:

An array of the names of the receiver's entities.

See Also:

entities(), entityNamed(String name)

externalModelsReferenced

public NSArray externalModelsReferenced()

Returns an array containing those models that are referenced by the receiver.

Returns:

An array of models referenced by the receiver.

See Also:

referencesToProperty(Object aProperty)

loadAllModelObjects

public void loadAllModelObjects()

Loads any of the receiver's entities, stored procedures, attributes, and relationships that have not yet been loaded.

See Also:

entities(), storedProcedures(), EOEntity.attributes(), EOEntity.relationships()

modelGroup

public EOModelGroup modelGroup()

Returns the model group to which the receiver belongs.

Returns:

The receiver's model group.

See Also:

setModelGroup(EOModelGroup group), EOModelGroup

name

public String name()

Returns the receiver's name.

Returns:

The receiver's name.

See Also:

path(), EOModel(String path), EOModel(NSDictionary tableOfContents, String path)

path

public String path()

Deprecated. use pathURL instead.

Returns:

The name of the EOModel file used to create the receiver, or null.

See Also:

pathURL()

pathURL

public URL pathURL()

Returns the URL to the EOModel file used to create the receiver, or null if the model wasn't initialized from an URL.

Returns:

The name of the EOModel file used to create the receiver, or null.

See Also:

name(), EOModel(String path), EOModel(NSDictionary tableOfContents, String path)

prototypeAttributeNamed

public EOAttribute prototypeAttributeNamed(String name)

Returns the prototype attribute identified by name. Looks first in the receiver, then in the model group to which the receiver belongs, and finally in the adaptor associated with the receiver.

Parameters:

name - An attribute name.

Returns:

The prototype attribute for the given name.

See Also:

availablePrototypeAttributeNames()

referencesToProperty

public NSArray referencesToProperty(Object property)

Returns an array of all properties in the receiver that reference property, whether derived attributes, relationships that reference property, and so on. Returns null if property isn't referenced by any of the properties in the model.

Parameters:

property - The name of a property.

Returns:

An array of all properties in the receiver that reference property.

See Also:

externalModelsReferenced()

removeEntity

public void removeEntity(EOEntity entity)

Removes entity from the receiver without performing any referential integrity checking.

Parameters:

entity - An EOEntity object to remove from the receiver.

See Also:

addEntity(EOEntity anEntity), removeEntityAndReferences(EOEntity entity)

removeEntityAndReferences

public void removeEntityAndReferences(EOEntity entity)

Removes entity from the receiver along with any attributes or relationships in other entities that reference entity.

Parameters:

entity - An EOEntity object to remove from the receiver.

See Also:

addEntity(EOEntity anEntity), removeEntity(EOEntity entity)

removeStoredProcedure

public void removeStoredProcedure(EOStoredProcedure storedProcedure)

Removes storedProcedure from the receiver without checking whether any entity uses it.

Parameters:

storedProcedure - The stored procedure to remove from the receiver.

See Also:

addStoredProcedure(EOStoredProcedure storedProcedure), storedProcedures()

setAdaptorName

public void setAdaptorName(String adaptorName)

Sets the name of the receiver's adaptor to adaptorName.

Parameters:

adaptorName - The name of the receiver's adaptor.

setConnectionDictionary

public void setConnectionDictionary(NSDictionary connectionDictionary)

Sets the dictionary containing information used to connect to the database to connectionDictionary.

Parameters:

connectionDictionary - The information used to connect to the database.

See Also:

EOAdaptor, EOAdaptor.adaptorWithModel(EOModel model)

setModelGroup

public void setModelGroup(EOModelGroup group)

Sets the model group to which the receiver should belong. Note that you shouldn't change an EOModel's model group after it has been bound to other models in its group.

Parameters:

group - The model group to which the receiver should belong.

See Also:

modelGroup()

setName

public void setName(String newName)

Sets the name of the receiver to newNname.

Parameters:

newName - A new name for the receiver.

setUserInfo

public void setUserInfo(NSDictionary dictionary)

Sets the receiver's userInfo dictionary to dictionary. User information is arbitrary auxiliary data which the application can use for whatever it needs. dictionary can only contain property list data types, which are String, NSDictionary, NSArray, and NSData.

Parameters:

dictionary - A dictionary of auxiliary data for the application to use as it needs.

storedProcedureNamed

public EOStoredProcedure storedProcedureNamed(String name)

Returns the stored procedure named name, or null if the receiver doesn't contain a stored procedure with the given name. Throws a runtime exception if an error occurs during processing; the error text indicates the nature of the exception. Throws an IllegalArgumentException if the model's index file (table of contents) contains name but the associated stored procedure is not found in the model's .eomodeld directory.

Parameters:

name - The name of a stored procedure.

Returns:

The stored procedure identified by name, or null.

Throws:

IllegalArgumentException - if the model file is corrupted.

See Also:

storedProcedureNames(), storedProcedures(), EOStoredProcedure

storedProcedureNames

public NSArray storedProcedureNames()

Returns an array containing the names of all of the receiver's stored procedures sorted in alphabetical order. Throws a runtime exception if an error occurs during processing; the error text indicates the nature of the exception.

Returns:

An alphabetically sorted array of the names of all of the receiver's stored procedures.

See Also:

storedProcedures(), storedProcedureNamed(String name), EOStoredProcedure

storedProcedures

public NSArray storedProcedures()

Returns an array containing all of the receiver's stored procedures or an empty array if the receiver has no stored procedures. Note that this method loads each of the model's stored procedures, thus defeating the benefits of incremental model loading.

Returns:

An array of all of the model's stored procedures, or an empty array.

See Also:

storedProcedureNames(), storedProcedureNamed(String name), EOStoredProcedure

toString

public String toString()

Returns a string representation of the receiver.

Overrides:

toString in class Object

Returns:

A string representation of the receiver.

userInfo

public NSDictionary userInfo()

Returns a dictionary of user data. You can use this to store any auxiliary information your application needs. Returns an empty dictionary if no user information has been set.

Returns:

A dictionary of arbitrary user data.

See Also:

setUserInfo(NSDictionary dictionary)

writeToFile

public void writeToFile(String path)

Writes out the model archive representation of the receiver in the location specified by path. If the directory specified by path already exists, a backup copy is first created from the existing archive with a tilde (~) character appended to the archive name to distinguish it. As a side-effect, this method resets the current path for the receiver to path.

Throws a runtime exception if unable to write the archive; the error text indicates the nature of the exception.

Parameters:

path - The filesystem location at which to write the model archive.

See Also:

path()