EOAdaptor

Inherits from: Object

Package: com.webobjects.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.

Note: EOAdaptor is abstract. Never create instances of the EOAdaptor class.

The EOAdaptor class has the following principal attributes:

Dictionary of connection information
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:

Method Description

assertConnectionDictionaryIsValid Verifies that the adaptor can connect with its connection information.

setConnectionDictionary Sets the connection dictionary.

For information on subclassing an EOAdaptor, see "Creating an EOAdaptor Subclass" (page 35).

Method Types

Creating an EOAdaptoradaptorWithName adaptorWithModelAccessing an adaptor's namenameConnecting to a database serverassertConnectionDictionaryIsValid connectionDictionary setConnectionDictionary isDroppedConnectionException handleDroppedConnectionPerforming database-specific transformations on valuesfetchedValueForValue fetchedValueForDataValue fetchedValueForDateValue fetchedValueForNumberValue fetchedValueForStringValueServicing modelscanServiceModel internalTypeForExternalType externalTypesWithModel assignExternalInfoForEntireModel assignExternalInfoForEntity assignExternalInfoForAttribute isValidQualifierTypeCreating adaptor contextscreateAdaptorContext contextsChecking connection statushasOpenChannelsAccessing a default expression classsetExpressionClassName expressionClass defaultExpressionClassAccessing the delegatedelegate setDelegate setDefaultDelegate defaultDelegateCreating and dropping databasescreateDatabaseWithAdministrativeConnectionDictionary dropDatabaseWithAdministrativeConnectionDictionaryProviding prototype attributesprototypeAttributes

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 EOAdaptor 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 synchronized EOAdaptor 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.

defaultDelegate

public static Object defaultDelegate()

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

expressionClassName

public static String expressionClassName(String className)

Description forthcoming.

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 synchronized 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

Instance Methods

administrativeConnectionDictionaryForAdaptor

public NSDictionary administrativeConnectionDictionaryForAdaptor(EOAdaptor adaptor)

This method, formerly provided by the EOLoginPanel class, returns the administrative connection dictionary for the specified adaptor.

assertConnectionDictionaryIsValid

public abstract 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

assignExternalInfoForAttribute

public 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.

See Also: assignExternalInfoForEntireModel

assignExternalInfoForEntireModel

public 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 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.

See Also: assignExternalInfoForEntireModel

assignExternalTypeForAttribute

public 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.

See Also: assignExternalInfoForEntireModel

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 abstract 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.

defaultExpressionClass

public abstract 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.

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.

expressionFactory

public abstract EOSQLExpressionFactory expressionFactory()

Supports changes made to EOSQLExpression and related classes and interfaces. Returns the EOExpressionFactory for the adaptor. For more information, see the section for EOSQLExpression.

externalTypesWithModel

public 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.

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 NSTimestamp fetchedValueForDateValue( NSTimestamp 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 method adaptorFetchedValueForValue which can override the adaptor's default behavior.

See Also: fetchedValueForDataValue, fetchedValueForDateValue, fetchedValueForNumberValue, fetchedValueForStringValue, valueFactoryMethod (EOAttribute)

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)

internalTypeForExternalType

public 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.

isDatabaseConnectionException

public boolean isDatabaseConnectionException(Exception exception)

Returns true if the specified exception has been raised due to a database connection failure or false otherwise.

isDroppedConnectionException

public boolean isDroppedConnectionException(Exception anException)

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.

See Also: handleDroppedConnection, reconnectionDictionaryForAdaptor ( EOAdaptor)

isValidQualifierType

public abstract 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

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.

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.

synchronizationFactory

public abstract EOSchemaGeneration synchronizationFactory()

Supports changes made to EOSQLExpression and related classes and interfaces. Returns the EOSynchronizationFactory for the adaptor. For more information, see the section for EOSQLExpression.

Method	Description
assertConnectionDictionaryIsValid	Verifies that the adaptor can connect with its connection information.
setConnectionDictionary	Sets the connection dictionary.