Framework:
com.apple.yellow.odbceoadaptor
Header File Directories:
System/Developer/Java/Headers
Introduction
The ODBCEOAdaptor framework is a set of classes that allow your programs to connect to an ODBC server. These classes provide ODBC-specific method implementations for the EOAccess framework's EOAdaptor, EOAdaptorChannel, EOAdaptorContext, and EOSQLExpression abstract classes.
ODBC (Open Data Base Connectivity) defines a standard interface that Windows applications can use to access any data source. Unlike the other Enterprise Objects Frameworks adaptors that support a single type of database, the ODBC adaptor supports any data source that has an ODBC driver. Consequently, in addition to having standard adaptor features, the ODBC adaptor also manages information relating to the driver and to the data types defined by the data source the driver supports.
The following table lists the classes in the ODBCEOAdaptor Framework and provides a brief description of each class.
Class | Description |
---|---|
ODBCAdaptor | Represents a single connection to a ODBC database server, and is responsible for keeping login and model information, performing ODBC-specific formatting of SQL expressions, and reporting errors. |
ODBCChannel | Represents an independent communication channel to the database server its ODBCAdaptor is connected to. |
ODBCContext | Represents a single transaction scope on the database server to which its adaptor object is connected. |
ODBCSQLExpression | Defines how to build SQL statements for ODBCChannels. |
The Connection Dictionary
The connection dictionary contains items needed to connect to an ODBC server, such as the data source (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. For ODBC the required keys are as follows:
dataSource
userName
password
The connection dictionary can also optionally have the keys connectionString, typeInfo, and driverInfo.
The connectionString contains the user name, password, and data source. If the connectionString key is present in the connection dictionary, the other login keys are ignored and this string is used to connect to the database.
The typeInfo key refers to the typeInfo dictionary, which is used to cache type information in the connection dictionary. This is done because different ODBC drivers work with different data types. Caching type information in the connection dictionary avoids costly connections to the driver and the database. The typeInfo dictionary contains the following information for every type in your database:
defaultODBCType = (<CHAR/TIMESTAMP/BIT/...>, ...)
precision = <precision>
minScale = <minScale>
maxScale = <maxScale>
isUnsigned = <YES/NO>
isNullable = <YES/NO>
isSearchable = <YES/NO>
createParams = <0/1/2>
Likewise, the driverInfo key refers to the driverInfo dictionary, which stores information about the driver, such as its name and version. This information is also cached in the connection dictionary.
Locking
All adaptors use the database server's native locking facilities to lock rows on the server. If you're using the Microsoft SQL Server, the ODBC adaptor locks a row by using the HOLDLOCK keyword in SELECT statements. In all other cases it uses the SELECT... FOR UPDATE... statement. Locking occurs when:
selectAttributesWithFetchSpecification
message with true
specified as the value for the lock
keyword.
lockObjectWithGlobalID
message.
For example, the following table shows the mapping from some of the Microsoft Access database data types to ODBC to Objective-C and Java:
Microsoft Access Database Type | Generic ODBC Type | Objective-C Type | Java Data Type |
---|---|---|---|
TEXT | SQL_VARCHAR | NSString | String |
CURRENCY | SQL_NUMERIC | NSDecimalNumber | BigDecimal |
BINARY | SQL_BINARY | NSData | NSData |
DATETIME | SQL_TIMESTAMP | NSCalendarDate | NSGregorianDate |
The following table lists the mapping between generic ODBC types and Objective-C types.
ODBC Data Type | Objective-C Data Type | Java Data Type |
---|---|---|
SQL_VARCHAR | NSString | String |
SQL_CHAR | NSString | String |
SQL_LONGVARCHAR | NSString | String |
SQL_DECIMAL | NSDecimalNumber | BigDecimal |
SQL_NUMERIC | NSDecimalNumber | BigDecimal |
SQL_BIGINT | NSNumber | Number |
SQL_SMALLINT | NSNumber | Number |
SQL_INTEGER | NSNumber | Number |
SQL_REAL | NSNumber | Number |
SQL_FLOAT | NSNumber | Number |
SQL_DOUBLE | NSNumber | Number |
SQL_BIT | NSNumber | Number |
SQL_TINYINT | NSNumber | Number |
SQL_VARBINARY | NSData | NSData |
SQL_BINARY | NSData | NSData |
SQL_LONGVARBINARY | NSData | NSData |
SQL_TIMESTAMP | NSCalendarDate | NSGregorianDate |
SQL_DATE | NSCalendarDate | NSGregorianDate |
SQL_TIME | NSCalendarDate | NSGregorianDate |
Prototype Attributes
The ODBCEOAdaptor Framework provides the following set of prototype attributes:
Name | External Type | Value Class Name | Other Attributes |
---|---|---|---|
binaryID | BINARY | NSData | width = 12 |
city | CHAR | NSString | columnName = CITY width = 50 |
date | DATETIME | NSCalendarDate | columnName = "" |
longText | LONGTEXT | NSString | |
money | CURRENCY | NSDecimalNumber | columnName = "" |
phoneNumber | CHAR | NSString | columnName = PHONE width = 20 |
rawImage | LONGBINARY | NSData | columnName = RAW_IMAGE |
state | CHAR | NSString | columnName = STATE; width = 2 |
streetAddress | CHAR | NSString | columnName = STREET_ADDRESS width = 100 |
tiffImage | LONGBINARY | NSImage | adaptorValueConversionMethodName = TIFFRepresentation columnName = PHOTO valueFactoryMethodName = "imageWithData:"; |
uniqueID | LONG | NSNumber | columnName = "" valueType = i |
zipCode | CHAR | NSString | columnName = ZIP width = 10 |
Generating Primary Keys
Each adaptor provides a database-specific implementation of the method primaryKeyForNewRowWithEntity:
for generating primary keys. The ODBCChannel's implementation uses a table named EO_PK_TABLE to keep track of the next available primary key value for a given table. The table contains a row for each table for which the adaptor provides primary key values.
ODBCChannel's implementation of primaryKeyForNewRowWithEntity:
attempts to select a value from the EO_PK_TABLE for the new row's table. If the attempt fails because the table doesn't exist, the adaptor creates the table using the following SQL statement:
CREATE TABLE EO_PK_TABLE (
NAME TEXT_TYPE(40),
PK NUMBER_TYPE
)
where TEXT_TYPE is the external (database) type for characters and NUMBER_TYPE is the external type for the table's primary key attribute. The ODBC adaptor sets the PK value for each row to the corresponding table's maximum primary key value plus one. After determining a primary key value for the new row, the ODBC adaptor updates the counter in the corresponding row in EO_PK_TABLE.
For more information on this topic, see Enterprise Objects Framework Developer's Guide.