Inserting with the Adaptor Sublayer
Synopsis
Describes how to insert a row into the database using the adaptor channel's insertRow method.
Description
There are three ways to insert a row into the database with the adaptor sublayer. You can insert using raw SQL using the adaptor channel's evaluateExpression method, the adaptor channel's insertRow method, or a stored procedure.
In this topic we describe how to insert a row using the insertRow method. This method eliminates the overhead associated with snapshots, uniquing, and fault creation. Furthermore, the source code does not depend on the particular database you use. However, you have to work with raw row dictionaries and you are responsible for setting the primary key. This example sets the primary key using the adaptor channel's primaryKeyForNewRowWithEntity method. See the programming topic Generating Primary Key Values for more information about the tradeoffs when generating primary keys.
If you are working with an editing context and inserting using the adaptor sublayer at the same time, EOF does not realize that an object has been inserted. You need to synchronize any enterprise objects with the changes to the database.
To insert a row using the adaptor channel's insertRow method, you need to provide
- An EOModel mapping entities to database tables.
- An NSDictionary containing the row. The keys for the row are the attribute names not the database column names.
- An adaptor channel that is connected to the database. (See the programming topics Accessing Adaptor Sublayer Objects , Creating Adaptor Sublayer Objects and Connecting Them to the Server , and Accessing Schema Information from the Database Server for more information about getting an adaptor channel.
- The name of the entity that you wish to insert, for example, " Movie ".
The following code inserts a row using the adaptor sublayer.
EOAdaptorChannel myAdaptorChannel; // assume exists String modelName = "movies"; String entityName = "Movie"; NSMutableDictionary dict = new NSMutableDictionary(); dict.setObjectForKey ("EOF III: The Multithreading","title"); dict.setObjectForKey ("Action","category"); dict.setObjectForKey (new Integer(90000000),"revenue"); EOModel myModel = EOModelGroup.defaultGroup().modelNamed(modelName); EOEntity myEntity = myModel.entityNamed(entityName); myAdaptorChannel.openChannel(); dict.addEntriesFromDictionary(myAdaptorChannel. // get a primary key primaryKeyForNewRowWithEntity(myEntity)); myAdaptorChannel.insertRow(dict,myEntity); // insert the row myAdaptorChannel.closeChannel();
The code first allocates and initializes a raw row dictionary for the new database row.
The code then finds the EOModel corresponding to the model name in the default model group. The default model group, accessed using EOModelGroup.defaultGroup() is a collection of EOModel objects corresponding to the models in the project's Resources suitcase. If you already have the EOModel, you don't need this step. Next, the code determines the EOEntity corresponding to the given entity name from the EOModel.
Before performing insertRow with the adaptor channel, the code establishes a connection to the database using the openChannel method and determines a primary key for the row. The primaryKeyForNewRowWithEntity method returns the primary key as an NSDictionary, which the code merges with the raw row dictionary before inserting the row into the database. The closeChannel method invocation disconnects the channel from the database.
Insertion Failures
The insertion can fail for the following reasons:
- The user logged on to the database does not have permission to insert a row.
- The EOAdaptorChannel is in an invalid state for inserting, for example, a fetch is in progress. To test if a fetch is in progress, use the adaptor channel's isFetchInProgress method.
- The inserted row fails to satisfy constraints defined in the database, for example, the primary key is missing or has an improper value.
See Also
- Accessing Adaptor Sublayer Objects
- Creating Adaptor Sublayer Objects and Connecting Them to the Server
- Accessing Schema Information from the Database Server
- Updating with the Adaptor Sublayer
- Deleting with the Adaptor Sublayer
- Executing Arbitrary SQL Statements
- EOAdaptor class specification in the Enterprise Objects Framework Reference
- EOAdaptorContext class specification in the Enterprise Objects Framework Reference
- EOAdaptorChannel class specification in the Enterprise Objects Framework Reference
Revision History
22 July, 1998. Seejo Pylappan. First Draft.
13 November, 1998. Clif Liu. Second Draft.
16 March, 1999. Clif Liu. Third Draft.
© 1999 Apple Computer, Inc.
