Principal Methods

This chapter provides a list of the most commonly used methods in an Enterprise Objects application. The methods are categorized by the task in which they are used and listed alphabetically within each category.

Creating and Initializing Objects

This section lists the primary methods you use to instantiate and initialize enterprise objects.

EOEnterpriseObject: awakeFromFetch(EOEditingContexteditingContext)

Override this method in custom enterprise object classes to provide custom initialization of an enterprise object when it is first fetched from a data source.

EOEnterpriseObject: awakeFromInsertion(EOEditingContexteditingContext)

Override this method to provide custom initialization of an enterprise object when it is first created and inserted into an editing context.

Do not add any custom code to an enterprise object’s constructor. Rather, override this method in your custom business logic classes and add your custom code there. This method is invoked automatically by the framework when a new enterprise object is created and has finished initializing. Before you can override this method for a particular enterprise object class, you need to create a custom class using EOModeler, which is discussed in Business Objects.

EOEditingContext: insertObject(EOEnterpriseObjectenterpriseObject)

Use this method to insert a new enterprise object instance into an editing context. When you instantiate an enterprise object, you must immediately insert it into an editing context.

EOUtilities: createAndInsertInstance(EOEditingContexteditingContext, StringentityName)

This convenience method instantiates an enterprise object for the entity specified by entityName and inserts the new object into the editing context specified by editingContext.

Fetching and Accessing Data

The methods in this section fetch data from a data source and access the properties of enterprise object instances.

EOFetchSpecification constructor: (StringentityName, EOQualifierqualifier, NSArraysortOrderings)

Use this method to construct a fetch specification that you use to retrieve data from a data source. Only the entityName parameter is mandatory. A fetch specification is transformed by the framework into a SQL expression in which entityName is used in the FROM clause, qualifier is used in the WHERE clause, and sortOrderings is used in the ORDER BY clause.

EOUtilities: objectsForEntityNamed(EOEditingContexteditingContext, StringentityName)

This convenience method fetches all the enterprise objects for the entity specified by entityName.

EOEditingContext: objectsWithFetchSpecification(EOFetchSpecificationfs)

Use this method to retrieve data from a data source.

EOUtilities: primaryKeyForObject(EOEditingContexteditingContext, EOEnterpriseObjectenterpriseObject)

This convenience method retrieves the primary key for the enterprise object specified by enterpriseObject. You usually do not need to worry about primary keys when building an Enterprise Objects application.

EOQualifier: qualifierWithQualifierFormat(Stringformat, NSArrayarguments)

Use this method to construct a qualifier for use in a fetch specification or for use when sorting fetch results in memory.

EOUtilities: rawRowsForSQL(EOEditingContexteditingContext, StringmodelName, StringsqlString)

This convenience method evaluates the specified sqlString and uses information from the EOModel specified by modelName to retrieve the raw database rows specified by sqlString. In an Enterprise Objects application, you usually do not need to explicitly think about SQL or fetch raw rows.

EOCustomObject: valueForKey(Stringkey)

This method returns an object for the property in an enterprise object specified by key. This method is part of the key-value coding infrastructure of Enterprise Objects, in which an object’s properties are accessed by key rather than directly as fields or through accessor methods. This is discussed in more detail in Accessing an Enterprise Object’s Data.

EOCustomObject: valueForKeyPath(StringkeyPath)

This method returns an object for the property in an enterprise object’s relationship specified by keyPath, where keyPath is a String of the form “relationship.property”. This method allows you to access relationships between enterprise objects using a chain of keys. It is part of the key-value coding infrastructure of Enterprise Objects, which is discussed in more detail in Accessing an Enterprise Object’s Data.

Identifying and Tracking Objects

The methods in this section to identify and track enterprise objects in the object graph (in an editing context).

EOEditingContext: faultForGlobalID(EOGlobalIDgid, EOEditingContexteditingContext)

This method returns an enterprise object based on the global ID gid in the editing context editingContext. When an enterprise object is fetched from a persistent data source or otherwise instantiated, it is assigned a globally unique identifier called a global ID. You can use a global ID to obtain a reference to the ID’s enterprise object (which may be a fault). Uses for this method are discussed in Working With Objects in Multiple Editing Contexts.

EOEditingContext: globalIDForObject(EOEnterpriseObjectenterpriseObject)

Use this method to obtain the global ID for an enterprise object in an editing context.

EOEnterpriseObject: editingContext()

Use this method to get a reference to the editing context in which a particular enterprise object is registered.

EOUtilities: localInstanceOfObject(EOEditingContexteditingContext, EOEnterpriseObjectenterpriseObject)

Use this method to create, in the editing context specified by editingContext, a copy of an enterprise object that exists in another editing context. This discussed in more detail in Working With Objects in Multiple Editing Contexts.

Working With Fetch Results

After you fetch data into an application, you often need to perform in-memory sorting or filtering of that data. The methods in this section provide support for both of those tasks.

EOQualifier: filteredArrayWithQualifier(NSArrayarray, EOQualifierqualifier)

Use this method to filter an array of enterprise objects based on the criteria specified by qualifier.

EOSortOrdering constructor: (Stringkey, NSSelectorselector)

Use this method to construct a sort ordering to use when sorting enterprise objects in memory. The key parameter specifies the property in the enterprise object on which to perform the sort. The selector parameter specifies the sorting order and is usually one of the static fields in the EOSortOrdering class, such as CompareAscending.

EOSortOrdering: sortedArrayUsingKeyOrderArray(NSArrayarray, NSArraysortOrderings)

Use this method to sort an array of enterprise objects in memory. The array of sortOrderings need contain only one EOSortOrdering object, which you construct with the EOSortOrdering constructor.

Manipulating and Changing Objects

The methods in this section manipulate enterprise objects and editing contexts.

EOCustomObject: addObjectToBothSidesOfRelationshipWithKey(EORelationshipManipulationobject, Stringkey)

Use this method to add the enterprise object specified by object as the destination of the relationship specified by key. See Manipulating Relationships for more information.

EOEditingContext: deleteObject(EOEnterpriseObjectenterpriseObject)

Use this method to delete an enterprise object from an editing context. If your application connects to a relational database, this method usually results in the removal of a row or rows of data.

EOEditingContext: lock()

Obtains a lock on the receiver. To ensure the integrity of an editing context in multithreaded environments, you must lock an editing context before you invoke operations on it and unlock it afterwards. In a WebObjects application, if you use Session’s defaultEditingContext, you do not need to lock and unlock it; it performs those operations internally.

EOEditingContext: redo()

Reapplies the last set of operations performed on enterprise objects in an editing context that were undone by the undo method. See Undoing Changes for more information. You do not usually invoke this method explicitly. Rather, it is usually used only in a desktop application as the invocation target of the Edit menu’s Redo item.

EOEditingContext: revert()

Use this method to restore an editing context to a stable state. See Discarding Changes.

EOCustomObject: removeObjectFromBothSidesOfRelationshipWithKey(EORelationshipManipulationobject, Stringkey)

Use this method to remove from the destination of the relationship specified by key the enterprise object specified by object. See Manipulating Relationships for more information.

EOEditingContext: saveChanges()

Commits the changes made in an editing context to the data source. See Flow of Data During a Save for detailed information on what occurs when this method is invoked.

EOCustomObject: takeValueForKey(Objectvalue, Stringkey)

This method sets the value of an enterprise object’s property identified by key to value. This method is part of the key-value coding infrastructure of Enterprise Objects, in which an object’s properties are accessed by key rather than directly as fields or through accessor methods. This is discussed in more detail in Accessing an Enterprise Object’s Data.

EOCustomObject: takeValueForKeyPath(Objectvalue, StringkeyPath)

This method sets the value of a property in an enterprise object that is the destination of an enterprise object’s relationship. keyPath is a String of the form “relationship.property”, in which “relationship” is the name of a relationship in the enterprise object on which this method is invoked and in which value mutates the property identified by the “property” portion of keyPath. This is discussed in more detail in Accessing an Enterprise Object’s Data.

EOEditingContext: undo()

Reverses the last set of operations performed on enterprise objects in an editing context. See Undoing Changes for more information.

EOEditingContext: unlock()

Releases a lock on the receiver. To ensure the integrity of an editing context in multithreaded environments, you must lock an editing context before you invoke operations on itm, and you must unlock it afterwards. In a WebObjects application, if you use Session’s defaultEditingContext, you do not need to lock and unlock it; it performs those operations internally.

EOCustomObject: validateKey(Objectvalue, Stringkey)

This method is defined in EOCustomObject as validateValueForKey. You never directly invoke that method. Rather, you implement methods of the form validateKey in custom enterprise object classes to validate certain properties. Those methods are then automatically invoked by validateValueForKey.

An implementation that validates the value of a bathrooms property of a Listing enterprise object would have the signature publicObjectvalidateBedrooms(Objectvalue, Stringkey). See Adding Validation for more information.