Documentation Archive Developer
[an error occurred while processing this directive] PATH  Documentation > WebObjects 4.5 > OracleEOAdaptor Reference

Table of Contents

OracleEOAdaptor Framework

Framework: System/Library/Frameworks/OracleEOAdaptor.framework
Header File Directories: System/Library/Frameworks/OracleEOAdaptor.framework/Headers


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.

OracleAdaptorRepresents a single connection to a Oracle database server, and is responsible for keeping login and model information, performing Oracle-specific formatting of SQL expressions, and reporting errors.
OracleChannelRepresents an independent communication channel to the database server its OracleAdaptor is connected to.
OracleContextRepresents a single transaction scope on the database server to which its adaptor object is connected.
OracleSQLExpressionDefines how to build SQL statements for OracleChannels.

The Connection Dictionary

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:

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:

language_territory. characterSet

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.


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:

Data Type Mapping

Every adaptor provides a mapping between each server data type and the Objective-C 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.

Enterprise Objects Framework uses Mac OS X Server encoding to represent string data, and it passes strings to the database without converting them to the database character set. If you require that the data passed to your server is in an encoding other than Mac OS X Server encoding, you need to subclass NSString.
Oracle Data TypeObjective-C Data Type

The type mapping methods-externalTypesWithModel:, internalTypeForExternalType:model:, and isValidQualifierType:model:-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:

NameExternal TypeValue Class NameOther Attributes
binaryIDRAWNSDatawidth = 12
cityVARCHAR2NSStringcolumnName = CITY width = 50
dateDATENSCalendarDatecolumnName = ""
moneyNUMBERNSDecimalNumbercolumnName = ""
phoneNumberVARCHAR2NSStringcolumnName = PHONE width = 20
rawImageLONG RAWNSDatacolumnName = RAW_IMAGE
stateVARCHAR2NSStringcolumnName = STATE width = 2
streetAddressVARCHAR2NSStringcolumnName = STREET_ADDRESS width = 100
tiffImageLONG RAWNSImageadaptorValueConversionMethodName = TIFFRepresentation columnName = PHOTO valueFactoryMethodName = "imageWithData:"
uniqueIDNUMBERNSNumbercolumnName = "" valueType = i
zipCodeVARCHAR2NSStringcolumnName = ZIP width = 10

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. The methods cursorDataArea, hostDataArea, and logonDataArea are used to retrieve Oracle-specific data structures from the channel and context to determine what error has occurred. The hostDataArea and logonDataArea methods are declared in the OracleContext class.

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:

Table of Contents