SybaseEOAdaptor Framework

Package: com.apple.yellow.sybaseeoadaptor

Introduction

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

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

The connection dictionary contains items needed to connect to a Sybase 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 Sybase adaptor defines string constants for use as connection dictionary keys:

• HOSTNAME
• DATABASENAME
• USERNAME
• PASSWORD
• LC_ALL_KEY
• ENCRYPTPASSWORD
• PRIMITIVE_TYPE_MAP

The last three keys are optional. The ENCRYPTPASSWORD key provides support for Sybase password encryption. A value for the LC_ALL_KEY declares to the Sybase server the character set being used by the client (such as eucjis, ascii7, or iso_1). For a complete list of types available for this field, see your Sybase documentation. The PRIMITIVE_TYPE_MAP entry describes the mapping of user-defined data types to their base Sybase type (such as varchar or datetime). For more information on user-defined data types, see "Data Type Mapping" .

To add any of these optional keys and appropriate values to your connection dictionary, you can manually edit your model file. For example:

connectionDictionary = {databaseName = People; 
    hostName = ""; 
    LC_ALL = eucjis;
    password = ""; 
    primitiveTypeMap = {id = varchar; ssn = char(9); };
    sybasePasswordEncryption = YES;
    userName = "";
}; 

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. Alternatively you can add the optional keys to a model's connection dictionary programmatically.

The default character set for non-Japanese systems is iso_1 (that is, ISO Latin 1), while the default character set for Japanese systems is eucjis. You only need to add the LC_ALL key to your connection dictionary if you are using a character set other than your system's default.

See the SybaseAdaptor class specification for more information on the connection dictionary key constants.

Error Handling

SybaseAdaptor, SybaseContext, and SybaseChannel can raise exceptions due to programming errors that result in invalid argument values or internal inconsistencies. In addition, messages, errors, and failure status returned from the Sybase SQL Server and client libraries can also result in EOGeneralAdaptorExceptions. When an exception results from a callback to the CS_CLIENTMSG_CB (Sybase ClientMessage callback) or the CS_SERVERMSG_CB (Sybase ServerMessage callback), all of the information passed into this routine is available in the userInfo dictionary contained by the exception. When an exception is raised in response to a Sybase ClientMessage callback, you can get the information provided by the client library as follows:

clientMsgDict =
    localException().userInfo().objectForKey("sybaseClientMessageDictionary");

The clientMsgDict contains the following keys which have values corresponding to those sent in the callback function that raised the exception: msgstring, osstring, sqlstate, severity, msgnumber, osnumber, status.

Similarly, when the exception is raised in response to a Sybase ServerMessage callback, you can get the information provided by the server as follows:

svrMsgDict = localException().userInfo().objectForKey("sybaseServerMessageDictionary");

The svrMsgDict contains the following keys which have values corresponding to those sent in the callback function that raised the exception: text, svrname, proc, sqlstate, msgnumber, state, severity, line, status.

Locking

All adaptors use the database server's native locking facilities to lock rows on the server. The Sybase adaptor locks a row by using the HOLDLOCK keyword in SELECT statements. 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.

The semantics of the HOLDLOCK keyword are such that when you lock a row other users can't update it, but it doesn't guarantee that your update will succeed. This is because other users could be holding a lock on the same row. However, you can still read rows that are locked by other users.

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

In addition, SybaseAdaptor provides a mapping for user-defined data types. For example, a custom data type partnumber defined as char(10) is mapped to String-the Java type to which partnumber's base data type (char) is mapped. SybaseAdaptor's implementation of describeModelWithTableNames automatically creates mappings for user-defined data types and saves them in the connection dictionary of the newly created model. Consequently, even models created with EOModeler automatically include information about custom data types.

Since information about custom types is stored in a model's connection dictionary, the type mapping methods- externalToInternalTypeMap, internalTypeForExternalType, and isValidQualifierType-use the model argument if it is provided. If the model argument isn't provided, these methods don't have user-defined data type information available to them.

Prototype Attributes

The SybaseEOAdaptor Framework provides the following set of prototype attributes:

Generating Primary Keys

Each adaptor provides a database-specific implementation of the method primaryKeyForNewRowWithEntity for generating primary keys. The SybaseChannel's implementation uses a table named eo_sequence_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. The statement used to create the eo_sequence_table is:

create table eo_sequence_table (
    table_name varchar(32),
    counter int null
)

SybaseChannel uses a stored procedure named eo_pk_for_table to access and maintain the primary key counter in eo_sequence_table. The stored procedure is defined as follows:

create procedure
eo_pk_for_table @tname varchar(32) as
begin
    define @max int

    update eo_sequence_table
    set counter = counter + 1
    where table_name = @tname

    select counter
    from eo_sequence_table
    where table_name = @tname
end

The stored procedure increments the counter in the eo_sequence_table row for the specified table, selects the counter value, and returns it. SybaseChannel executes this eo_pk_for_table stored procedure from primaryKeyForNewRowWithEntity and returns the stored procedure's return value.

To use SybaseChannel'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.