OracleEOAdaptor Framework

Package: com.apple.yellow.oracleeoadaptor

Introduction

The OracleEOAdaptor framework is a set of classes that allow your programs to connect to an Oracle server. These classes provide Oracle-specific method implementations for the EOAccess framework's EOAdaptor, EOAdaptorChannel, EOAdaptorContext, and EOSQLExpression abstract classes.

The following table lists the classes in the OracleEOAdaptor Framework and provides a brief description of each class.

The connection dictionary contains items needed to connect to an Oracle server, such as the server name and database (it's common to omit the user name and password from the connection dictionary, and prompt users to enter those values in a login panel). The keys of this dictionary identify the information the server expects, and the values of those keys are the values that the adaptor uses when trying to connect to the server.

The Oracle adaptor defines string constants for use as connection dictionary keys:

• ServerIdKey
• HostMachineKey
• UserNameKey
• PasswordKey
• ConnectionStringKey
• NlsLangKey

The OracleAdaptor attempts to connect with a connection string of the form "userName/password@serverId". If all the values except the one for ServerIdKey are absent, then OracleAdaptor attempts to connect with just the value for ServerIdKey.

The ConnectionStringKey and NlsLangKey are optional. The value for ConnectionStringKey is a string to be used to login to the database server. If the ConnectionStringKey is present in the connection dictionary, the other logon keys (ServerIdKey, HostMachineKey, UserNameKey, and PasswordKey) are ignored and the value for the ConnectionStringKey is used to connect to the database.

The value for NlsLangKey is used to set the Oracle NLS_LANG environment variable. NLS_LANG declares to the Oracle server the character set being used by the client, as well as the language in which you want server error messages to appear. The format is as follows:

For example, supplying the value japanese_japan.jeuc for the NlsLangKey tells the server that the language is Japanese, the territory is Japan, and the character set is jeuc. See your Oracle documentation for a complete list of types available for this field.

To add the NlsLangKey and a value to your connection dictionary, you can manually edit your model file. For example:

connectionDictionary = {
    password = tiger; 
    serverId = sjOracle; 
    userName = scott;
    NLS_LANG = american_america.us7ascii;
};

Subsequently changing the connection dictionary in your model file using the Set Adaptor Info command in EOModeler has no effect on these keys and their values-they are preserved unless you edit the file to remove them.

The default character set for Japanese systems is jeuc. If you are using a non-Japanese system, the default is whatever Oracle provides. You only need to add the NlsLangKey to your connection dictionary if you are using a character set other than your system's default.

Locking

All adaptors use the database server's native locking facilities to lock rows on the server. The Oracle adaptor locks a row by using the SELECT... FOR UPDATE... statement. This occurs when:

• You send the adaptor channel a selectAttributes message with true specified as the value for the lock keyword.
• You explicitly lock an object's row with the EODatabaseContext's lockObjectWithGlobalID message.
• You set pessimistic locking at the database level and fetch objects.

Data Type Mapping

Every adaptor provides a mapping between each server data type and the Java type to which a database value will be coerced when it's fetched from the database. The following table lists the mapping used by OracleAdaptor.

The type mapping methods-externalTypesWithModel, internalTypeForExternalTypeInModel, and isValidQualifierTypeInModel-allow for an adaptor to supplement its set of type mappings with additional mappings for user-defined database types. OracleAdaptor does not make use of the model argument if one is provided.

Prototype Attributes

The OracleAdaptor Framework provides the following set of prototype attributes:

Handling Errors

OracleChannel provides a method for handling errors: raiseOracleError. This method is invoked whenever the channel encounters an error reported by the Oracle server.

Generating Primary Keys

Each adaptor provides a database-specific implementation of the method primaryKeyForNewRowWithEntity for generating primary keys. The OracleChannel's implementation uses sequence objects to provide primary key values. The statement used to create the sequence is:

create sequence table_SEQ

where table is the name of the table for which the adaptor provides primary key values. The adaptor sets the sequence start value to the corresponding table's maximum primary key value plus one.

To use OracleChannel's database-specific primary key generation mechanism, be sure that your database accommodates the adaptor's scheme. To modify your database so that it supports the adaptor's mechanism for generating primary keys, use EOModeler. For more information on this topic, see Enterprise Objects Framework Developer's Guide.

Bind Variables

The OracleAdaptor uses bind variables. A bind variable is a placeholder used in an SQL statement that is replaced with an actual value after the database server determines an execution plan. You use the following OracleSQLExpression methods to operate on bind variables:

• bindVariableDictionaryForAttribute
• mustUseBindVariableForAttribute
• shouldUseBindVariableForAttribute