EOAdaptor
Inherits from: NSObject
Conforms to: NSObject
(NSObject)
Declared in: EOAccess/EOAdaptor.h
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 class 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:
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
EOAccess defines one constant in EOAdaptor.h, an NSString, as described below:
Constant | Description |
EOGeneralAdaptorException | The name of exceptions raised by adaptors when errors occur during interactions with their database servers. |
Method Types
- Creating an EOAdaptor
- + adaptorWithName:
- + adaptorWithModel:
- - initWithName:
- 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:attribute:
- - fetchedValueForDataValue:attribute:
- - fetchedValueForDateValue:attribute:
- - fetchedValueForNumberValue:attribute:
- - fetchedValueForStringValue:attribute:
- Servicing models
- - canServiceModel:
- + internalTypeForExternalType:model:
- + externalTypesWithModel:
- + assignExternalInfoForEntireModel:
- + assignExternalInfoForEntity:
- + assignExternalInfoForAttribute:
- - isValidQualifierType:model:
- Creating adaptor contexts
- - createAdaptorContext
- - contexts
- Checking connection status
- - hasOpenChannels
- Accessing a default expression class
- + setExpressionClassName:adaptorClassName:
- - 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
- - objectStoreChangesFromAttribute:toAttribute:
Class Methods
adaptorWithModel:
+(id)adaptorWithModel:(EOModel
*)model
NSInvalidArgumentException
if model is nil, if model's
adaptor name is nil, or if the adaptor named in model can't
be loaded.A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version.
See Also: - adaptorName ( EOModel), - setConnectionDictionary:
adaptorWithName:
+ (id)adaptorWithName:(NSString
*)name
EOAdaptor *myAdaptor = [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. However,
note that dynamic loading isn't available on PDO platforms. Consequently,
you must statically link your adaptor into applications for PDO:
In this case, adaptorWithName: simply
looks in the runtime for an adaptor class corresponding with the
specified name. Raises an NSInvalidArgumentException
if name is nil 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:
+ (void)assignExternalInfoForAttribute:(EOAttribute
*)attribute
Overridden 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 override this method. A subclass that does override this method must incorporate the superclass's version.
See Also: + assignExternalInfoForEntireModel:
assignExternalInfoForEntireModel:
+ (void)assignExternalInfoForEntireModel:(EOModel
*)model
A subclass of EOAdaptor doesn't need to override this method.
assignExternalInfoForEntity:
+ (void)assignExternalInfoForEntity:(EOEntity
*)entity
An adaptor subclass should override this method to assign additional database-specific characteristics, if any. A subclass that does override this method must incorporate the superclass's version.
See Also: + assignExternalInfoForEntireModel:
assignExternalTypeForAttribute:
+ (void)assignExternalTypeForAttribute:(EOAttribute
*)attribute
An adaptor subclass should override this method to assign an external type using attribute's internal type, precision, and length information. A subclass that does override this method should incorporate the superclass's version.
See Also: + assignExternalInfoForEntireModel:
availableAdaptorNames
+ (NSArray *)availableAdaptorNames
defaultDelegate
+ (id)defaultDelegate
externalTypesWithModel:
+ (NSArray *)externalTypesWithModel:(EOModel
*)model
An adaptor subclass should implement this method.
internalTypeForExternalType:model:
+ (NSString *)internalTypeForExternalType:(NSString
*)extType
model:(EOModel *)model
An adaptor subclass should override this method without invoking EOAdaptor's implementation.
setDefaultDelegate:
+ (void)setDefaultDelegate:(id)defaultDelegate
setExpressionClassName:adaptorClassName:
+ (void)setExpressionClassName:(NSString
*)sqlExpressionClassName
adaptorClassName:(NSString *)adaptorClassName
NSInvalidArgumentException
if adaptorClassName is nil or
the empty string.Use this method to substitute a subclass of EOSQLExpression for the expression class provided by the adaptor. For example, the default expression class for the Oracle adaptor is OracleSQLExpression. The following statement substitutes the class named MySQLExpression:
[EOAdaptor setExpressionClassName:@"MySQLExpression" adaptorClassName:@"OracleAdaptor"];
A subclass of EOAdaptor doesn't need to override this method. A subclass that does override this method must incorporate the superclass's version.
See Also: - defaultExpressionClass
sharedLoginPanelInstance
+ (EOLoginPanel *)sharedLoginPanelInstance
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
- (void)assertConnectionDictionaryIsValid
An adaptor subclass must override this method without invoking EOAdaptor's implementation.
See Also: - setConnectionDictionary:, - runLoginPanel, - runLoginPanelAndValidateConnectionDictionary
canServiceModel:
- (BOOL)canServiceModel:(EOModel
*)model
A subclass of EOAdaptor doesn't need to override this method.
connectionDictionary
- (NSDictionary *)connectionDictionary
A subclass of EOAdaptor doesn't need to override this method.
contexts
- (NSArray *)contexts
See Also: - createAdaptorContext
createAdaptorContext
- (EOAdaptorContext *)createAdaptorContext
An adaptor subclass must override this method without invoking EOAdaptor's implementation.
See Also: - contexts, - initWithAdaptor: ( EOAdaptorContext)
createDatabaseWithAdministrativeConnectionDictionary:
- (void)createDatabaseWithAdministrativeConnectionDictionary:(NSDictionary
*)connectionDictionary
See Also: - dropDatabaseWithAdministrativeConnectionDictionary:, EOLoginPanel
databaseEncoding
- (NSStringEncoding)databaseEncoding
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 raises an NSInvalidArgumentException
if
the receiver's database encoding isn't valid.
A subclass of EOAdaptor doesn't need to override this method.
See Also: - availableStringEncodings (NSString), - defaultCStringEncoding (NSString)
defaultExpressionClass
- (Class)defaultExpressionClass
An adaptor subclass must override this method without invoking EOAdaptor's implementation.
See Also: + setExpressionClassName:adaptorClassName:
delegate
- (id)delegate
dropDatabaseWithAdministrativeConnectionDictionary:
- (void)dropDatabaseWithAdministrativeConnectionDictionary:(NSDictionary
*)connectionDictionary
See Also: - createDatabaseWithAdministrativeConnectionDictionary:, EOLoginPanel class
expressionClass
- (Class)expressionClass
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:attribute:
- (NSData *)fetchedValueForDataValue:(NSData
*)value
attribute:(EOAttribute *)attribute
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:attribute:
- (NSCalendarDate *)fetchedValueForDateValue:(NSCalendarDate
*)value
attribute:(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:attribute:
- (NSNumber *)fetchedValueForNumberValue:(NSNumber
*)value
attribute:(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:attribute:
- (NSString*)fetchedValueForStringValue:(NSString
*)value
attribute:(EOAttribute *)attribute
EOAdaptor's implementation trims trailing spaces and returns nil for zero-length strings. An adaptor subclass should override this method to perform any additional conversion or formatting on string values.
fetchedValueForValue:attribute:
- (id)fetchedValueForValue:(id)value
attribute:(EOAttribute *)attribute
An adaptor subclass can override this method or one of the data type-specific fetchedValue... methods. EOAdaptor's implementation of fetchedValueForValue:attribute: 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 NSString, NSNumber, NSDate, NSData, or any of their subclasses), fetchedValueForValue:attribute: returns value unchanged.
This method invokes the EOAdaptor Delegatedelegate method adaptor:fetchedValueForValue:attribute: which can override the adaptor's default behavior.
See Also: - fetchedValueForDataValue:attribute:, - fetchedValueForDateValue:attribute:, - fetchedValueForNumberValue:attribute:, - fetchedValueForStringValue:attribute:, - valueFactoryMethod (EOAttribute)
handleDroppedConnection
- (void)handleDroppedConnection
You should never invoke this method; it is invoked automatically by the Framework. Subclasses don't normally need to override the superclass implementation.
hasOpenChannels
- (BOOL)hasOpenChannels
See Also: - hasOpenChannels ( EOAdaptorContext)
initWithName:
- (id)initWithName:(NSString
*)name
Never invoke this method directly. It is invoked automatically from adaptorWithName: and adaptorWithModel:-EOAdaptor class methods you use to create a new adaptor.
A subclass of EOAdaptor doesn't need to override this method, but may override it to perform additional initialization. A subclass that does override this method must incorporate the superclass's version through a message to super.
isDroppedConnectionException:
- (BOOL)isDroppedConnectionException:(NSException
*)exception
YES
if
the exception is one that the adaptor can attempt to recover from
by reconnecting to the database, NO
otherwise.Invoked
if an exception is raised during fetching or saving. If the adaptor
returns YES
, 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 NO
,
reconnection isn't attempted and the exception is raised.
The
default implementation of isDroppedConnectionException: returns NO
.
Subclasses that support database reconnection should implement this
method to allow for automatic database reconnection.
See Also: - handleDroppedConnection, - reconnectionDictionaryForAdaptor: ( EOAdaptor Delegate)
isValidQualifierType:model:
- (BOOL)isValidQualifierType:(NSString
*)typeName
model:(EOModel *)model
An adaptor subclass must override this method without invoking EOAdaptor's implementation.
name
- (NSString *)name
A subclass of EOAdaptor doesn't need to override this method.
See Also: + adaptorWithName:, - initWithName:
objectStoreChangesFromAttribute:toAttribute:
- (NSDictionary *)objectStoreChangesFromAttribute:(EOAttribute
*)schemaAttribute
toAttribute:(EOAttribute *)modelAttribute
prototypeAttributes
- (NSArray *)prototypeAttributes
runLoginPanel
- (NSDictionary *)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.
See Also: - setConnectionDictionary:, - assertConnectionDictionaryIsValid, + sharedLoginPanelInstance
runLoginPanelAndValidateConnectionDictionary
- (BOOL)runLoginPanelAndValidateConnectionDictionary
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.
See Also: - runLoginPanel, - setConnectionDictionary:, - assertConnectionDictionaryIsValid, + sharedLoginPanelInstance
setConnectionDictionary:
- (void)setConnectionDictionary:(NSDictionary
*)dictionary
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.
See Also: - connectionDictionary, - hasOpenChannels, - assertConnectionDictionaryIsValid, - runLoginPanelAndValidateConnectionDictionary, - runPanelForAdaptor:validate:allowsCreation: (EOLoginPanel)
setDelegate:
- (void)setDelegate:(id)delegate