OracleAdaptor

Inherits From:
EOAdaptor : NSObject

Declared in: OracleEOAdaptor/OracleAdaptor.h

Class Description

An OracleAdaptor represents a single connection to an Oracle database server, and is responsible for keeping login and model information, performing Oracle-specific formatting of SQL expressions, and reporting errors.

The OracleAdaptor class has these restrictions: You can't have nested transactions, and the adaptor doesn't support full outer joins.

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 logon keys for Oracle are as follows:

serverId
hostMachine

userName

password

If there isn't a value for the hostMachine key, then OracleAdaptor attempts to connect with a connection string of the form "userName/password@serverId". If all the values except the one for serverId are absent, then OracleAdaptor attempts to connect with just the value for serverId. For more information on logon keys, see "Using SQL*Net."

The connection dictionary can optionally include two additional keys: connectionString and NLS_LANG. The connectionString contains a string to be used to login to the database server. If the connectionString key is present in the connection dictionary, the other logon keys are ignored and this string is used to connect to the database.

NLS_LANG allows you 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 NLS_LANG key 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 NLS_LANG key and a value to your connection dictionary, you must manually edit your model file. For example:

connectionDictionary = {

    hostMachine = entropy; 

    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 NLS_LANG key to your connection dictionary if you are using a character set other than your system's default.

Note: Enterprise Objects Framework uses OPENSTEP 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 OPENSTEP encoding, you need to subclass NSString.

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:

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.

Oracle Data Type

Objective-C Data Type

VARCHAR2 NSString
NUMBER NSDecimalNumber
LONG NSNumber
ROWID NSNumber
DATE NSCalendarDate
RAW NSData
LONG RAW NSData
CHAR NSString
MLSLABEL NSData
REFCURSOR OracleChannel

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.

Using SQL*Net

The Oracle adaptor supports both SQL*Net v1 and v2-style connection strings. The version of SQL*Net used is determined by the connection string you provide (whether through the login panel or through the connection dictionary in your model file).

To use SQL*Net v1, supply a user name, password, host machine name, and server ID. This results in a v1-style connection string of the form "userName/password@T:hostMachine:serverID."

To use SQL*Net v2, supply a server ID, user name, and password, but omit the host machine name. This results in a v2-style connection string that has the form "userName/password@serverID." If you want to use a custom connection string, omit values for all of the keys except serverId in your connection dictionary. You can then use the Server ID field in the Oracle login panel to supply your own connection string.

Method Types

Mapping external types to internal types
+ externalTypesWithModel:
+ internalTypeForExternalType:model:
Working with channels and contexts
- adaptorChannelClass
- adaptorContextClass
Testing the connection dictionary
- assertConnectionDictionaryIsValid
Getting information from the connection dictionary
- connectionKeys
- oracleConnectionString
Coercing fetched values
- fetchedValueForDataValue:attribute:
- fetchedValueForDateValue:attribute:
- fetchedValueForNumberValue:attribute:
- fetchedValueForStringValue:attribute:
Returning the default expression class
- defaultExpressionClass
Verifying a qualifier type
- isValidQualifierType:model:

Class Methods

externalTypesWithModel:

+ (NSArray *)externalTypesWithModel:(EOModel *)model

Overrides the EOAdaptor method externalTypesWithModel: to return the Oracle database types.

See also: + internalTypeForExternalType:model:

internalTypeForExternalType:model:

+ (NSString *)internalTypeForExternalType:(NSString *)externalType model:(EOModel *)model

Overrides the EOAdaptor method internalTypeForExternalType: to return the name of the Objective-C class used to represent values stored in the database as externalType.

See also: + externalTypesWithModel:

Instance Methods

adaptorChannelClass

- (Class)adaptorChannelClass

Returns the OracleChannel class.

adaptorContextClass

- (Class)adaptorContextClass

Returns the OracleContext class

assertConnectionDictionaryIsValid

- (void)assertConnectionDictionaryIsValid

Overrides the EOAdaptor method assertConnectionDictionaryIsValid to verify that the receiver can connect to the database with its connection dictionary. Briefly forms a connection to the server to validate the connection dictionary and then closes the connection. The adaptor uses this method in conjunction with displaying a server login panel. Raises an exception if an error occurs.

Note that this method doesn't open a connection to the database-that happens when the first adaptor channel is sent an openChannel message.

connectionKeys

- (NSArray *)connectionKeys

Returns an NSArray containing the keys in the receiver's connection dictionary. You can use this method to prompt the user to supply values for the connection dictionary.

defaultExpressionClass

- (Class)defaultExpressionClass

Returns the OracleSQLExpression class.

fetchedValueForDataValue:attribute:

- (NSData *)fetchedValueForDataValue:(NSData *)value attribute:(EOAttribute *)attribute

Returns value.

fetchedValueForDateValue:attribute:

- (NSCalendarDate *)fetchedValueForDateValue:(NSCalendarDate *)date
attribute:(EOAttribute *)attribute

Returns an NSCalendarDate based on date whose millisecond value is set to 0.

fetchedValueForNumberValue:attribute:

- (NSNumber *)fetchedValueForNumberValue:(NSNumber *)numberValue
attribute:(EOAttribute *)attribute

Returns an NSNumber based on numberValue that has been rounded according to the precision and scale specified for attribute.

fetchedValueForStringValue:attribute:

- (NSString *)fetchedValueForStringValue:(NSString *)value attribute:(EOAttribute *)attribute

Provides default processing for string values. Trims trailing spaces and returns nil for 0 length strings.

isValidQualifierType:model:

- (BOOL)isValidQualifierType:(NSString *)typeName model:(EOModel *)model

Overrides the EOAdaptor method isValidQualifierType:model: to return YES if an attribute of type typeName can be used in a qualifier (a SQL WHERE clause) sent to the database server, NO otherwise. typeName is the name of a type as required by the database server, such as an Oracle "NUMBER".

oracleConnectionString

- (NSString *)oracleConnectionString

Returns the user name, password, host machine, and server id as a string suitable to be supplied as an argument to orlon().

Copyright © 1997, Apple Computer, Inc. All rights reserved.