com.webobjects.eoaccess
Class EOAdaptor

java.lang.Object
  |
  +--com.webobjects.eoaccess.EOAdaptor

Direct Known Subclasses:

JDBCAdaptor, JNDIAdaptor

public abstract class EOAdaptor

extends Object

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

An EOAdaptor can manage several EOAdaptorContexts, each of which represents a transaction scope on the database server. An EOAdaptorContext can, in turn, manage several EOAdaptorChannels, each of which handles actual access to the data on the server. An EOAdaptor by default has no EOAdaptorContexts. To create a new EOAdaptorContext, use the EOAdaptor method createAdaptorContext.

EOAdaptor is an abstract class that provides concrete subclasses with a structure for connecting to a database. You never instantiate the EOAdaptor class, but you can use its static methods, adaptorWithName and adaptorWithModel, to create instances of a concrete subclass. However, you rarely interact directly 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
• Array of adaptor contexts
• Expression class

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

Connecting to the Server

An EOAdaptor uses a connection dictionary to connect to the database server. The keys of this dictionary identify the information the server expects, and the values of those keys are the values that the adaptor will try when connecting.

A connection to the database server isn't actually formed until an adaptor channel is opened. When the adaptor is asked to validate its connection dictionary, it only confirms with the server that it will accept the values in the dictionary when a connection is requested.

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.

Creating an EOAdaptor Subclass

Enterprise Objects Framework provides a concrete JDBC adaptor for communication with JDBC-compliant relational databases and a concrete JNDI adaptor for communication with LDAP data sources. You may want to create your own concrete EOAdaptor subclass for a different database or persistent storage system. EOAdaptor provides many default method implementations that are sufficient for concrete subclasses:

• assignExternalInfoForEntireModel
• connectionDictionary
• contexts
• delegate
• hasOpenChannels
• name

The following methods establish structure and conventions that other Enterprise Objects Framework classes depend on and should be overridden with caution:

• setExpressionClassName
• setConnectionDictionary
• setDelegate

If you override setConnectionDictionary or setDelegate, your implementations should incorporate the superclass's implementation by calling super.

The remaining EOAdaptor methods must be overridden by every concrete adaptor subclass in terms of the persistent storage system with which it interacts:

• assignExternalInfoForAttribute
• assignExternalInfoForEntity
• externalTypesWithModel
• internalTypeForExternalType
• assertConnectionDictionaryIsValid
• createAdaptorContext
• fetchedValueForDataValue
• fetchedValueForDateValue
• fetchedValueForNumberValue
• fetchedValueForStringValue
• fetchedValueForValue
• isValidQualifierType

See Also:

adaptorWithName(String name), adaptorWithModel(EOModel model), assignExternalInfoForEntireModel(EOModel model), connectionDictionary(), contexts(), delegate(), hasOpenChannels(), name(), setExpressionClassName( String sqlExpressionClassName, String adaptorClassName), setConnectionDictionary(NSDictionary dictionary), setDelegate(Object delegate), assignExternalInfoForAttribute(EOAttribute attribute), assignExternalInfoForEntity(EOEntity entity), externalTypesWithModel(EOModel model), internalTypeForExternalType(String extType, EOModel model), assertConnectionDictionaryIsValid(), createAdaptorContext(), fetchedValueForDataValue(NSData value, EOAttribute attribute), fetchedValueForDateValue( NSTimestamp value, EOAttribute attribute), fetchedValueForNumberValue(Number value, EOAttribute attribute), fetchedValueForStringValue(String value, EOAttribute attribute), fetchedValueForValue(Object value, EOAttribute attribute), isValidQualifierType(String typeName, EOModel model)

Inner Class Summary

static interface

EOAdaptor.Delegate This interface defines a delegate to EOAdaptor to handle specific requests that are normally handled by EOAdaptor (or rather its subclass since EOAdaptor is an abstract class).

Constructor Summary

EOAdaptor(String name)
Creates and returns a new EOAdaptor with the specified name.

Method Summary

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.
static EOAdaptor	adaptorWithName(String name) Creates and returns a new adaptor from the class with the specified name.
NSDictionary	administrativeConnectionDictionaryForAdaptor(EOAdaptor adaptor) This method, formerly provided by the EOLoginPanel class, returns null in the default implementation.
abstract void	assertConnectionDictionaryIsValid() An abstract method that should be implemented by subclasses to verify that the adaptor can connect to the database server with its connection dictionary.
void	assignExternalInfoForAttribute(EOAttribute attribute) The default implementation assigns the column name (external name) for attribute based on attribute's internal name.
void	assignExternalInfoForEntireModel(EOModel model) Assigns database-specific characteristics to model.
void	assignExternalInfoForEntity(EOEntity entity) The default implementation assigns an external name to entity based on entity's name attribute.
void	assignExternalTypeForAttribute(EOAttribute attribute) The default implementation does nothing.
boolean	canServiceModel(EOModel model) Returns true if the receiver can service model, false otherwise.
NSDictionary	connectionDictionary() Returns the receiver's connection dictionary, or null if the adaptor doesn't have one.
NSArray	contexts() Returns the adaptor contexts created by the receiver, or an empty array if no adaptor contexts have been created.
abstract EOAdaptorContext	createAdaptorContext() An abstract method that should be implemented by subclasses to create and return a new EOAdaptorContext, or null if a new context can't be created.
void	createDatabaseWithAdministrativeConnectionDictionary(NSDictionary administrativeConnectionDictionary) Uses the administrative login information to create the database defined by administrativeConnectionDictionary.
static Object	defaultDelegate() Returns the default delegate, which is the object that is assigned to new adaptor instances as the delegate, or null if no default delegate is set.
abstract Class	defaultExpressionClass() An abstract method that should be implemented by subclasses to return the subclass of EOSQLExpression used as the default expression class for the adaptor.
Object	delegate() Returns the receiver's delegate or null if a delegate has not been assigned.
void	dropDatabaseWithAdministrativeConnectionDictionary(NSDictionary administrativeConnectionDictionary) Uses the administrative login information to drop the database defined by the administrativeConnectionDictionary.
Class	expressionClass() Returns the subclass of EOSQLExpression used by the receiver for query language expressions, which is assigned using the class method setExpressionClassName.
static String	expressionClassName(String adaptorClassName) Returns the class name of the subclass of EOSQLExpression used for expression evaluation on a given adaptor class.
abstract EOSQLExpressionFactory	expressionFactory() An abstract method that supports changes made to EOSQLExpression and related classes and interfaces.
NSArray	externalTypesWithModel(EOModel model) The default implementation returns an empty array.
NSData	fetchedValueForDataValue(NSData value, EOAttribute att) The default implementation returns value unchanged.
NSTimestamp	fetchedValueForDateValue(NSTimestamp value, EOAttribute att) The default implementation returns value unchanged.
Number	fetchedValueForNumberValue(Number value, EOAttribute att) The default implementation returns value unchanged.
String	fetchedValueForStringValue(String value, EOAttribute att) The default implementation returns value unchanged.
Object	fetchedValueForValue(Object value, EOAttribute att) Returns the value that the receiver's database server would ultimately store for value if it were inserted or updated in the column described by att.
void	handleDroppedConnection() Invoked when necessary to clean up after a dropped connection.
boolean	hasOpenChannels() Returns true if any of the receiver's contexts have open channels, false otherwise.
String	internalTypeForExternalType(String extType, EOModel model) The default implementation returns null.
boolean	isDroppedConnectionException(Exception exception) The default implementation returns false.
abstract boolean	isValidQualifierType(String typeName, EOModel model) An abstract method that should be implemented by subclasses to return true if an attribute of type typeName can be used in a qualifier (an SQL WHERE clause) sent to the database server, false otherwise.
String	name() Returns the adaptor's name.
NSArray	prototypeAttributes() Returns an array of prototype attributes specific to the adaptor class, or an empty array if there are none.
void	setConnectionDictionary(NSDictionary dictionary) Sets the adaptor's connection dictionary to dictionary, which must only contain String, NSData, NSDictionary, and NSArray objects.
static void	setDefaultDelegate(Object delegate) Sets the default delegate, which is the object assigned as delegate to all newly created EOAdaptor instances.
void	setDelegate(Object delegate) Sets the receiver's delegate to delegate, or removes its delegate if delegate is null.
static void	setExpressionClassName(String sqlExpressionClassName, String adaptorClassName) Sets the expression class for instances of the class named adaptorClassName to sqlExpressionClassName.
abstract EOSchemaGeneration	synchronizationFactory() An abstract method that supports changes made to EOSQLExpression and related classes and interfaces.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EOAdaptor

public EOAdaptor(String name)

Creates and returns a new EOAdaptor with the specified name. When you create an adaptor subclass, override this method.

Never use this constructor directly. It is invoked automatically from adaptorWithName and adaptorWithModel, the EOAdaptor static methods used to create new adaptor instances.

Parameters:

name - The name of adaptor to create.

See Also:

adaptorWithName(String name), adaptorWithModel(EOModel model)

Method Detail

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 an empty string, or if the adaptor named in model can't be loaded.

Parameters:

model - The model from which to read the adaptor.

Returns:

The adaptor specified in model.

Throws:

IllegalArgumentException - if model is null, if model's adaptor name is null, or if the adaptor named in model can't be loaded

See Also:

adaptorWithName(String name), EOModel.adaptorName(), setConnectionDictionary(NSDictionary dictionary), EOModel

adaptorWithName

public static EOAdaptor adaptorWithName(String name)

Creates and returns a new adaptor from the class with the specified name. Usually you would use adaptorWithModel to create a new adaptor istance, but you can use this method when you don't have a model. In fact, this method is typically used when you are creating an adaptor for the purpose of creating a model from an existing database.

Parameters:

name - The adaptor name.

Returns:

The corresponding adaptor.

See Also:

adaptorWithModel(EOModel model)

administrativeConnectionDictionaryForAdaptor

public NSDictionary administrativeConnectionDictionaryForAdaptor(EOAdaptor adaptor)

This method, formerly provided by the EOLoginPanel class, returns null in the default implementation. Adaptor subclasses can override this method to return the administrative connection dictionary for the specified adaptor. Should return null if the user cancels the panel.

Parameters:

adaptor - The adaptor.

Returns:

null by default.

assertConnectionDictionaryIsValid

public abstract void assertConnectionDictionaryIsValid()

An abstract method that should be implemented by subclasses to verify that the adaptor can connect to the database server with its connection dictionary. Should briefly form a connection to the server to validate the connection dictionary and then close the connection. This method should throw a runtime exception if the connection dictionary contains invalid information, or if any error occurs.

An actual connection is made when the first adaptor channel is sent an openChannel message.

See Also:

setConnectionDictionary(NSDictionary dictionary), EOAdaptorChannel.openChannel()

assignExternalInfoForAttribute

public void assignExternalInfoForAttribute(EOAttribute attribute)

The default implementation assigns the column name (external name) for attribute based on attribute's internal name. For example, if the attribute is named "firstName", this method assigns the external name "FIRST_NAME". Makes no changes to attribute's column name if attribute is derived.

This method can be overridden by subclasses to assign other database-specific characteristics to attribute, such as external type. Subclasses of EOAdaptor don't need to implement this method. A subclass that does implement this method must incorporate the superclass's version.

Parameters:

attribute - The attribute.

See Also:

assignExternalTypeForAttribute(EOAttribute attribute), assignExternalInfoForEntireModel(EOModel model)

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. Recurses through entities and their attributes calling the conversion methods above.

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

Parameters:

model - The model.

See Also:

assignExternalInfoForEntity(EOEntity entity), assignExternalInfoForAttribute(EOAttribute attribute)

assignExternalInfoForEntity

public void assignExternalInfoForEntity(EOEntity entity)

The default implementation assigns an external name to entity based on entity's name attribute.

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

Parameters:

entity - An EOEntity.

See Also:

assignExternalInfoForEntireModel(EOModel model), EOEntity.name(), EOEntity.externalNameForInternalName(String internalName, String separatorString, boolean allCaps)

assignExternalTypeForAttribute

public void assignExternalTypeForAttribute(EOAttribute attribute)

The default implementation does nothing. This method can be overridden by subclasses to assign the external type to attribute. An adaptor subclass should implement this method to assign an external type using attribute's internal type, precision, and length information.

Parameters:

attribute - The attribute for which to set a corresponding external type.

See Also:

assignExternalInfoForEntireModel(EOModel model)

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.

Subclasses of EOAdaptor don't need to override this method.

Parameters:

model - A model.

Returns:

true if this adaptor instance can service database access requests for this model.

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. Connection dictionary keys are specific to each adaptor; refer to your adaptor's documentation for the keys it uses.

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

Returns:

The receiver's connection dictionary, or null.

contexts

public NSArray contexts()

Returns the adaptor contexts created by the receiver, or an empty array if no adaptor contexts have been created. Subclasses of EOAdaptor don't need to override this method.

Returns:

The adaptor contexts created by the receiver, or an empty array.

See Also:

createAdaptorContext()

createAdaptorContext

public abstract EOAdaptorContext createAdaptorContext()

An abstract method that should be 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.

Returns:

Should return a new EOAdaptorContext.

See Also:

contexts()

createDatabaseWithAdministrativeConnectionDictionary

public void createDatabaseWithAdministrativeConnectionDictionary(NSDictionary administrativeConnectionDictionary)

Uses the administrative login information to create the database defined by administrativeConnectionDictionary. Throws an exception if administrativeConnectionDictionary is null.

Parameters:

administrativeConnectionDictionary - The administrative connection dictionary.

Throws:

EOGeneralAdaptorException - if administrativeConnectionDictionary is null.

See Also:

dropDatabaseWithAdministrativeConnectionDictionary( NSDictionary administrativeConnectionDictionary)

defaultDelegate

public static Object defaultDelegate()

Returns the default delegate, which is the object that is assigned to new adaptor instances as the delegate, or null if no default delegate is set.

Returns:

The default delegate for new adaptor instances, or null.

defaultExpressionClass

public abstract Class defaultExpressionClass()

An abstract method that should be implemented by subclasses to return the subclass of EOSQLExpression used as the default expression class for the adaptor. You won't ordinarily invoke this method directly. It is invoked automatically to determine which class should be used to represent query language expressions.

Returns:

Should return the subclass of EOSQLExpression used as the default expression class for the adaptor.

See Also:

setExpressionClassName( String sqlExpressionClassName, String adaptorClassName)

delegate

public Object delegate()

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

Returns:

The receiver's delegate or null.

dropDatabaseWithAdministrativeConnectionDictionary

public void dropDatabaseWithAdministrativeConnectionDictionary(NSDictionary administrativeConnectionDictionary)

Uses the administrative login information to drop the database defined by the administrativeConnectionDictionary. Throws an exception if administrativeConnectionDictionary is null.

Parameters:

administrativeConnectionDictionary - The administrative connection dictionary.

Throws:

EOGeneralAdaptorException - if administrativeConnectionDictionary is null.

See Also:

createDatabaseWithAdministrativeConnectionDictionary( NSDictionary administrativeConnectionDictionary)

expressionClass

public Class expressionClass()

Returns the subclass of EOSQLExpression used by the receiver for query language expressions, which is 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. Throws an exception if the expression class is not loaded in memory.

You rarely need to invoke this method yourself. It is invoked by the Enterprise Objects Framework to determine the class to use to represent query language expressions. You should use this method if you explicitly create EOSQLExpression instances. To be sure that you are using the correct expression class, create instances of the class returned from this method.

Subclasses of EOAdaptor don't need to override this method. A subclass that does override this method must incorporate the superclass's version by calling super.

Returns:

The subclass of EOSQLExpression used by this adaptor.

Throws:

IllegalStateException - if the expression class is not in memory.

See Also:

setExpressionClassName(String sqlExpressionClassName, String adaptorClassName), defaultExpressionClass()

expressionClassName

public static String expressionClassName(String adaptorClassName)

Returns the class name of the subclass of EOSQLExpression used for expression evaluation on a given adaptor class.

Parameters:

adaptorClassName - The name of the adaptor class.

Returns:

The adaptor specified in model.

See Also:

setExpressionClassName(String sqlExpressionClassName, String adaptorClassName)

expressionFactory

public abstract EOSQLExpressionFactory expressionFactory()

An abstract method that supports changes made to EOSQLExpression and related classes and interfaces. Subclass implementations return the EOExpressionFactory for the adaptor.

Returns:

Should return the EOExpressionFactory.

See Also:

EOSQLExpression

externalTypesWithModel

public NSArray externalTypesWithModel(EOModel model)

The default implementation returns an empty array. This method can be overridden by subclasses to return the names of the database types 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. Refer to your adaptor's documentation to determine whether, and how, it uses the model for type mapping.

Parameters:

model - An optional argument that can be used to supplement the adaptor's set of database types with additional, user-defined database types.

Returns:

An empty array by default.

fetchedValueForDataValue

public NSData fetchedValueForDataValue(NSData value,
                                       EOAttribute att)

The default implementation returns value unchanged. This method can be overridden by subclasses to return the value that the receiver's database server would ultimately store for value if it were inserted or updated in the column described by att. An adaptor subclass should override this method if the adaptor's database performs transformations on binary types, such as BLOBs.

This method is invoked from fetchedValueForValue when the value argument is an NSData.

Parameters:

value - The original value.

att - The attribute corresponding to the database column in which value would be stored.

Returns:

value unchanged by default.

See Also:

fetchedValueForValue(Object value, EOAttribute att)

fetchedValueForDateValue

public NSTimestamp fetchedValueForDateValue(NSTimestamp value,
                                            EOAttribute att)

The default implementation returns value unchanged. This method can be overridden by subclasses to return the value that the receiver's database server would ultimately store for value if it were inserted or updated in the column described by att. 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.

This method is invoked from fetchedValueForValue when the value argument is a date.

Parameters:

value - The original value.

att - The attribute corresponding to the database column in which value would be stored.

Returns:

value unchanged by default.

See Also:

fetchedValueForValue(Object value, EOAttribute att)

fetchedValueForNumberValue

public Number fetchedValueForNumberValue(Number value,
                                         EOAttribute att)

The default implementation returns value unchanged. This method can be overridden by subclasses to return the value that the receiver's database server would ultimately store for value if it were inserted or updated in the column described by att. 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 rules of the database.

This method is invoked from fetchedValueForValue when the value argument is a number.

Parameters:

value - The original value.

att - The attribute corresponding to the database column in which value would be stored.

Returns:

value unchanged by default.

See Also:

fetchedValueForValue(Object value, EOAttribute att)

fetchedValueForStringValue

public String fetchedValueForStringValue(String value,
                                         EOAttribute att)

The default implementation returns value unchanged. This method can be overridden by subclasses to return the value that the receiver's database server would ultimately store for value if it were inserted or updated in the column described by att. An adaptor subclass should override this method to perform any additional conversion or formatting that is needed on string values.

This method is invoked from fetchedValueForValue when the value argument is a string.

Parameters:

value - The original value.

att - The attribute corresponding to the database column in which value would be stored.

Returns:

value unchanged by default.

See Also:

fetchedValueForValue(Object value, EOAttribute att)

fetchedValueForValue

public Object fetchedValueForValue(Object value,
                                   EOAttribute att)

Returns the value that the receiver's database server would ultimately store for value if it were inserted or updated in the column described by att. Returns value unchanged if value is not a string, number, date, or data object (that is, an instance of String, Number, NSTimestamp, NSData, or one of their subclasses). The Framework uses this method to keep Enterprise Object snapshots synchronized with database values.

For example, assume that a product's price is marked down 15%. If the product's original price was 5.25, the sale price is 5.25*.85, or 4.4625. When the Enterprise Objects Framework updates the product's price, the database server truncates the price to 4.46 (assuming the scale of the price column in the database is 2). Before performing the update, the Framework calls fetchedValueForValue 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 invokes one of the data type-specific methods depending on value's class.

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

Parameters:

value - The original value.

att - The attribute corresponding to the database column in which value would be stored.

Returns:

value, or the new value.

See Also:

fetchedValueForDataValue(NSData value, EOAttribute att), fetchedValueForDateValue( NSTimestamp value, EOAttribute att), fetchedValueForNumberValue(Number value, EOAttribute att), fetchedValueForStringValue(String value, EOAttribute att), EOAttribute.valueFactoryMethod(), EOAdaptor

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.

Never invoke this method yourself. It is invoked automatically by the Framework. Subclasses don't normally need to override the superclass implementation.

See Also:

EOAdaptor.Delegate.reconnectionDictionaryForAdaptor(EOAdaptor adaptor), EOAdaptorContext.handleDroppedConnection()

hasOpenChannels

public boolean hasOpenChannels()

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

Returns:

true if the adaptor has any open channels.

See Also:

EOAdaptorContext.hasOpenChannels()

internalTypeForExternalType

public String internalTypeForExternalType(String extType,
                                          EOModel model)

The default implementation returns null. This method can be overridden by subclasses to return the name of the class used to represent values stored in the database as extType. Should return null if no mapping for extType is found.

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. Refer to your adaptor's documentation to determine whether, and how, it uses the model for type mapping.

Parameters:

extType - The name of the external type.

model - An optional argument that can be used to supplement the adaptor's set of type mappings with additional mappings for user-defined database types.

Returns:

null by default.

isDroppedConnectionException

public boolean isDroppedConnectionException(Exception exception)

The default implementation returns false. Subclasses that support database reconnection should implement this method to allow for automatic database reconnection. This method should return 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 thrown during fetching or saving. If the adaptor returns true, it then attempts to reconnect to the database and retries the operation. If the reconnection attempt fails, the exception from the failure is thrown as usual. If the adaptor returns false, reconnection isn't attempted and the exception is thrown.

Parameters:

exception - An exception object.

Returns:

false by default.

See Also:

handleDroppedConnection(), EOAdaptor.Delegate.reconnectionDictionaryForAdaptor( EOAdaptor adaptor)

isValidQualifierType

public abstract boolean isValidQualifierType(String typeName,
                                             EOModel model)

An abstract method that should be implemented by subclasses to return true if an attribute of type typeName can be used in a qualifier (an SQL WHERE clause) sent to the database server, false otherwise. typeName is the name of a type as required by the database server. 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.

Parameters:

typeName - The name of a type as determined by the database server.

model - A model.

Returns:

Should return true if an attribute of type typeName can be used in a qualifier.

name

public String name()

Returns the adaptor's name. Subclasses of EOAdaptor don't need to override this method.

Returns:

The name of the receiver.

See Also:

adaptorWithName(String name)

prototypeAttributes

public NSArray prototypeAttributes()

Returns an array of prototype attributes specific to the adaptor class, or an empty array if there are none. Adaptor writers should note that this method looks for an EOModel named EOadaptorNamePrototypes in the Resources directory of the adaptor.

Returns:

An array of prototype attributes specific to the adaptor class, or an empty array.

setConnectionDictionary

public void setConnectionDictionary(NSDictionary dictionary)

Sets the adaptor's connection dictionary to dictionary, which must only contain String, NSData, NSDictionary, and NSArray objects. Connection information can not be changed while the adaptor is connected. Throws an exception if there are any open channels when this method is invoked.

Subclasses of EOAdaptor don't need to override this method. A subclass that does override this method must incorporate the superclass's version by calling super.

Parameters:

dictionary - The adaptor's connection dictionary.

Throws:

IllegalArgumentException - if there are any open channels when this method is called.

See Also:

connectionDictionary(), hasOpenChannels(), assertConnectionDictionaryIsValid()

setDefaultDelegate

public static void setDefaultDelegate(Object delegate)

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

Parameters:

delegate - The object assigned as delegate to all newly created EOAdaptor instances.

setDelegate

public void setDelegate(Object delegate)

Sets the receiver's delegate to delegate, or removes its delegate if delegate is null. Subclasses of EOAdaptor don't need to override this method. A subclass that does override this method must incorporate the superclass's version by calling super.

Parameters:

delegate - The receiver's 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 an empty string. Use this method to substitute a subclass of EOSQLExpression for the expression class provided by the adaptor.

Parameters:

sqlExpressionClassName - The name of a subclass of EOSQLExpression.

adaptorClassName - The class name of affected adaptor.

Throws:

IllegalArgumentException - if adaptorClassName is null or an empty string.

See Also:

expressionClassName(String className), defaultExpressionClass(), EOSQLExpression

synchronizationFactory

public abstract EOSchemaGeneration synchronizationFactory()

An abstract method that supports changes made to EOSQLExpression and related classes and interfaces. Subclass implementations return the EOSynchronizationFactory for the adaptor.

Returns:

Should return the EOSynchronizationFactory for the adaptor.

See Also:

EOSQLExpression