PATH  WebObjects 4.0 Documentation > What's New in EOF 3.0

Table of Contents Previous Section

Raw Row Fetching

 When you perform a fetch in an Enterprise Objects Framework application, the information from the database is fetched and stored in a graph of enterprise objects. This object graph provides many advantages, but it can be large and complex. If you're creating a simple application, you may not need all of the benefits of the object graph. For example, a WebObjects application that merely displays information from a database without ever performing database updates and without ever traversing relationships might be just as well served by fetching the information into a set of dictionaries rather than a set of enterprise objects.

More specifically, suppose you want to display the first name, last name, and the department for a set of employees. Using objects, you would bind Employee's firstName, lastName, and department.name keys to your user interface. This configuration requires fetching of all of the attributes in an Employee entity-the ones you want to display (firstName and lastName) as well as the ones you don't (salary, birthDate, address, and so on, for example). In addition, this configuration requires faulting in (or perhaps prefetching) all of the related Department objects. Again you fetch all the Department attributes, those you want to display (departmentName) as well as those you don't (budget, location, and so on). In addition to fetching a large amount of data that your application doesn't use, this object-based fetch incurs the additional overhead of creating real enterprise objects from the returned data and of uniquing those objects in the EOEditingContext.

In this kind of display-only scenario, it might be preferable to fetch only the attributes that you need, and to fetch them as lightweight, non-uniqued, rows. In this example, you could fetch only the firstName, lastName, and department.name for each employee. In addition to fetching less data, you'd also fetch with one trip to the database instead of two (one for Employee objects and one for the related Departments).

Enterprise Objects Framework 3.0 supports this concept of a simplified fetch, called raw row fetching. In raw row fetching, each row from the database is fetched into an NSDictionary object.

To set up an application to perform raw row fetching, create an EOFetchSpecification, and send it a setFetchesRawRows:YES (or setFetchesRawRows(true) in Java) message. By default, the keys in the raw row dictionaries are the attribute names as given by the EOEntity's attributesToFetch method.

If you want more control over the attributes that are fetched for the raw row, use the setRawRowKeyPaths: method to specify the attribute paths you want. The key paths you provide can be simple attribute keys, such as title, as well as key paths, such as studio.name. After the fetch, each row is returned as a separate dictionary whose keys are the key paths you specified. If you use setRawRowKeyPaths:, you don't have to invoke setFetchesRawRows:; it's automatic.

When you use raw row fetching, you lose some important features:

Should you fetch a row into an NSDictionary and later want to fetch the corresponding enterprise object, send faultForRawRow:entityNamed:editingContext: (or faultForRawRow in Java) to the EOEditingContext. This creates a fault for the row (an EOFault object in Objective-C or an empty object of the correct enterprise object class in Java). The raw row dictionary must contain the primary key attributes for this method to work properly. When your code tries to access the object for that row, the fault forces another database fetch, and a true enterprise object is created.

The following tables describe the API added to support raw row fetching.
EOFetchSpecification
rawRowKeyPaths Returns an array of attribute keys that should be fetched as raw data. The default value is nil or null, indicating that full enterprise objects are to be returned from the fetch. If the array contains no objects, the entity specifies which attributes to fetch (EOEntity's attributesToFetch method).
setRawRowKeyPaths: Sets the array of attribute keys that should be fetched as raw data. You can disable the fetching of raw rows by sending nil or null to this method. If you want to perform raw row fetching, but you want the entity to specify which attributes to fetch, you can pass an empty array to this method or you can use the setFetchesRawRows: method to enable raw row fetching.
fetchesRawRows Returns whether raw row fetching is performed. YES or true if rawRowKeyPaths is non-nil or non-null.
setFetchesRawRows: Sets whether raw row fetching is performed. If the value passed to this method is YES or true, then the rawRowKeyPaths array is set to an empty array. If NO or false, then the rawRowKeyPaths array is set to nil or null.
EOObjectStore
faultForRawRow:entityNamed:editingContext: (Objective-C) faultForRawRow (Java) Returns a fault for the given raw row dictionary. The raw row dictionary must include the primary key attributes for this method to work properly. If the dictionary does not include the primary key, this method raises or throws an exception. Note that as EOObjectStore subclasses, EOEditingContext and EODatabaseContext also provide this method.

In addition to these methods, EOUtilities also provides raw row fetching methods. For more information, see section "New Convenience API."

Table of Contents Next Section