Documentation Archive Developer
Search
PATH  Documentation > WebObjects 4.5 > EOAccess Reference

Table of Contents

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:

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

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. Raises an 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

Creates and returns a new adaptor, loading it from the framework named name if necessary and sending it an initWithName: message. For example, this code excerpt creates an adaptor from a framework named AcmeEOAdaptor.framework:
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

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 override this method.



assignExternalInfoForEntity:

+ (void)assignExternalInfoForEntity:(EOEntity *)entity

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

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

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

Returns an array containing the names of all available adaptors, as found by searching the paths returned by NSStandardLibraryPaths(). If no adaptors are found, this method returns an empty array.

defaultDelegate

+ (id)defaultDelegate

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

externalTypesWithModel:

+ (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:model:

+ (NSString *)internalTypeForExternalType:(NSString *)extType model:(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 nil if no mapping for extType is found.

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



setDefaultDelegate:

+ (void)setDefaultDelegate:(id)defaultDelegate

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

setExpressionClassName:adaptorClassName:

+ (void)setExpressionClassName:(NSString *)sqlExpressionClassName adaptorClassName:(NSString *)adaptorClassName

Sets the expression class for instances of the class named adaptorClassName to sqlExpressionClassName. If sqlExpressionClassName is nil, restores the expression class to the default. Raises an 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

Returns the receiver's login panel in applications that have a graphical user interface. Returns nil 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

- (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. Raises an EOGeneralAdaptorException if the connection dictionary contains invalid information.

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

See Also: - setConnectionDictionary:, - runLoginPanel, - runLoginPanelAndValidateConnectionDictionary



canServiceModel:

- (BOOL)canServiceModel:(EOModel *)model

Returns YES if the receiver can service model, NO otherwise. EOAdaptor's implementation returns YES 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

- (NSDictionary *)connectionDictionary

Returns the receiver's connection dictionary, or nil 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

- (NSArray *)contexts

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

See Also: - createAdaptorContext



createAdaptorContext

- (EOAdaptorContext *)createAdaptorContext

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

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

See Also: - contexts, - initWithAdaptor: ( EOAdaptorContext)



createDatabaseWithAdministrativeConnectionDictionary:

- (void)createDatabaseWithAdministrativeConnectionDictionary:(NSDictionary *)connectionDictionary

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

See Also: - dropDatabaseWithAdministrativeConnectionDictionary:, EOLoginPanel



databaseEncoding

- (NSStringEncoding)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 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

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:adaptorClassName:



delegate

- (id)delegate

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

dropDatabaseWithAdministrativeConnectionDictionary:

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

- (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:adaptorClassName:. If no class has been set for the receiver's class, this method determines the expression class by sending defaultExpressionClass to self.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:attribute:

- (NSData *)fetchedValueForDataValue:(NSData *)value attribute:(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:attribute: 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:attribute:

- (NSCalendarDate *)fetchedValueForDateValue:(NSCalendarDate *)value attribute:(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:attribute: when the value argument is a date.

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

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:attribute: when the value argument is a number.

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

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:attribute: when the value argument is a string.

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

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:attribute: 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: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

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

- (BOOL)hasOpenChannels

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

See Also: - hasOpenChannels ( EOAdaptorContext)



initWithName:

- (id)initWithName:(NSString *)name

The designated initializer for the EOAdaptor class, this method is overridden by adaptor subclasses to initialize a newly allocated EOAdaptor subclass 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, an adaptor named "Acme" is loaded from the framework AcmeEOAdaptor.framework. Returns self.

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

Returns 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

Implemented by subclasses to return YES if an attribute of type typeName can be used in a qualifier (a SQL WHERE clause) sent to the database server, or NO 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

- (NSString *)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:, - initWithName:



objectStoreChangesFromAttribute:toAttribute:

- (NSDictionary *)objectStoreChangesFromAttribute:(EOAttribute *)schemaAttribute toAttribute:(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

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

- (NSDictionary *)runLoginPanel

Runs the adaptor's login panel by sending a runLoginPanelAndValidateConnectionDictionarymessage to the adaptor's login panel object with the validate flag NO. 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.

See Also: - setConnectionDictionary:, - assertConnectionDictionaryIsValid, + sharedLoginPanelInstance



runLoginPanelAndValidateConnectionDictionary

- (BOOL)runLoginPanelAndValidateConnectionDictionary

Runs the adaptor's login panel by sending a runPanelForAdaptor:validate:allowsCreation:message to the adaptor's login panel object with the validate flag YES. Returns YES if the user enters valid connection information, or NO 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.

See Also: - runLoginPanel, - setConnectionDictionary:, - assertConnectionDictionaryIsValid, + sharedLoginPanelInstance



setConnectionDictionary:

- (void)setConnectionDictionary:(NSDictionary *)dictionary

Sets the adaptor's connection dictionary to dictionary, which must only contain NSString, NSData, NSDictionary, and NSArray objects. Raises an NSInvalidArgumentException 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.

See Also: - connectionDictionary, - hasOpenChannels, - assertConnectionDictionaryIsValid, - runLoginPanelAndValidateConnectionDictionary, - runPanelForAdaptor:validate:allowsCreation: (EOLoginPanel)



setDelegate:

- (void)setDelegate:(id)delegate

Sets the receiver's delegate to delegate, or removes its delegate if delegate is nil. The receiver does not retain delegate. 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.


Table of Contents