PATH Documentation > WebObjects 4.5 > EOAdaptor Reference

EOAdaptor

Inherits from: NSObject

Package: com.apple.yellow.eoaccess

Class Description

EOAdaptor is an abstract class that provides concrete subclasses with a structure for connecting to a database. A concrete subclass of EOAdaptor provides database-specific method implementations and represents a single database server. You never interact with instances of the EOAdaptor class, but you use its static methods, adaptorWithName and adaptorWithModel, to create instances of a concrete subclass. The EOAdaptor class defines the methods that find and load the concrete adaptors from bundles. However, you rarely interact with a concrete adaptor either. Generally, adaptors are automatically created and used by other classes in the Enterprise Objects Framework.

The EOAdaptor class has the following principal attributes:

Dictionary of connection information
Login panel
Array of adaptor contexts
Expression class

Other framework classes create EOAdaptor objects. adaptorWithModel creates a new adaptor with the adaptor name in the specified model. adaptorWithName creates a new adaptor with the specified name.

The following table lists the most commonly-used methods in the EOAdaptor class:

EOAdaptor isn't declared to be abstract, but conceptually it is abstract. Never create instances of the EOAdaptor class.

Method	Description
assertConnectionDictionaryIsValid	Verifies that the adaptor can connect with its connection information.
runLoginPanel	Runs the login panel without affecting the connection dictionary.
runLoginPanelAndValidateConnectionDictionary	Runs the login panel until the user enters valid connection information or cancels the panel.
setConnectionDictionary	Sets the connection dictionary.

For information on subclassing an EOAdaptor, see "Creating an EOAdaptor Subclass" .

Constants

EOAdaptor defines one constant, a String, as described below:

Constant	Description
`GeneralAdaptorException`	The name of exceptions raised by adaptors when errors occur during interactions with their database servers.

Method Types

Creating an EOAdaptor

adaptorWithName

adaptorWithModel

Accessing an adaptor's name

name

Accessing the names of all available adaptors

availableAdaptorNames

Connecting to a database server

assertConnectionDictionaryIsValid

connectionDictionary

setConnectionDictionary

runLoginPanelAndValidateConnectionDictionary

runLoginPanel

isDroppedConnectionException

handleDroppedConnection

Encoding database strings

databaseEncoding

Performing database-specific transformations on values

fetchedValueForValue

fetchedValueForDataValue

fetchedValueForDateValue

fetchedValueForNumberValue

fetchedValueForStringValue

Servicing models

canServiceModel

internalTypeForExternalType

externalTypesWithModel:

assignExternalInfoForEntireModel:

assignExternalInfoForEntity

assignExternalInfoForAttribute

isValidQualifierType

Creating adaptor contexts

createAdaptorContext

contexts

Checking connection status

hasOpenChannels

Accessing a default expression class

setExpressionClassName

expressionClass

defaultExpressionClass

Accessing an adaptor's login panel

sharedLoginPanelInstance

runLoginPanelAndValidateConnectionDictionary

runLoginPanel

Accessing the delegate

delegate

setDelegate

setDefaultDelegate

defaultDelegate

Creating and dropping databases

createDatabaseWithAdministrativeConnectionDictionary

dropDatabaseWithAdministrativeConnectionDictionary

Providing prototype attributes

prototypeAttributes

Synchronizing the database with a model

objectStoreChangesFromAttributeToAttribute

Constructors

EOAdaptor

public EOAdaptor(String name)

Creates and returns a new EOAdaptor with name. name is usually derived from the base filename (that is, the filename without the ".framework" extension) of the framework from which the adaptor is loaded. For example, the Oracle adaptor is loaded from the framework OracleEOAdaptor.framework. When you create an adaptor subclass, override this method to create a new adaptor with name.

Never use this constructor directly. It is invoked automatically from adaptorWithName and adaptorWithModel-EOAdaptor static methods you use to create a new adaptor.

Static Methods

adaptorWithModel

public static Object adaptorWithModel(EOModel model)

Creates and returns a new adaptor by extracting the adaptor name from model, invoking adaptorWithName, and assigning model's connection dictionary to the new adaptor. Throws an exception if model is null, if model's adaptor name is null, or if the adaptor named in model can't be loaded.

A subclass of EOAdaptor doesn't need to implement this method. A subclass that does implement this method must incorporate the superclass's version.

See Also: adaptorName ( EOModel), setConnectionDictionary

adaptorWithName

public static Object adaptorWithName(String name)

Creates and returns a new adaptor, loading it from the framework named name if necessary. For example, this code excerpt creates an adaptor from a framework named AcmeEOAdaptor.framework:

EOAdaptor myAdaptor = (EOAdaptor)EOAdaptor.adaptorWithName("Acme");

This method searches the application's main bundle, ~/Library/Frameworks, Network/Library/Frameworks, and System/Library/Frameworks for the first framework whose base filename (that is, the filename without the ".framework" extension) corresponds to name. Throws an exception if name is null or if an adaptor class corresponding with name can't be found.

Usually you'd use adaptorWithModel to create a new adaptor, but you can use this method when you don't have a model. In fact, this method is typically used when you're creating an adaptor for the purpose of creating a model from an existing database.

assignExternalInfoForAttribute

public static void assignExternalInfoForAttribute(EOAttribute attribute)

Implemented by adaptor subclasses to assign database-specific characteristics to attribute. EOAdaptor's implementation invokes assignExternalTypeForAttribute to assign an external type, and then it assigns a column name based on the attribute name. For example, assignExternalInfoForAttribute assigns the column name "FIRST_NAME" to an attribute named "firstName". The method makes no changes to attribute's column name if attribute is derived.

A subclass of EOAdaptor doesn't need to implement this method. A subclass that does implement this method must incorporate the superclass's version.

assignExternalInfoForEntireModel:

public static void assignExternalInfoForEntireModel(EOModel model)

Assigns database-specific characteristics to model. Used in EOModeler to switch a model's adaptor. This method examines each entity in model. If an entity's external name is not set and all of the entity's attribute's external names are not set, then this method uses assignExternalInfoForEntity and assignExternalInfoForAttribute to assign external names. If the entity's external name is set or if any of the entity's attributes' external names are set, then the method doesn't assign external names to the entity or any of its attributes. Regardless, this method assigns external types for all the model's attributes.

A subclass of EOAdaptor doesn't need to implement this method.

assignExternalInfoForEntity

public static void assignExternalInfoForEntity(EOEntity entity)

Implemented by adaptor subclasses to assign database-specific characteristics to entity. EOAdaptor's implementation assigns an external name to entity based on entity's name. For example, assignExternalInfoForEntity assigns the external name "MOVIE" to an entity named "Movie".

An adaptor subclass should implement this method to assign additional database-specific characteristics, if any. A subclass that does implement this method must incorporate the superclass's version.

assignExternalTypeForAttribute

public static void assignExternalTypeForAttribute(EOAttribute attribute)

Overridden by adaptor subclasses to assign the external type to attribute. EOAdaptor's implementation does nothing.

An adaptor subclass should implement this method to assign an external type using attribute's internal type, precision, and length information. A subclass that does implement this method should incorporate the superclass's version.

availableAdaptorNames

public static NSArray availableAdaptorNames()

Returns an array containing the names of all available adaptors. If no adaptors are found, this method returns an empty array.

defaultDelegate

public static Object defaultDelegate()

Returns the default delegate-the object that is assigned to new adaptor instances as their delegate.

externalTypesWithModel:

public static NSArray externalTypesWithModel(EOModel model)

Implemented by subclasses to return the names of the database types (such as Sybase "varchar" or Oracle "NUMBER") for use with the adaptor. model is an optional argument that can be used to supplement the adaptor's set of database types with additional, user-defined database types. See your adaptor's documentation for information on if and how it uses model.

An adaptor subclass should implement this method.

internalTypeForExternalType

public static String internalTypeForExternalType( String extType, EOModel model)

Implemented by subclasses to return the name of the class used to represent values stored in the database as extType. model is an optional argument that can be used to supplement the adaptor's set of type mappings with additional mappings for user-defined database types. See your adaptor's documentation for information on if and how it uses model. Returns null if no mapping for extType is found.

An adaptor subclass should implement this method without invoking EOAdaptor's implementation.

setDefaultDelegate

public static void setDefaultDelegate(Object anObject)

Sets the default delegate-the object assigned as delegate to all newly created EOAdaptor instances. By default, there is no default delegate.

setExpressionClassName

public static void setExpressionClassName( String sqlExpressionClassName, String adaptorClassName)

Sets the expression class for instances of the class named adaptorClassName to sqlExpressionClassName. If sqlExpressionClassName is null, restores the expression class to the default. Throws an exception if adaptorClassName is null or the empty string.

Use this method to substitute a subclass of EOSQLExpression for the expression class provided by the adaptor.

A subclass of EOAdaptor doesn't need to implement this method. A subclass that does implement this method must incorporate the superclass's version.

See Also: defaultExpressionClass

sharedLoginPanelInstance

public static EOLoginPanel sharedLoginPanelInstance()

Returns the receiver's login panel in applications that have a graphical user interface. Returns null if the application doesn't have an NSApplication object. Otherwise, looks for the bundle named "LoginPanel" in the resources for the adaptor framework, loads the bundle, and returns an instance of the bundle's principal class (see the NSBundle class specification for information on loading bundles). The returned object is used to implement runLoginPanelAndValidateConnectionDictionary and runLoginPanel.

A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version through a message to super.

Instance Methods

assertConnectionDictionaryIsValid

public void assertConnectionDictionaryIsValid()

Implemented by subclasses to verify that the adaptor can connect to the database server with its connection dictionary. Briefly forms a connection to the server to validate the connection dictionary and then closes the connection. Throws an exception if the connection dictionary contains invalid information.

An adaptor subclass must override this method without invoking EOAdaptor's implementation.

See Also: setConnectionDictionary

canServiceModel

public boolean canServiceModel(EOModel model)

Returns true if the receiver can service model, false otherwise. EOAdaptor's implementation returns true if the receiver's connection dictionary is equal to model's connection dictionary as determined by NSDictionary's isEqual method.

A subclass of EOAdaptor doesn't need to override this method.

connectionDictionary

public NSDictionary connectionDictionary()

Returns the receiver's connection dictionary, or null if the adaptor doesn't have one. The connection dictionary contains the values, such as user name and password, needed to connect to the database server. The dictionary's keys identify the information the server expects, and its values are the values that the adaptor will try when connecting. Each adaptor uses different keys; see your adaptor's documentation for keys it uses.

A subclass of EOAdaptor doesn't need to override this method.

contexts

public NSArray contexts()

Returns the adaptor contexts created by the receiver, or null if no adaptor contexts have been created. A subclass of EOAdaptor doesn't need to override this method.

See Also: createAdaptorContext

createAdaptorContext

public EOAdaptorContext createAdaptorContext()

Implemented by subclasses to create and return a new EOAdaptorContext, or null if a new context can't be created. A newly created EOAdaptor has no contexts.

An adaptor subclass must override this method without invoking EOAdaptor's implementation.

See Also: contexts

createDatabaseWithAdministrativeConnectionDictionary

public void createDatabaseWithAdministrativeConnectionDictionary( NSDictionary connectionDictionary)

Uses the administrative login information to create the database (or user for Oracle) defined by connectionDictionary.

databaseEncoding

public int databaseEncoding()

Returns the string encoding used to encode and decode database strings. A database system stores strings in a particular character set. The Framework needs to know what character set the database system uses so it can encode and decode strings coming from and going to the database server. The string encoding returned from this method specifies the character set the Framework uses.

An adaptor's database encoding is stored in the connection dictionary with the key "databaseEncoding". If the connection dictionary doesn't have an entry for the database encoding, the default C string encoding is used. This method throws an exception if the receiver's database encoding isn't valid.

A subclass of EOAdaptor doesn't need to override this method.

defaultExpressionClass

public Class defaultExpressionClass()

Implemented by subclasses to return the subclass of EOSQLExpression used as the default expression class for the adaptor. You wouldn't ordinarily invoke this method directly. It's invoked automatically to determine which class should be used to represent query language expressions.

An adaptor subclass must override this method without invoking EOAdaptor's implementation.

See Also: setExpressionClassName

delegate

public Object delegate()

Returns the receiver's delegate or null if a delegate has not been assigned. A subclass of EOAdaptor doesn't need to override this method.

dropDatabaseWithAdministrativeConnectionDictionary

public void dropDatabaseWithAdministrativeConnectionDictionary( NSDictionary connectionDictionary)

Uses the administrative login information to drop the database (or user for Oracle) defined by the connectionDictionary.

See Also: createDatabaseWithAdministrativeConnectionDictionary, EOLoginPanel class

expressionClass

public Class expressionClass()

Returns the subclass of EOSQLExpression used by the receiver for query language expressions. Returns the expression class assigned using the class method setExpressionClassName. If no class has been set for the receiver's class, this method determines the expression class by sending defaultExpressionClass to this.You rarely need to invoke this method yourself. It's invoked by the Framework to determine the class to use to represent query language expressions. You should, however, use this method if you explicitly create EOSQLExpression instances. To be sure you're using the correct expression class, create instances of the class returned from this method.

A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version through a message to super.

fetchedValueForDataValue

public NSData fetchedValueForDataValue( NSData value, EOAttribute attribute)

Overridden by subclasses to return the value that the receiver's database server would ultimately store for value if it was inserted or updated in the column described by attribute. This method is invoked from fetchedValueForValue when the value argument is an NSData.

EOAdaptor's implementation returns value unchanged. An adaptor subclass should override this method if the adaptor's database performs transformations on binary types, such as BLOBs.

fetchedValueForDateValue

public NSGregorianDate fetchedValueForDateValue( NSGregorianDate value, EOAttribute attribute)

EOAdaptor's implementation returns value unchanged. An adaptor subclass should override this method to convert or format date values. For example, a concrete adaptor subclass could set value's millisecond value to 0.

fetchedValueForNumberValue

public Number fetchedValueForNumberValue( Number value, EOAttribute attribute)

EOAdaptor's implementation returns value unchanged. An adaptor subclass should override this method to convert or format numeric values. For example, a concrete adaptor subclass should probably round value according to the precision and scale attribute.

fetchedValueForStringValue

public String fetchedValueForStringValue( String value, EOAttribute attribute)

EOAdaptor's implementation trims trailing spaces and returns null for zero-length strings. An adaptor subclass should override this method to perform any additional conversion or formatting on string values.

fetchedValueForValue

public Object fetchedValueForValue( Object value, EOAttribute attribute)

Returns the value that the receiver's database server would ultimately store for value if it was inserted or updated in the column described by attribute. The Framework uses this method to keep enterprise object snapshots in sync with database values. For example, assume that a product's price is marked down 15%. If the product's original price is 5.25, the sale price is 5.25*.85, or 4.4625. When the Framework updates the product's price, the database server truncates the price to 4.46 (assuming the scale of the database's price column is 2). Before performing the update, the Framework sends the adaptor a fetchedValueForValue message with the value 4.4625. The adaptor performs the database-specific transformation and returns 4.46. The Framework assigns the truncated value to the product object and to the product object's snapshot and then proceeds with the update.

An adaptor subclass can override this method or one of the data type-specific fetchedValue... methods. EOAdaptor's implementation of fetchedValueForValue invokes one of the data type-specific methods depending on value's class. If value is not a string, number, date, or data object (that is, an instance of String, Number, NSGregorianDate, NSData, or any of their subclasses), fetchedValueForValue returns value unchanged.

This method invokes the EOAdaptor.Delegate method adaptorFetchedValueForValue which can override the adaptor's default behavior.

handleDroppedConnection

public void handleDroppedConnection()

Invoked when necessary to clean up after a dropped connection. Sends handleDroppedConnection to all of its adaptor contexts and then clears its array of contexts. If the delegate implements reconnectionDictionaryForAdaptor, that method is invoked, and the return value is assigned to the adaptor as its new connection dictionary.

You should never invoke this method; it is invoked automatically by the Framework. Subclasses don't normally need to override the superclass implementation.

hasOpenChannels

public boolean hasOpenChannels()

Returns true if any of the receiver's contexts have open channels, false otherwise. A subclass of EOAdaptor doesn't need to override this method.

See Also: hasOpenChannels ( EOAdaptorContext)

isDroppedConnectionException

public boolean isDroppedConnectionException(Throwable aThrowable)

Returns true if the exception is one that the adaptor can attempt to recover from by reconnecting to the database, false otherwise.

Invoked if an exception is raised during fetching or saving. If the adaptor returns true, then the adaptor attempts to reconnect to the database and retries the operation. If the reconnection attempt fails, the exception from the failure is raised as usual. If the adaptor returns false, reconnection isn't attempted and the exception is raised.

The default implementation of isDroppedConnectionException: returns false. Subclasses that support database reconnection should implement this method to allow for automatic database reconnection.

isValidQualifierType

public boolean isValidQualifierType( String typeName, EOModel model)

Implemented by subclasses to return true if an attribute of type typeName can be used in a qualifier (a SQL WHERE clause) sent to the database server, or false otherwise. typeName is the name of a type as required by the database server, such as Sybase "varchar" or Oracle "NUMBER". model is an optional argument that can be used to supplement the adaptor's set of type mappings with additional mappings for user-defined database types. See your adaptor's documentation for information on if and how it uses model.

An adaptor subclass must override this method without invoking EOAdaptor's implementation.

name

public String name()

Returns the adaptor's name; this is usually the base filename of the framework from which the adaptor was loaded. For example, if an adaptor was loaded from a framework named AcmeEOAdaptor.framework, this method returns "Acme".

A subclass of EOAdaptor doesn't need to override this method.

See Also: adaptorWithName

objectStoreChangesFromAttributeToAttribute

public NSDictionary objectStoreChangesFromAttributeToAttribute( EOAttribute schemaAttribute, EOAttribute modelAttribute)

Returns a dictionary describing the changes to synchronize schemaAttribute (the attribute reflecting the definition of a column in the database) with modelAttribute (the attribute as it's defined in the model).

prototypeAttributes

public NSArray prototypeAttributes()

Returns an array of prototype attributes specific to the adaptor class. Adaptor writers should note that this method looks for an EOModel named EOadaptorNamePrototypes in the resources directory of the adaptor.

runLoginPanel

public NSDictionary runLoginPanel()

Runs the adaptor's login panel by sending a runLoginPanelAndValidateConnectionDictionarymessage to the adaptor's login panel object with the validate flag false. Returns connection information entered in the panel without affecting the adaptor's connection dictionary. The connection dictionary returned isn't validated by this method.

A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version through a message to super.

runLoginPanelAndValidateConnectionDictionary

public boolean runLoginPanelAndValidateConnectionDictionary()

Runs the adaptor's login panel by sending a runPanelForAdaptormessage to the adaptor's login panel object with the validate flag true. Returns true if the user enters valid connection information, or false if the user cancels the panel.

A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version through a message to super.

setConnectionDictionary

public void setConnectionDictionary(NSDictionary dictionary)

Sets the adaptor's connection dictionary to dictionary, which must only contain String, NSData, NSDictionary, and NSArray objects. Throws an exception if there are any open channels-you can't change connection information while the adaptor is connected.

A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version through a message to super.

setDelegate

public void setDelegate(Object delegate)

Sets the receiver's delegate to delegate, or removes its delegate if delegate is null. A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version through a message to super.