com.webobjects.eoaccess
Class EOEntity

java.lang.Object
  com.webobjects.eoaccess.EOEntity

All Implemented Interfaces:

EOPropertyListEncoding, EOSQLExpression.SQLValue

public class EOEntity

extends Object

implements EOPropertyListEncoding, EOSQLExpression.SQLValue

An EOEntity describes a table in a database and associates a name internal to the Enterprise Objects Framework with an external name by which the table is known to the database. An EOEntity maintains a group of attributes and relationships, which are collectively called properties. These are represented by the EOAttribute and EORelationship classes, respectively.

You usually define entities in an EOModel using the EOModeler application. EOEntity objects are primarily used by the Enterprise Objects Framework for mapping tables in the database to Enterprise Objects in the application. You are not likely to interact with them directly unless you are specifically working with models.

An EOEntity is associated with a specific class whose instances are used to represent records (rows) from the database in applications using layers at or above the database layer of the Enterprise Objects Framework. If an EOEntity doesn't have a specific class associated with it, instances of EOGenericRecord are created.

An EOEntity may be marked as read-only, in which case any changes to rows or objects for that entity made by the database level objects are denied.

You can define an external query for an EOEntity to be used when a selection is attempted with an unrestricted qualifier (one that would select all rows in the entity's table). An external query is sent unaltered to the database server and so can use database-specific features such as stored procedures; external queries are thus useful for hiding records or invoking database-specific features. You can also assign stored procedures to be invoked upon particular database operations through the use of EOEntity's setStoredProcedure method.

Like the other major modeling classes, EOEntity provides a user dictionary for the application to store any application-specific information related to the entity.

Creating an Entity

An EOEntity requires at least the following to be usable:

• A name.
• The name of a table in the database (the external name).
• The name of an Enterprise Object class.
• A set of attributes to be used as the primary key.

Note that if an entity has no Enterprise Object class name, the database-level objects use EOGenericRecord.

See Also:

setStoredProcedure(EOStoredProcedure storedProcedure, String operation), EOAttribute, EORelationship, EOGenericRecord

Field Summary

static String	DeleteProcedureOperation A stored procedure to delete a row.
static String	FetchAllProcedureOperation A stored procedure to fetch all records.
static String	FetchWithPrimaryKeyProcedureOperation A stored procedure to fetch by primary key.
static String	InsertProcedureOperation A stored procedure to insert a row.
static String	NextPrimaryKeyProcedureOperation A stored procedure to generate a new primary key.

Constructor Summary

EOEntity()
Creates and returns a new EOEntity.

EOEntity(NSDictionary plist, Object owner)
Creates and returns a new EOEntity initialized from the property list plist belonging to the EOModel owner.

Method Summary

void	addAttribute(EOAttribute attribute) Adds attribute to the receiver and sets the receiver as the attribute's entity.
void	addFetchSpecification(EOFetchSpecification fetchSpec, String name) Adds the fetch specification fetchSpec to the receiver and associates name with it.
void	addRelationship(EORelationship relationship) Adds relationship to the receiver and sets the receiver as the relationship's entity.
void	addSharedObjectFetchSpecificationByName(String name) Adds the fetch specification identified by name to the set of fetch specifications used to load objects into a shared editing context.
void	addSubEntity(EOEntity child) Adds the EOEntity child as a sub-entity of the receiver.
EOAttribute	anyAttributeNamed(String name) Returns the user-created attribute identified by name.
EORelationship	anyRelationshipNamed(String relationshipName) Returns the user-created relationship identified by relationshipName.
EOAttribute	attributeNamed(String attributeName) Returns the attribute named attributeName, or null if no such attribute exists in the receiver.
NSArray	attributes() Returns an array containing all of the receiver's attributes, or null if the receiver has no attributes.
NSArray	attributesToFetch() Returns an array of the EOAttributes that need to be fetched so that they can be included in the row snapshot.
NSArray	attributesUsedForLocking() Returns an array containing those attributes used for locking, that is, those properties whose values must match a snapshot any time a row is updated.
void	awakeWithPropertyList(NSDictionary pl) EOEntity's implementation of this method does nothing.
void	beautifyName() Makes the receiver's name conform to a standard convention.
boolean	cachesObjects() Returns true if all of the objects from the receiver are to be cached in memory and queries are to be evaluated in memory using this cache rather than in the database.
EOClassDescription	classDescriptionForInstances() Returns the EOClassDescription associated with the receiver.
String	className() Returns the name of the Enterprise Object class associated with the receiver.
NSArray	classProperties() Returns an array containing the properties that are bound to the receiver's class (so that values corresponding to those properties are passed to instances of that class).
NSArray	classPropertyNames() Returns an array containing the names of those properties that are bound to the receiver's class (so that values corresponding to those properties are passed to instances of that class).
String	clientClassName() Returns the name of the client-side Enterprise Object class associated with the receiver.
NSArray	clientClassProperties() Returns an array containing the properties that are bound to the client-side class corresponding to the receiver.
NSArray	clientClassPropertyNames() Returns an array containing the names of the properties that are bound to the client-side class corresponding to the entity.
void	encodeIntoPropertyList(NSMutableDictionary result) Encodes the receiver as a property list.
NSArray	externalModelsReferenced() Examines each of the receiver's relationships and returns a list of all external models referenced by the receiver, or an empty arrray if no external models are referenced.
String	externalName() Returns the name of the receiver as understood by the database server, that is, the receiver's external name.
static String	externalNameForInternalName(String internalName, String separatorString, boolean allCaps) Used by the Enterprise Objects Framework to convert an internal object name, internalName to a database schema name that conforms to a standard convention, separating name elements with separatorString and capitalizing or lowercasing the external name based on the Boolean parameter allCaps.
String	externalQuery() Returns a query statement that is used by an EOAdaptorChannel to select rows for the entity when a qualifier is empty, or null if the entity has no external query.
EOFetchSpecification	fetchSpecificationNamed(String fetchSpecName) Returns the fetch specification identified by fetchSpecName.
NSArray	fetchSpecificationNames() Returns an alphabetically sorted array of the names of the receiver's fetch specifications.
EOGlobalID	globalIDForRow(NSDictionary row) Constructs a unique global identifier for the receiver from the keys and values in the dictionary row, which represents a database row.
boolean	isAbstractEntity() Returns true if the receiver is an abstract entity, false otherwise.
boolean	isPrimaryKeyValidInObject(NSKeyValueCoding object) Returns true if every key attribute is present in object and has a value that is not null.
boolean	isQualifierForPrimaryKey(EOQualifier qualifier) Returns true if qualifier describes the primary key and nothing but the primary key, false otherwise.
boolean	isReadOnly() Returns true if the receiver can not be modified, false if it can.
boolean	isValidAttributeUsedForLocking(EOAttribute anAttribute) Returns true if anAttribute can be used for locking, false otherwise.
boolean	isValidClassProperty(Object aProp) Returns true if the property aProp is a valid class property of the receiver, false otherwise.
boolean	isValidPrimaryKeyAttribute(EOAttribute anAttribute) Returns false if anAttribute isn't an EOAttribute, doesn't belong to the entity or is derived.
int	maxNumberOfInstancesToBatchFetch() Returns the maximum number of to-one faults from the receiver to fire at one time.
EOModel	model() Returns the EOModel that contains the receiver.
String	name() Returns the receiver's name.
static String	nameForExternalName(String externalName, String separatorString, boolean initialCaps) Used by the Enterprise Objects Framework to convert a database schema name externalName to an internal object name that conforms to a standard convention, using the capitalization rule initialCaps and removing the character separatorString that separates name elements in the external name.
EOEntity	parentEntity() Returns the parent entity for the receiver, that is, the entity from which the receiver inherits.
NSArray	primaryKeyAttributeNames() Returns an array containing the names of the EOAttributes that make up the receiver's primary key.
NSArray	primaryKeyAttributes() Returns an array of those EOAttributes that make up the receiver's primary key.
NSDictionary	primaryKeyForGlobalID(EOGlobalID gid) Returns the primary key for the object identified by gid, or null if gid is not an instance of EOKeyGlobalID.
NSDictionary	primaryKeyForRow(NSDictionary row) Returns the primary key for row, or null if the primary key can't be computed.
String	primaryKeyRootName() Returns the external name (that is, the name understood by the database) of the receiver's root (parent) entity.
EOQualifier	qualifierForPrimaryKey(NSDictionary row) Returns a qualifier for the receiver that can be used to fetch an instance of the receiver with the primary key extracted from row.
boolean	referencesProperty(Object property) Returns true if any of the receiver's attributes or relationships reference property, false otherwise.
EORelationship	relationshipNamed(String relationshipName) Returns the relationship identified by relationshipName, or null if the receiver has no such relationship.
NSArray	relationships() Returns an array containing all of the receiver's relationships or null if the receiver has none.
void	removeAttribute(EOAttribute attribute) If attribute exists, removes it from the receiver.
void	removeFetchSpecificationNamed(String name) Removes the fetch specification identifed by name from the receiver.
void	removeRelationship(EORelationship relationship) If relationship exists, removes it from the receiver.
void	removeSharedObjectFetchSpecificationByName(String name) Removes the fetch specification identified by name from the set of fetch specifications used to load objects into a shared editing context.
void	removeSubEntity(EOEntity child) Removes the EOEntity child from the list of sub-entities that inherit from the receiver.
EOQualifier	restrictingQualifier() Returns the qualifier used to restrict all queries made against the receiver.
EOQualifier	schemaBasedQualifier(EOQualifier qualifier) Returns an SQL qualifier based on qualifier that is suitable for evaluation by a database (as opposed to in-memory evaluation).
boolean	setAttributesUsedForLocking(NSArray attributes) If all of the the EOAttributes in attributes can be used by an EODatabaseChannel to lock Enterprise Objects for updates, sets attributes as the receiver's attributes used for locking and returns true.
void	setCachesObjects(boolean flag) Based on the Boolean value flag, sets whether the receiver's Enterprise Objects are cached the first time the associated database table is queried.
void	setClassName(String name) Assigns name as the name of the Enterprise Object class associated with the receiver if name is not null.
boolean	setClassProperties(NSArray attributes) If all of the the EOAttributes in attributes are valid class properties of the receiver, sets attributes as the receiver's class properties and returns true.
void	setExternalName(String string) Sets the name of the receiver as understood by the database server (that is, the receiver's external name) to string.
void	setExternalQuery(String string) Assigns string as the query statement used for selecting rows from the entity when there is no qualifier.
void	setIsAbstractEntity(boolean flag) Based on the Boolean flag, sets whether the receiver is an abstract entity, false otherwise.
void	setMaxNumberOfInstancesToBatchFetch(int size) Sets the maximum number of faults from the entity to trigger at one time to size.
void	setName(String name) Sets the receiver's name to name.
boolean	setPrimaryKeyAttributes(NSArray attributes) If all of the the EOAttributes in attributes are valid primary keys of the receiver, sets attributes as the receiver's primary keys and returns true.
void	setReadOnly(boolean flag) Sets whether the receiver is read-only based on the Boolean value flag.
void	setRestrictingQualifier(EOQualifier qualifier) Assigns qualifier as the qualifier used to restrict all queries made against the receiver.
void	setSharedObjectFetchSpecificationsByName(NSArray names) Sets the names of the fetch specifications used to load objects into a shared editing context to names.
void	setStoredProcedure(EOStoredProcedure storedProcedure, String operation) Sets storedProcedure as a stored procedure for the receiver and associates with it the name operation, which must be one of the following: FetchAllProcedureOperation FetchWithPrimaryKeyProcedureOperation InsertProcedureOperation DeleteProcedureOperation NextPrimaryKeyProcedureOperation This information is used when changes from the object graph have been transformed into EODatabaseOperations that are being used to construct EOAdaptorOperations.
void	setUserInfo(NSDictionary dictionary) Sets the dictionary of auxiliary user data to dictionary.
NSArray	sharedObjectFetchSpecificationNames() Returns an array of strings, which are the names of the fetch specifications used to load objects into a shared editing context.
EOStoredProcedure	storedProcedureForOperation(String operation) Returns the stored procedure identified by the name operation, if one has been set.
NSArray	subEntities() Returns a list of those entities that inherit from the receiver, or an empty array if no entities inherit from the receiver.
String	toString() Returns a string representation of all the receiver's properties.
NSDictionary	userInfo() Returns a dictionary of user data.
String	valueForSQLExpression(EOSQLExpression context) Returns an SQL query string based on the receiver's external name and an EOSQLExpression object context.

Methods inherited from class java.lang.Object

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

Field Detail

DeleteProcedureOperation

public static final String DeleteProcedureOperation

A stored procedure to delete a row.

FetchAllProcedureOperation

public static final String FetchAllProcedureOperation

A stored procedure to fetch all records.

FetchWithPrimaryKeyProcedureOperation

public static final String FetchWithPrimaryKeyProcedureOperation

A stored procedure to fetch by primary key.

InsertProcedureOperation

public static final String InsertProcedureOperation

A stored procedure to insert a row.

NextPrimaryKeyProcedureOperation

public static final String NextPrimaryKeyProcedureOperation

A stored procedure to generate a new primary key.

Constructor Detail

EOEntity

public EOEntity()

Creates and returns a new EOEntity.

EOEntity

public EOEntity(NSDictionary plist,
                Object owner)

Creates and returns a new EOEntity initialized from the property list plist belonging to the EOModel owner. plist is dictionary containing only property list data types (that is, NSDictionary, NSArray, NSData, and String). This constructor is used by EOModeler when it reads in an EOModel from a file.

Parameters:

plist - A dictionary of property list values from which to initialize the new EOEntity object.

owner - The EOModel to which the newly created entity belongs.

See Also:

EOPropertyListEncoding.encodeIntoPropertyList(NSMutableDictionary propertyList), EOPropertyListEncoding.awakeWithPropertyList(NSDictionary propertyList)

Method Detail

addAttribute

public void addAttribute(EOAttribute attribute)

Adds attribute to the receiver and sets the receiver as the attribute's entity. Throws an exception if:

• attribute is null.
• attribute has an EOEntity set that is different than the receiver.
• attribute's name is already in use by another attribute or relationship belonging to the receiver.
• an error is encountered during processing.

Parameters:

attribute - A attribute to add to the receiver.

Throws:

IllegalArgumentException - if attribute's name is null or is already in use by another attribute or relationship; or if attribute has a different entity already set.

RuntimeException - if an error is encountered during processing; the error text indicates the nature of the exception.

See Also:

removeAttribute(EOAttribute name), attributes(), attributeNamed(String attributeName)

addFetchSpecification

public void addFetchSpecification(EOFetchSpecification fetchSpec,
                                  String name)

Adds the fetch specification fetchSpec to the receiver and associates name with it. Throws an exception if the entityName for fetchSpec is different than the receiver's name.

Parameters:

fetchSpec - A fetch specification.

name - A name for fetchSpec.

See Also:

fetchSpecificationNamed(String fetchSpecName), fetchSpecificationNames(), removeFetchSpecificationNamed(String fetchSpecName)

addRelationship

public void addRelationship(EORelationship relationship)

Adds relationship to the receiver and sets the receiver as the relationship's entity. Throws an exception if:

• relationship is null.
• relationship has an EOEntity set that is different than the receiver.
• relationship's name is already in use by another attribute or relationship belonging to the receiver.
• an error is encountered during processing.

Parameters:

relationship - A relationship to add to the receiver.

Throws:

IllegalArgumentException - if relationship's name is null or is already in use by another attribute or relationship; or if relationship has a different entity already set.

RuntimeException - if an error is encountered during processing; the error text indicates the nature of the exception.

See Also:

removeRelationship(EORelationship name), relationships(), relationshipNamed(String name)

addSharedObjectFetchSpecificationByName

public void addSharedObjectFetchSpecificationByName(String name)

Adds the fetch specification identified by name to the set of fetch specifications used to load objects into a shared editing context.

Parameters:

name - The name of a fetch specification to add to the receiver's list of shared object fetch specifications.

addSubEntity

public void addSubEntity(EOEntity child)

Adds the EOEntity child as a sub-entity of the receiver. This is the first step in setting up an inheritance hierarchy between entities.

NOTE: addSubEntity and removeSubEntity are not thread-safe. In general, modifying an EOModel programmatically is not thread-safe.

Parameters:

child - An EOEntity which will inherit from the receiver.

See Also:

subEntities(), removeSubEntity(EOEntity child)

anyAttributeNamed

public EOAttribute anyAttributeNamed(String name)

Returns the user-created attribute identified by name. If no such attribute exists, this method looks through the "hidden" attributes created by the Enterprise Objects Framework for one with the given name. Hidden attributes are used for such things as primary keys on target entities of flattened attributes. Returns null if no attribute with the given name is found.

Parameters:

name - The name of an attribute.

Returns:

The attribute specified by name, or null.

See Also:

attributeNamed(String attributeName), attributes()

anyRelationshipNamed

public EORelationship anyRelationshipNamed(String relationshipName)

Returns the user-created relationship identified by relationshipName. If none exists, this method looks through the "hidden" relationships created by the Enterprise Objects Framework for one with the given name. If none is found, null is returned.

Parameters:

relationshipName - The name of a relationship.

Returns:

The named relationship, or null.

See Also:

relationshipNamed(String name), relationships()

attributeNamed

public EOAttribute attributeNamed(String attributeName)

Returns the attribute named attributeName, or null if no such attribute exists in the receiver.

Parameters:

attributeName - The name of an attribute.

Returns:

The named attribute, or null.

See Also:

anyAttributeNamed(String attributeName), attributes(), relationshipNamed(String name)

attributes

public NSArray attributes()

Returns an array containing all of the receiver's attributes, or null if the receiver has no attributes. Throws a runtime exception if an error in encountered during evaluation; the error text indicates the nature of the exception.

Returns:

An array of all of the receiver's attributes, or null.

See Also:

anyAttributeNamed(String attributeName), attributeNamed(String attributeName)

attributesToFetch

public NSArray attributesToFetch()

Returns an array of the EOAttributes that need to be fetched so that they can be included in the row snapshot. The set of attributes includes:

• Attributes that are class properties, "used for locking," or primary keys.
• Source attributes of any to-many relationship (flattened or non-flattened) that is a class property.
• Source attributes of any non-flattened, to-one relationship that is a class property or that is used by a flattened attribute that is a class property.
• The foreign key attributes of any flattened, to-one relationship that is a class property or that is used by a class property.

Returns:

The array of attributes needed for the row snapshot.

attributesUsedForLocking

public NSArray attributesUsedForLocking()

Returns an array containing those attributes used for locking, that is, those properties whose values must match a snapshot any time a row is updated. Attributes used for locking are those whose values are compared when a database-level object performs an update. When the database-level classes fetch an Enterprise Object, they cache these attributes' values in a snapshot. Later, when the Enterprise Object is updated, the values of these attributes in the object are checked against those in the snapshot. If they differ, the update fails.

Returns:

An array of the attributes used for locking.

See Also:

EODatabaseContext

awakeWithPropertyList

public void awakeWithPropertyList(NSDictionary pl)

EOEntity's implementation of this method does nothing.

Specified by:

awakeWithPropertyList in interface EOPropertyListEncoding

Parameters:

pl - The property list representation of an object.

beautifyName

public void beautifyName()

Makes the receiver's name conform to a standard convention. EOEntity names that conform to this style are all lower-case except for the initial letter of each word, which is upper-case. Thus, "MOVIE" becomes "Movie", and "MOVIE_ROLE" becomes "MovieRole".

See Also:

setName(String name), EOModel.beautifyNames()

cachesObjects

public boolean cachesObjects()

Returns true if all of the objects from the receiver are to be cached in memory and queries are to be evaluated in memory using this cache rather than in the database. This method should only be used for fairly small tables of read-only objects, since the first access to the entity will trigger fetching the entire table. You should generally restrict this method to read-only entities to avoid cached data becoming out of sync with database data. Also, you shouldn't use this method if the application will be making any queries against the entity that can't be evaluated in memory.

Returns:

true if all of the objects from the receiver are to be cached in memory.

See Also:

setCachesObjects(boolean flag)

classDescriptionForInstances

public EOClassDescription classDescriptionForInstances()

Returns the EOClassDescription associated with the receiver. The EOClassDescription class provides a mechanism for extending classes by giving them access to the metadata contained in an EOModel (or other external source of information). In an application, EOClassDescriptions are registered on demand for the EOEntity on which an Enterprise Object is based.

Returns:

The class description for the receiver.

See Also:

EOClassDescription, EOEntity

className

public String className()

Returns the name of the Enterprise Object class associated with the receiver. When a row is fetched for the entity by a database-level object, it is returned as an instance of this class. This class might not be present in the runtime system, and in fact, the application may have to load it on demand. If the application doesn't load a class, EOGenericRecord is used. An Enterprise Object class other than EOGenericRecord can be mapped to only one entity.

Returns:

The name of the receiver's Enterprise Object class.

classProperties

public NSArray classProperties()

Returns an array containing the properties that are bound to the receiver's class (so that values corresponding to those properties are passed to instances of that class). This set of properties is a subset of the entity's attributes and relationships.

Returns:

An array of the properties that are bound to the receiver's class.

See Also:

classPropertyNames()

classPropertyNames

public NSArray classPropertyNames()

Returns an array containing the names of those properties that are bound to the receiver's class (so that values corresponding to those properties are passed to instances of that class). This set of properties is a subset of the entity's attributes and relationships.

Returns:

An array of the names of those properties that are bound to the receiver's class.

See Also:

classProperties()

clientClassName

public String clientClassName()

Returns the name of the client-side Enterprise Object class associated with the receiver. If no client-side class name has yet been registered for the receiver, this method returns the name of the receiving class (either EOEntity or a subclass of EOEntity).

Equivalent to the EOAccessAdditions method clientClassNameForEntity in the EOJavaClient Framework in WebObjects 4.5.x.

Returns:

The name of the client-side Enterprise Object class for the receiver.

clientClassProperties

public NSArray clientClassProperties()

Returns an array containing the properties that are bound to the client-side class corresponding to the receiver. If no information about the client-side class's properties is available, this method returns the receiver's class properties. The properties returned by this method are the attributes and relationships that are used by the client. Only these attributes and relationships will be passed to the client.

Equivalent to the EOAccessAdditions method clientClassPropertiesForEntity in the EOJavaClient Framework in WebObjects 4.5.x.

Returns:

An array of the properties that are bound to the client-side class corresponding to the receiver.

clientClassPropertyNames

public NSArray clientClassPropertyNames()

Returns an array containing the names of the properties that are bound to the client-side class corresponding to the entity. If no information about the client-side class's properties is available, this method returns the names of the entity's class properties. The property names returned by this method are the attributes and relationships that are used by the client. Only these attributes and relationships will be passed to the client.

Equivalent to the EOAccessAdditions method clientClassPropertyNamesForEntity in the EOJavaClient Framework in WebObjects 4.5.x.

Returns:

An array of the names of the properties that are bound to the client-side class corresponding to the receiver.

encodeIntoPropertyList

public void encodeIntoPropertyList(NSMutableDictionary result)

Encodes the receiver as a property list.

Specified by:

encodeIntoPropertyList in interface EOPropertyListEncoding

Parameters:

result - A property list representation of the receiver.

externalModelsReferenced

public NSArray externalModelsReferenced()

Examines each of the receiver's relationships and returns a list of all external models referenced by the receiver, or an empty arrray if no external models are referenced.

Returns:

An array of external models referenced by the receiver.

See Also:

referencesProperty(Object property)

externalName

public String externalName()

Returns the name of the receiver as understood by the database server, that is, the receiver's external name.

Returns:

The entity's external name.

externalNameForInternalName

public static String externalNameForInternalName(String internalName,
                                                 String separatorString,
                                                 boolean allCaps)

Used by the Enterprise Objects Framework to convert an internal object name, internalName to a database schema name that conforms to a standard convention, separating name elements with separatorString and capitalizing or lowercasing the external name based on the Boolean parameter allCaps.

By default, the separator string is an underscore and full capitalization is turned on. Consequently "name" becomes "NAME" and "firstName" becomes "FIRST_NAME". If allCaps is false, this method converts "firstName" to "first_name". A different separator string may also be specified.

Parameters:

internalName - An internal object model name.

separatorString - A character that is used to separate name elements.

allCaps - Boolean flag to determine whether to capitalize the returned external name.

Returns:

An external (database schema name) generated based on internalName, separatorString, and allCaps.

See Also:

nameForExternalName(String externalName, String separatorString, boolean initialCaps)

externalQuery

public String externalQuery()

Returns a query statement that is used by an EOAdaptorChannel to select rows for the entity when a qualifier is empty, or null if the entity has no external query. An empty qualifier is one that specifies only the entity and would thus fetch all Enterprise Objects for that entity.

External queries are useful for hiding records or invoking database-specific features such as stored procedures when an application attempts to select all records for an entity. You can also use the EOStoredProcedure class to work with stored procedures.

Returns:

A query statement to use when a qualifier is empty, or null.

See Also:

setExternalQuery(String name), EOStoredProcedure

fetchSpecificationNamed

public EOFetchSpecification fetchSpecificationNamed(String fetchSpecName)

Returns the fetch specification identified by fetchSpecName.

Parameters:

fetchSpecName - The name of a fetch specification.

Returns:

The fetch specification identified by fetchSpecName.

See Also:

addFetchSpecification(EOFetchSpecification fetchSpec, String fetchSpecName), fetchSpecificationNames(), removeFetchSpecificationNamed(String fetchSpecName)

fetchSpecificationNames

public NSArray fetchSpecificationNames()

Returns an alphabetically sorted array of the names of the receiver's fetch specifications. Throws a runtime exception if an error is encountered during sorting; the error text indicates the nature of the exception.

Returns:

An alphabetized array of names of the receiver's fetch specifications.

See Also:

addFetchSpecification(EOFetchSpecification fetchSpec, String fetchSpecName), fetchSpecificationNamed(String fetchSpecName), removeFetchSpecificationNamed(String fetchSpecName)

globalIDForRow

public EOGlobalID globalIDForRow(NSDictionary row)

Constructs a unique global identifier for the receiver from the keys and values in the dictionary row, which represents a database row.

Parameters:

row - A dictionary representation of a database row from which to create an EOGlobalID for the receiver.

Returns:

A global identifier for the receiver.

See Also:

primaryKeyForGlobalID(com.webobjects.eocontrol.EOGlobalID globalID)

isAbstractEntity

public boolean isAbstractEntity()

Returns true if the receiver is an abstract entity, false otherwise. An abstract entity is one that has no corresponding Enterprise Objects in the application. Abstract entities are used to model inheritance relationships. For example, you might have a Person abstract entity that acts as the parent of Customer and Employee entities. Customer and Employee would inherit certain characteristics from Person (such as name and address attributes). However, though the application might have Customer and Employee objects, it would never have a Person object.

Returns:

true if the receiver is an abstract entity.

See Also:

setIsAbstractEntity(boolean flag)

isPrimaryKeyValidInObject

public boolean isPrimaryKeyValidInObject(NSKeyValueCoding object)

Returns true if every key attribute is present in object and has a value that is not null. Returns false otherwise. This method uses the EOKeyValueCoding interface so the object parameter may be a dictionary instead of an Enterprise Object.

Parameters:

object - The object to query.

Returns:

true if every key attribute in object is valid.

See Also:

primaryKeyForRow(NSDictionary aRow)

isQualifierForPrimaryKey

public boolean isQualifierForPrimaryKey(EOQualifier qualifier)

Returns true if qualifier describes the primary key and nothing but the primary key, false otherwise. Throws a runtime exception if an error in encountered during evaluation; the error text indicates the nature of the exception.

Parameters:

qualifier - An EOQualifier object.

Returns:

true if qualifier describes only the primary key.

isReadOnly

public boolean isReadOnly()

Returns true if the receiver can not be modified, false if it can. If an entity is read-only, then Enterprise Objects fetched for that entity are also read-only (that is, can not be inserted, deleted, or updated).

Returns:

true if the entity can't be modified.

isValidAttributeUsedForLocking

public boolean isValidAttributeUsedForLocking(EOAttribute anAttribute)

Returns true if anAttribute can be used for locking, false otherwise. In order for an attribute to be valid for locking, it must be an attribute belonging to the receiver and must not be a derived attribute. Used to test the validity of an attribute for locking before passing it to setAttributesUsedForLocking.

Parameters:

anAttribute - An EOAttribute.

Returns:

true if the attribute can be used for locking.

See Also:

attributesUsedForLocking(), setAttributesUsedForLocking(NSArray attributes)

isValidClassProperty

public boolean isValidClassProperty(Object aProp)

Returns true if the property aProp is a valid class property of the receiver, false otherwise. To be a valid class property, a property must be an instance of EOAttribute or EORelationship.

Note that this method does not tell you whether aProp is a member of the array returned by the classProperties method. In other words, unlike classProperties, classPropertyNames, and setClassProperties, this method does not interact with the properties bound to the receiver's Enterprise Object class.

Parameters:

aProp - The property to query.

Returns:

true if aProp is a valid class property of the receiver.

See Also:

classProperties(), classPropertyNames(), setClassProperties(NSArray attributes)

isValidPrimaryKeyAttribute

public boolean isValidPrimaryKeyAttribute(EOAttribute anAttribute)

Returns false if anAttribute isn't an EOAttribute, doesn't belong to the entity or is derived. Otherwise returns true.

Parameters:

anAttribute - the attribute to query

Returns:

false if anAttribute isn't an EOAttribute, doesn't belong to the entity, or is derived.

See Also:

setPrimaryKeyAttributes(NSArray keys)

maxNumberOfInstancesToBatchFetch

public int maxNumberOfInstancesToBatchFetch()

Returns the maximum number of to-one faults from the receiver to fire at one time.

Returns:

The maximum number of to-one faults to batch fetch.

See Also:

setMaxNumberOfInstancesToBatchFetch(int size)

model

public EOModel model()

Returns the EOModel that contains the receiver.

Returns:

The model that contains the entity.

See Also:

EOModel.addEntity(EOEntity anEntity)

name

public String name()

Returns the receiver's name.

Returns:

The entity's name.

nameForExternalName

public static String nameForExternalName(String externalName,
                                         String separatorString,
                                         boolean initialCaps)

Used by the Enterprise Objects Framework to convert a database schema name externalName to an internal object name that conforms to a standard convention, using the capitalization rule initialCaps and removing the character separatorString that separates name elements in the external name.

By default, the separator string is assumed to be an underscore, however a different character may be specified, as used by the database. The default capitalization rule for EOAttribute, EORelationship, or EOStored procedure object names is false, that is, all lower-case except for the initial letter of each embedded word other than the first, which is upper-case. Consequently, "NAME" becomes "name" and "FIRST_NAME" becomes "firstName".

The default capitalization rule for EOEntity object names is true, that is, is all lower-case except for the initial letter of each word. Consequently "CUSTOMER_ACCOUNT" becomes "CustomerAccount".

Parameters:

externalName - A table or column name in the database schema.

separatorString - A character that is used to separate name elements in the externalName.

initialCaps - Boolean flag to determine whether to capitalize the initial letter of every name element.

Returns:

An object model name generated based on externalName, separatorString, and initialCaps.

See Also:

externalNameForInternalName(String internalName, String separatorString, boolean allCaps), beautifyName(), EOModel.beautifyNames(), EOAttribute.beautifyName(), EORelationship.beautifyName(), EOStoredProcedure.beautifyName()

parentEntity

public EOEntity parentEntity()

Returns the parent entity for the receiver, that is, the entity from which the receiver inherits.

Returns:

The receiver's parent entity.

See Also:

subEntities()

primaryKeyAttributeNames

public NSArray primaryKeyAttributeNames()

Returns an array containing the names of the EOAttributes that make up the receiver's primary key.

Returns:

An array of the names of the attributes that make up the receiver's primary key.

See Also:

primaryKeyAttributes()

primaryKeyAttributes

public NSArray primaryKeyAttributes()

Returns an array of those EOAttributes that make up the receiver's primary key.

Returns:

The array of attributes that make up the receiver's primary key.

See Also:

primaryKeyAttributeNames()

primaryKeyForGlobalID

public NSDictionary primaryKeyForGlobalID(EOGlobalID gid)

Returns the primary key for the object identified by gid, or null if gid is not an instance of EOKeyGlobalID.

Parameters:

gid - The unique identifier for an Enterprise Object.

Returns:

The primary key for the object identified by gid or null.

See Also:

globalIDForRow(NSDictionary row)

primaryKeyForRow

public NSDictionary primaryKeyForRow(NSDictionary row)

Returns the primary key for row, or null if the primary key can't be computed. The primary key is a dictionary whose keys are attribute names and whose values are values for those attributes.

Parameters:

row - The dictionary of keys and values representing a database row.

Returns:

The primary key for row, or null.

See Also:

primaryKeyForGlobalID(EOGlobalID gid)

primaryKeyRootName

public String primaryKeyRootName()

Returns the external name (that is, the name understood by the database) of the receiver's root (parent) entity. If the receiver has no parent entity, returns the receiver's external name, if one is set, or internal name, if no external name is set.

Returns:

The external name of the receiver's root entity, or the receiver's external name, or the receiver's internal name.

See Also:

externalName(), name(), parentEntity()

qualifierForPrimaryKey

public EOQualifier qualifierForPrimaryKey(NSDictionary row)

Returns a qualifier for the receiver that can be used to fetch an instance of the receiver with the primary key extracted from row. Throws an exception if the value of the primary key obtained from row is either null or NSKeyValueCoding.NullValue.

Parameters:

row - A primary key dictionary for a row in the database.

Returns:

A qualifier that can be used to fetch an instance of the receiver based on the primary key from row.

Throws:

IllegalArgumentException - if the primary key is null or NSKeyValueCoding.NullValue.

See Also:

isQualifierForPrimaryKey(EOQualifier aQualifier), restrictingQualifier()

referencesProperty

public boolean referencesProperty(Object property)

Returns true if any of the receiver's attributes or relationships reference property, false otherwise. A property can be referenced by a flattened attribute or by a relationship.

For example, suppose a model has an Employee entity with a toDepartment relationship. If you flatten the department's name attribute into the Employee entity, creating a departmentName attribute, that flattened attribute references the toDepartment relationship. If an entity has any outstanding references to a property, you shouldn't remove the property.

Parameters:

property - An attribute or relationship of the receiver.

Returns:

true if any of the receiver's attributes or relationships reference property.

See Also:

removeAttribute(EOAttribute name), removeRelationship(EORelationship name)

relationshipNamed

public EORelationship relationshipNamed(String relationshipName)

Returns the relationship identified by relationshipName, or null if the receiver has no such relationship.

Parameters:

relationshipName - The name of a relationship.

Returns:

The specified relationship or null.

See Also:

anyRelationshipNamed(String relationshipName), attributeNamed(String attributeName), relationships()

relationships

public NSArray relationships()

Returns an array containing all of the receiver's relationships or null if the receiver has none. Throws a runtime exception if an error is encountered during processing; the error text indicates the nature of the exception.

Returns:

An array of all of the receiver's relationships, or null.

See Also:

attributes()

removeAttribute

public void removeAttribute(EOAttribute attribute)

If attribute exists, removes it from the receiver. Always use referencesProperty to check that an attribute isn't referenced by another property before removing it.

Parameters:

attribute - An existing attribute of the receiver.

See Also:

addAttribute(EOAttribute anAttribute), attributes(), referencesProperty(Object property)

removeFetchSpecificationNamed

public void removeFetchSpecificationNamed(String name)

Removes the fetch specification identifed by name from the receiver.

Parameters:

name - The name of a fetch specification to remove.

See Also:

addFetchSpecification(EOFetchSpecification fetchSpec, String fetchSpecName), fetchSpecificationNamed(String fetchSpecName), fetchSpecificationNames()

removeRelationship

public void removeRelationship(EORelationship relationship)

If relationship exists, removes it from the receiver. Always use referencesProperty to check that a relationship isn't referenced by another property before removing it.

Parameters:

relationship - The relationship to remove from the receiver.

See Also:

addRelationship(EORelationship aRelationship), relationships(), referencesProperty(Object property)

removeSharedObjectFetchSpecificationByName

public void removeSharedObjectFetchSpecificationByName(String name)

Removes the fetch specification identified by name from the set of fetch specifications used to load objects into a shared editing context.

Parameters:

name - The name of a fetch specification to remove from the receiver's list of shared object fetch specifications.

removeSubEntity

public void removeSubEntity(EOEntity child)

Removes the EOEntity child from the list of sub-entities that inherit from the receiver.

NOTE: addSubEntity and removeSubEntity are not thread-safe. In general, modifying an EOModel programmatically is not thread-safe.

Parameters:

child - An EOEntity to remove from the receiver's list of sub-entities.

See Also:

addSubEntity(EOEntity child), subEntities()

restrictingQualifier

public EOQualifier restrictingQualifier()

Returns the qualifier used to restrict all queries made against the receiver. Restricting qualifiers are useful when there is not a one-to-one mapping between an entity and a particular database table, or when you always want to filter the data that's returned for a particular entity.

For example, if you are using the "single table" inheritance model in which parent and child data are contained in the same table, you would use a restricting qualifier to fetch objects of the appropriate type. To give a non-inheritance example, for an Employees table you might create a "Sales" entity that has a restricting qualifier that only fetches employees who are in the Sales department.

Returns:

The qualifier used to restrict all queries made against the receiver.

See Also:

setRestrictingQualifier(EOQualifier aQualifier)

schemaBasedQualifier

public EOQualifier schemaBasedQualifier(EOQualifier qualifier)

Returns an SQL qualifier based on qualifier that is suitable for evaluation by a database (as opposed to in-memory evaluation). Invoked by an EODatabaseChannel object before it uses its EOAdaptorChannel to perform a database operation. Whereas in-memory qualifier evaluation uses object instance variables to resolve relationships, a database qualifier must use foreign keys.

Parameters:

qualifier - A qualifier for in-memory evaluation from which to derive an SQL qualifier for evaluation by the database.

Returns:

An SQL qualifier based on qualifier that uses foreign keys to resolve relationships.

See Also:

EOQualifierEvaluation, EODatabaseChannel.selectObjectsWithFetchSpecification( EOFetchSpecification fetchSpecification, EOEditingContext context)

setAttributesUsedForLocking

public boolean setAttributesUsedForLocking(NSArray attributes)

If all of the the EOAttributes in attributes can be used by an EODatabaseChannel to lock Enterprise Objects for updates, sets attributes as the receiver's attributes used for locking and returns true. Otherwise returns false and leaves the receiver's currently-set attributes used for locking unchanged.

Parameters:

attributes - An array of attributes to be used for locking on the receiver.

Returns:

true if attributes can be set as the receiver's attributes used for locking.

See Also:

isValidAttributeUsedForLocking(EOAttribute anAttribute), EODatabase, EODatabaseContext, EODatabaseChannel

setCachesObjects

public void setCachesObjects(boolean flag)

Based on the Boolean value flag, sets whether the receiver's Enterprise Objects are cached the first time the associated database table is queried.

Parameters:

flag - Boolean value to set whether the receiver's fetched objects are cached.

See Also:

cachesObjects()

setClassName

public void setClassName(String name)

Assigns name as the name of the Enterprise Object class associated with the receiver if name is not null. The specified class need not be present in the runtime system when this message is sent. When an EODatabaseChannel fetches objects for the receiver, they are created as instances of this class. The application may have to load the class on demand if it isn't present in the runtime system; if it doesn't load the class, EOGenericRecord will be used.

An Enterprise Object class other than EOGenericRecord can be mapped to only one entity.

Parameters:

name - The name of the enteprise object class associated with the receiver.

See Also:

className()

setClassProperties

public boolean setClassProperties(NSArray attributes)

If all of the the EOAttributes in attributes are valid class properties of the receiver, sets attributes as the receiver's class properties and returns true. Otherwise returns false and leaves the currently-set class properties for the receiver unchanged.

Parameters:

attributes - An array of attributes to set as the receiver's class properties.

Returns:

true if attributes can be set as the receiver's class properties.

See Also:

isValidClassProperty(Object property)

setExternalName

public void setExternalName(String string)

Sets the name of the receiver as understood by the database server (that is, the receiver's external name) to string. For example, though the application may know the receiver as "JobTitle", the database may require a form such as "JOB_TTL".

An adaptor uses the external name to communicate with the database; the application should never need to use the external name.

Parameters:

string - The external (database server) name for the receiver.

setExternalQuery

public void setExternalQuery(String string)

Assigns string as the query statement used for selecting rows from the entity when there is no qualifier. External queries are useful for hiding records or invoking database-specific features such as stored procedures when an application attempts to select all records for an entity. You can also use the EOStoredProcedure class to work with stored procedures.

An external query is sent unaltered to the database server, and so must contain the external (column) names instead of the entity's attribute names. However, to work properly with the adaptor, the external query must use the columns in alphabetical order by their corresponding EOAttributes' names.

Parameters:

string - The query text.

See Also:

externalQuery(), EOStoredProcedure, EOAttribute.columnName()

setIsAbstractEntity

public void setIsAbstractEntity(boolean flag)

Based on the Boolean flag, sets whether the receiver is an abstract entity, false otherwise. Abstract entities are used to model inheritance relationships.

For example, you might have a Person abstract entity that acts as the parent of Customer and Employee entities. Customer and Employee would inherit certain characteristics from Person (such as name and address attributes). However, though the application might have Customer and Employee objects, it would never have a Person object.

Parameters:

flag - true if the receiver is an abstract entity.

See Also:

isAbstractEntity()

setMaxNumberOfInstancesToBatchFetch

public void setMaxNumberOfInstancesToBatchFetch(int size)

Sets the maximum number of faults from the entity to trigger at one time to size. By default, only one object is fetched from the database when you trigger a fault.

Using this optional method to fetch a batch of faults when one fault is triggered helps to optimize performance by getting extra work done for each round trip to the database.

Parameters:

size - The maximum number of faults to trigger at one time.

See Also:

maxNumberOfInstancesToBatchFetch()

setName

public void setName(String name)

Sets the receiver's name to name.

Parameters:

name - The name to set for the receiver.

See Also:

beautifyName()

setPrimaryKeyAttributes

public boolean setPrimaryKeyAttributes(NSArray attributes)

If all of the the EOAttributes in attributes are valid primary keys of the receiver, sets attributes as the receiver's primary keys and returns true. Otherwise returns false and leaves the currently-set primary keys for the receiver unchanged.

Primary key attributes should be chosen carefully. Floating-point numbers, for example, can not be reliably compared for equality, and thus are unsuitable for use in primary keys. Integer and string types are the safest choice for primary keys. BigDecimal objects can be used as primary keys, but entail more overhead than integers.

Parameters:

attributes - An array of attributes to be used as primary keys of the receiver.

Returns:

true if attribute can be set as the receiver's primary key attributes.

See Also:

isValidPrimaryKeyAttribute(EOAttribute anAttribute)

setReadOnly

public void setReadOnly(boolean flag)

Sets whether the receiver is read-only based on the Boolean value flag. If an entity is read-only, the database rows for that entity can not be modified by the application.

Parameters:

flag - Boolean value to set whether the receiver is read-only.

See Also:

isReadOnly()

setRestrictingQualifier

public void setRestrictingQualifier(EOQualifier qualifier)

Assigns qualifier as the qualifier used to restrict all queries made against the receiver. The restricting qualifier can be used to map an entity to a subset of the rows in a table.

Parameters:

qualifier - An EOQualifier used to restrict all queries for the receiver.

See Also:

restrictingQualifier()

setSharedObjectFetchSpecificationsByName

public void setSharedObjectFetchSpecificationsByName(NSArray names)

Sets the names of the fetch specifications used to load objects into a shared editing context to names.

Parameters:

names - An array of names of fetch specifications.

setStoredProcedure

public void setStoredProcedure(EOStoredProcedure storedProcedure,
                               String operation)

Sets storedProcedure as a stored procedure for the receiver and associates with it the name operation, which must be one of the following:

• FetchAllProcedureOperation
• FetchWithPrimaryKeyProcedureOperation
• InsertProcedureOperation
• DeleteProcedureOperation
• NextPrimaryKeyProcedureOperation

This information is used when changes from the object graph have been transformed into EODatabaseOperations that are being used to construct EOAdaptorOperations. At this point, the Enterprise Objects Framework checks the entities associated with the changed objects to see if the entities have any stored procedures defined for the operation being performed.

Parameters:

storedProcedure - A stored procedure for the operation described by the name operation.

operation - The name of an EODatabaseOperation.

See Also:

FetchAllProcedureOperation, FetchWithPrimaryKeyProcedureOperation, InsertProcedureOperation, DeleteProcedureOperation, NextPrimaryKeyProcedureOperation, storedProcedureForOperation(String operation), EOStoredProcedure

setUserInfo

public void setUserInfo(NSDictionary dictionary)

Sets the dictionary of auxiliary user data to dictionary. The userInfo dictionary contains arbitrary data that the application can use for whatever it needs. dictionary can only contain property list data types: String, NSDictionary, NSArray, and NSData.

Parameters:

dictionary - Arbitrary information for use by the application.

sharedObjectFetchSpecificationNames

public NSArray sharedObjectFetchSpecificationNames()

Returns an array of strings, which are the names of the fetch specifications used to load objects into a shared editing context. Returns an empty array if there are no shared object fetch specifications.

Returns:

An array of fetch specification names, or an empty array.

storedProcedureForOperation

public EOStoredProcedure storedProcedureForOperation(String operation)

Returns the stored procedure identified by the name operation, if one has been set. Otherwise, returns null. operation must be one of the following:

• FetchAllProcedureOperation
• FetchWithPrimaryKeyProcedureOperation
• InsertProcedureOperation
• DeleteProcedureOperation
• NextPrimaryKeyProcedureOperation

Parameters:

operation - The name of a stored procedure.

Returns:

The stored procedure identified by operation, or null.

See Also:

FetchAllProcedureOperation, FetchWithPrimaryKeyProcedureOperation, InsertProcedureOperation, DeleteProcedureOperation, NextPrimaryKeyProcedureOperation, setStoredProcedure(EOStoredProcedure storedProcedure , String operation), EOAttribute.parameterDirection(), EOAttribute.storedProcedure()

subEntities

public NSArray subEntities()

Returns a list of those entities that inherit from the receiver, or an empty array if no entities inherit from the receiver.

Returns:

An array of the receiver's sub-entities, or an empty array.

See Also:

addSubEntity(EOEntity child), parentEntity(), removeSubEntity(EOEntity child)

toString

public String toString()

Returns a string representation of all the receiver's properties.

Returns:

The entity's property list as a string.

userInfo

public NSDictionary userInfo()

Returns a dictionary of user data. The application can use this to store any auxiliary information it needs.

Returns:

A dictionary of arbitrary user data.

See Also:

setUserInfo(NSDictionary dictionary)

valueForSQLExpression

public String valueForSQLExpression(EOSQLExpression context)

Returns an SQL query string based on the receiver's external name and an EOSQLExpression object context. Returns the receiver's external name if context is null.

For conformance to the EOSQLExpression.SQLValue interface.

Specified by:

valueForSQLExpression in interface EOSQLExpression.SQLValue

Parameters:

context - An EOSQLExpression object.

Returns:

An SQL query string based on context, or the receiver's external name.

See Also:

externalName(), EOSQLExpression