PATH  WebObjects 4.0 Documentation > EOAccess Reference



EOAdaptor

Inherits From:
NSObject

Inherits From:
com.apple.yellow.eoaccess


Class Description

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

The EOAdaptor class has the following principal attributes:

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:

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

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


Method Types

Creating an EOAdaptor
adaptorWithName
adaptorWithModel
Accessing an adaptor's name
name
Accessing the names of all available adaptors
availableAdaptorNames
Accessing connection information
assertConnectionDictionaryIsValid
connectionDictionary
setConnectionDictionary
runLoginPanelAndValidateConnectionDictionary
runLoginPanel
databaseEncoding
Performing database-specific transformations on values
fetchedValueForValue
fetchedValueForDataValue
fetchedValueForDateValue
fetchedValueForNumberValue
fetchedValueForStringValue
Servicing models
canServiceModel
internalTypeForExternalTypeInModel
externalTypesWithModel
assignExternalInfoForEntireModel
assignExternalInfoForEntity
assignExternalInfoForAttribute
isValidQualifierTypeInModel
Creating adaptor contexts
createAdaptorContext
contexts
Checking connection status
hasOpenChannels
Accessing a default expression class
setExpressionClassNameForAdaptorClassName
expressionClass
defaultExpressionClass
Accessing an adaptor's login panel
sharedLoginPanelInstance
runLoginPanelAndValidateConnectionDictionary
runLoginPanel
Accessing the delegate
delegate
setDelegate
Other
createDatabaseWithAdministrativeConnectionDictionary
dropDatabaseWithAdministrativeConnectionDictionary
prototypeAttributes

Constructors

public EOAdaptor()

public EOAdaptor(java.lang.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.


Class Methods


adaptorWithModel

public static java.lang.Object adaptorWithModel(EOModel model)

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

See also: - adaptorName (EOModel), setConnectionDictionary


adaptorWithName

public static java.lang.Object adaptorWithName(java.lang.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.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. Throws an exception if name is null or if an adaptor class corresponding with name can't be found.

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


assignExternalInfoForAttribute

public static void assignExternalInfoForAttribute(EOAttribute attribute)

Overridden by adaptor subclasses to assign database-specific characteristics to attribute. EOAdaptor's implementation assigns an external type and then 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.

See also: assignExternalInfoForEntireModel


assignExternalInfoForEntireModel

public static void assignExternalInfoForEntireModel(EOModel model)

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


assignExternalInfoForEntity

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

See also: assignExternalInfoForEntireModel


assignExternalTypeForAttribute

public static void assignExternalTypeForAttribute(EOAttribute attribute)

Overridden by adaptor subclasses to assign the external type to attribute. EOAdaptor's implementation does nothing. A subclass of EOAdaptor should override this method to assign an external type using attribute's internal type, precision, and length information.

See also: assignExternalInfoForEntireModel


availableAdaptorNames

public static NSArray availableAdaptorNames()

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

See also: assignExternalInfoForEntireModel


externalTypesWithModel

public static NSArray externalTypesWithModel(EOModel model)

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

An adaptor subclass should implement this method.


internalTypeForExternalTypeInModel

public static java.lang.String internalTypeForExternalTypeInModel(java.lang.String extType, EOModel model)

Implemented by subclasses to return the name of the Java 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.


setExpressionClassNameForAdaptorClassName

public static void setExpressionClassNameForAdaptorClassName(java.lang.String sqlExpressionClassName, java.lang.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.


Instance Methods


assertConnectionDictionaryIsValid

public void assertConnectionDictionaryIsValid()

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

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

See also: setConnectionDictionary


canServiceModel

public boolean canServiceModel(EOModel model)

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

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


connectionDictionary

public NSDictionary connectionDictionary()

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

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

See also: setConnectionDictionary


contexts

public NSArray contexts()

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

See also: createAdaptorContext


createAdaptorContext

public EOAdaptorContext createAdaptorContext()

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

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

See also: contexts


createDatabaseWithAdministrativeConnectionDictionary

public void createDatabaseWithAdministrativeConnectionDictionary(
NSDictionary connectionDictionary)

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

See also: dropDatabaseWithAdministrativeConnectionDictionary, EOLoginPanel class


databaseEncoding

public int databaseEncoding()

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

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

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

See also: - availableStringEncodings (NSString), - defaultCStringEncoding (NSString)


defaultExpressionClass

public java.lang.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: setExpressionClassNameForAdaptorClassName


delegate

public java.lang.Object delegate()

See also: 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.setDelegate


dropDatabaseWithAdministrativeConnectionDictionary

public void dropDatabaseWithAdministrativeConnectionDictionary(
NSDictionary connectionDictionary)

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

See also: createDatabaseWithAdministrativeConnectionDictionary, EOLoginPanel class


expressionClass

public java.lang.Class expressionClass()

Returns the subclass of EOSQLExpression used by the receiver for query language expressions. Returns the expression class assigned using the class method setExpressionClassNameForAdaptorClassName. If no class has been set for the receiver's class, this method determines the expression class by sending defaultExpressionClass to this.

You wouldn't ordinarily invoke this method directly. It's invoked automatically to determine which class should be used to represent query language expressions.

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


fetchedValueForDataValue

public NSData fetchedValueForDataValue(
NSData value,
EOAttribute attribute)

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

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


fetchedValueForDateValue

public NSGregorianDate fetchedValueForDateValue(
NSGregorianDate value,
EOAttribute attribute)

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

public java.lang.Number fetchedValueForNumberValue(java.lang.Number 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 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

public java.lang.String fetchedValueForStringValue(java.lang.String 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 a string.

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


fetchedValueForValue

public java.lang.Object fetchedValueForValue(java.lang.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 java.lang.String, java.lang.Number, NSGregorianDate, NSData, or any of their subclasses), fetchedValueForValue returns value unchanged.

This method invokes the EOAdaptorDelegates method adaptor:fetchedValueForAttributeValue:attribute: which can override the adaptor's default behavior.

See also: fetchedValueForDataValue, fetchedValueForDateValue, fetchedValueForNumberValue, fetchedValueForStringValue, - valueFactoryMethod (EOAttribute)


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)


isValidQualifierTypeInModel

public boolean isValidQualifierTypeInModel(java.lang.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 java.lang.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 implementers should note that this method looks for an EOModel named EOadaptorNamePrototypes in the resources directory of the adaptor.


runLoginPanel

public NSDictionary runLoginPanel()

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

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

See also: runLoginPanelAndValidateConnectionDictionary, setConnectionDictionary, assertConnectionDictionaryIsValid, sharedLoginPanelInstance


runLoginPanelAndValidateConnectionDictionary

public boolean runLoginPanelAndValidateConnectionDictionary()

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

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

See also: runLoginPanel, setConnectionDictionary, assertConnectionDictionaryIsValid, sharedLoginPanelInstance


setConnectionDictionary

public void setConnectionDictionary(NSDictionary dictionary)

Sets the adaptor's connection dictionary to dictionary, which must only contain java.lang.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.

See also: connectionDictionary, hasOpenChannels, assertConnectionDictionaryIsValid


setDelegate

public void setDelegate(java.lang.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.

See also: delegate


sharedLoginPanelInstance

public static EOLoginPanel sharedLoginPanelInstance()

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

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





Copyright © 1998, Apple Computer, Inc. All rights reserved.