WebObjects 5.4.2

com.webobjects.jdbcadaptor
Class JDBCAdaptor

java.lang.Object
  extended by com.webobjects.eoaccess.EOAdaptor
      extended by com.webobjects.jdbcadaptor.JDBCAdaptor

public class JDBCAdaptor
extends EOAdaptor

JDBCAdaptor is a concrete subclass of EOAdaptor that use JDBC for connecting to a database. It can be customized for a particular database and JDBC driver by using a JDBCPlugIn. Application code rarely needs to interact directly with an adaptor and should not normally use adaptor-specific API. All the useful API resides in EOAdaptor and the other generic EOAccess framework classes.

See Also:
EOAdaptor, JDBCPlugIn

Nested Class Summary
 
Nested classes/interfaces inherited from class com.webobjects.eoaccess.EOAdaptor
EOAdaptor.Delegate
 
Field Summary
static String DataSourceJndiNameKey
          Key for JNDI datasource name
static String DriverKey
          Key labeling the JDBC driver class name in the connection dictionary.
static String JDBCInfoKey
          Connection dictionary key labeling database-specific information contained in an NSDictionary, commonly referred to as "JDBC info".
static String PasswordKey
          Key labeling the password in the connection dictionary.
static String PlugInKey
          Key labeling the plugin class name in the connection dictionary.
static String TypeInfoKey
          Key labeling the NSDictionary of external type information in the JDBC info dictionary.
static String URLKey
          Key labeling the JDBC URL String in the connection dictionary.
static String UsernameKey
          Key labeling the user name in the connection dictionary.
 
Constructor Summary
JDBCAdaptor(String name)
          Create a JDBCAdaptor.
 
Method Summary
 void assertConnectionDictionaryIsValid()
          Checks that the connectionary dictionary is valid by attempting to make a connection.
 void assignExternalTypeForAttribute(EOAttribute attribute)
          Assigns an appropriate external type to the attribute.
 boolean canServiceModel(EOModel model)
          Returns true if the adaptor is compatible with the model; false otherwise.
protected  String connectionDictionaryURL()
          Returns the JDBC URL from the adaptor's connection dictionary.
 Properties connectionProperties()
          Returns a Properties object specifying connection information.
 String connectionURL()
          Returns the JDBC URL that should be used for connecting to the database as specified by the plugin.
 EOAdaptorContext createAdaptorContext()
          Returns a new JDBCContext for this adaptor.
 EOAttribute createAttribute(String name, String columnName, int columnType, String externalType, int precision, int scale, int isNullable)
          Returns a new EOAttribute based on the arguments.
 Class defaultExpressionClass()
          Returns the expression class to use for this adaptor.
 String driverName()
          Returns the JDBC driver's name.
 EOSQLExpressionFactory expressionFactory()
          Returns the expression factory to use for this adaptor.
 String externalTypeForJDBCType(int type)
          Returns the name of an external type that matches the given JDBC type type.
 NSArray externalTypesWithModel(EOModel model)
          Returns an NSArray of external type names for the model.
 Object fetchedValueForValue(Object value, EOAttribute attribute)
          Calls super with the result of the plugIn's plugInValueForValue.
protected static NSDictionary getJDBCInfoWithConnectionDictionary(NSDictionary connectionDictionary)
           
 void handleDroppedConnection()
          Handles cleaning up when a connection is dropped.
 boolean isDroppedConnectionException(Exception exception)
          Returns true if exception is a JDBCAdaptorException and it is considered a "dropped" connection; otherwise false.
 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.
protected  NSDictionary jdbcInfo()
          Returns an NSDictionary of database-specific information.
 String password()
          Returns the password from the adaptor's connection dictionary.
 JDBCPlugIn plugIn()
          Returns the JDBCPlugIn to use with this adaptor's connection dictionary.
 String plugInName()
          Returns the adaptor's plug-in name.
 EOSchemaSynchronizationFactory schemaSynchronizationFactory()
          An abstract method that supports changes made to EOSQLExpression and related classes and interfaces.
 void setConnectionDictionary(NSDictionary dictionary)
          Sets the adaptor's connection dictionary to dictionary, which must only contain String, NSData, NSDictionary, and NSArray objects.
static String stringRepresentationForJDBCType(int columnType)
           
 EOSchemaGeneration synchronizationFactory()
          Deprecated. 
protected  NSDictionary typeInfo()
          Returns an NSDictionary of external type information.
protected static NSDictionary typeInfoForModel(EOModel model)
           
 String username()
          Returns the user name from the adaptor's connection dictionary.
protected  int varcharMaxLength()
           
 
Methods inherited from class com.webobjects.eoaccess.EOAdaptor
adaptorWithModel, adaptorWithName, administrativeConnectionDictionaryForAdaptor, assignExternalInfoForAttribute, assignExternalInfoForEntireModel, assignExternalInfoForEntity, connectionDictionary, contexts, createDatabaseWithAdministrativeConnectionDictionary, defaultDelegate, delegate, dropDatabaseWithAdministrativeConnectionDictionary, expressionClass, expressionClassName, fetchedValueForDataValue, fetchedValueForDateValue, fetchedValueForNumberValue, fetchedValueForStringValue, hasOpenChannels, hasPlugIns, internalTypeForExternalType, name, prototypeAttributes, setDefaultDelegate, setDelegate, setExpressionClassName
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JDBCInfoKey

public static final String JDBCInfoKey
Connection dictionary key labeling database-specific information contained in an NSDictionary, commonly referred to as "JDBC info".

See Also:
JDBCAdaptor.jdbcInfo(), Constant Field Values

DataSourceJndiNameKey

public static final String DataSourceJndiNameKey
Key for JNDI datasource name

See Also:
Constant Field Values

TypeInfoKey

public static final String TypeInfoKey
Key labeling the NSDictionary of external type information in the JDBC info dictionary.

See Also:
Constant Field Values

UsernameKey

public static final String UsernameKey
Key labeling the user name in the connection dictionary.

See Also:
Constant Field Values

PasswordKey

public static final String PasswordKey
Key labeling the password in the connection dictionary.

See Also:
Constant Field Values

DriverKey

public static final String DriverKey
Key labeling the JDBC driver class name in the connection dictionary.

See Also:
Constant Field Values

PlugInKey

public static final String PlugInKey
Key labeling the plugin class name in the connection dictionary.

See Also:
Constant Field Values

URLKey

public static final String URLKey
Key labeling the JDBC URL String in the connection dictionary.

See Also:
Constant Field Values
Constructor Detail

JDBCAdaptor

public JDBCAdaptor(String name)
Create a JDBCAdaptor. User code should not normally create an adaptor with this constructor.

See Also:
EOAdaptor.adaptorWithModel(com.webobjects.eoaccess.EOModel), EOAdaptor.adaptorWithName(java.lang.String)
Method Detail

setConnectionDictionary

public void setConnectionDictionary(NSDictionary dictionary)
                             throws IllegalArgumentException
Description copied from class: EOAdaptor
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.

Overrides:
setConnectionDictionary in class EOAdaptor
Parameters:
dictionary - The adaptor's connection dictionary.
Throws:
IllegalArgumentException - if there are any open channels when this method is called.
See Also:
EOAdaptor.connectionDictionary(), EOAdaptor.hasOpenChannels(), EOAdaptor.assertConnectionDictionaryIsValid()

jdbcInfo

protected NSDictionary jdbcInfo()
Returns an NSDictionary of database-specific information.

Returns:
an NSDictionary of database-specific information
See Also:
JDBCPlugIn.jdbcInfo(), JDBCAdaptor.typeInfo()

typeInfo

protected NSDictionary typeInfo()
Returns an NSDictionary of external type information.

Returns:
an NSDictionary of external type information
See Also:
JDBCAdaptor.jdbcInfo()

connectionProperties

public Properties connectionProperties()
Returns a Properties object specifying connection information.

Returns:
a Properties object specifying connection information
See Also:
JDBCPlugIn.connectionPropertiesForConnectionDictionary(com.webobjects.foundation.NSDictionary)

canServiceModel

public boolean canServiceModel(EOModel model)
Returns true if the adaptor is compatible with the model; false otherwise. The decision is made by matching the connection dictionary of the adaptor against that of the model considering the following keys: URLKey, UsernameKey, PasswordKey, DriverKey, and PlugInKey.

Overrides:
canServiceModel in class EOAdaptor
Parameters:
model - A model.
Returns:
true if this adaptor instance can service database access requests for this model.
See Also:
JDBCAdaptor.URLKey, JDBCAdaptor.UsernameKey, JDBCAdaptor.PasswordKey, JDBCAdaptor.DriverKey, JDBCAdaptor.PlugInKey

varcharMaxLength

protected int varcharMaxLength()

assertConnectionDictionaryIsValid

public void assertConnectionDictionaryIsValid()
Checks that the connectionary dictionary is valid by attempting to make a connection. If it fails, a JDBCAdaptorException is thrown.

Specified by:
assertConnectionDictionaryIsValid in class EOAdaptor
See Also:
JDBCAdaptorException

createAdaptorContext

public EOAdaptorContext createAdaptorContext()
Returns a new JDBCContext for this adaptor.

Specified by:
createAdaptorContext in class EOAdaptor
Returns:
a new JDBCContext
See Also:
EOAdaptor.contexts()

handleDroppedConnection

public void handleDroppedConnection()
Handles cleaning up when a connection is dropped. Usually not called directly.

Overrides:
handleDroppedConnection in class EOAdaptor
See Also:
EOAdaptor.Delegate.reconnectionDictionaryForAdaptor(EOAdaptor adaptor), EOAdaptorContext.handleDroppedConnection()

plugIn

public JDBCPlugIn plugIn()
Returns the JDBCPlugIn to use with this adaptor's connection dictionary.

Returns:
a JDBCPlugIn
See Also:
EOAdaptor.connectionDictionary(), JDBCAdaptor.PlugInKey

plugInName

public String plugInName()
Returns the adaptor's plug-in name. Subclasses of EOAdaptor need to override this method if they support a plug-in achitecture.

Overrides:
plugInName in class EOAdaptor
Returns:
The name of the plug-in.

defaultExpressionClass

public Class defaultExpressionClass()
Returns the expression class to use for this adaptor. The expression class is normally determined by the plugin. It should be a subclass of JDBCExpression.

Specified by:
defaultExpressionClass in class EOAdaptor
Returns:
a subclass of JDBCExpression
See Also:
JDBCPlugIn.defaultExpressionClass(), JDBCExpression

expressionFactory

public EOSQLExpressionFactory expressionFactory()
Returns the expression factory to use for this adaptor. The expression factory is normally determined by the plugin. It should be a subclass of JDBCExpressionFactory.

Specified by:
expressionFactory in class EOAdaptor
Returns:
a JDBCExpressionFactory
See Also:
JDBCPlugIn.expressionFactory(), JDBCExpressionFactory

schemaSynchronizationFactory

public EOSchemaSynchronizationFactory schemaSynchronizationFactory()
Description copied from class: EOAdaptor
An abstract method that supports changes made to EOSQLExpression and related classes and interfaces. Subclass implementations return the EOSchemaGeneration for the adaptor.

Specified by:
schemaSynchronizationFactory in class EOAdaptor
Returns:
Should return the EOSchemaGeneration for the adaptor.
See Also:
EOSQLExpression

synchronizationFactory

@Deprecated
public EOSchemaGeneration synchronizationFactory()
Deprecated. 

Description copied from class: EOAdaptor
An abstract method that supports changes made to EOSQLExpression and related classes and interfaces. Subclass implementations return the EOSynchronizationFactory for the adaptor.

Specified by:
synchronizationFactory in class EOAdaptor
Returns:
Should return the EOSynchronizationFactory for the adaptor.
See Also:
EOSQLExpression

fetchedValueForValue

public Object fetchedValueForValue(Object value,
                                   EOAttribute attribute)
Calls super with the result of the plugIn's plugInValueForValue. This allows a PlugIn to influence the value. The basic behavior is the same as EOAdaptor.fetchedValueForValue.

Overrides:
fetchedValueForValue in class EOAdaptor
Parameters:
value - The original value.
attribute - The attribute corresponding to the database column in which value would be stored.
Returns:
value, or the new value.
See Also:
JDBCPlugIn.plugInValueForValue(java.lang.Object, com.webobjects.eoaccess.EOAttribute)

externalTypesWithModel

public NSArray externalTypesWithModel(EOModel model)
Returns an NSArray of external type names for the model. This information is often cached in the connection dictionary of the model, but the adaptor can also fetch it at runtime.

Overrides:
externalTypesWithModel in class EOAdaptor
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 NSArray of external type names

externalTypeForJDBCType

public String externalTypeForJDBCType(int type)
Returns the name of an external type that matches the given JDBC type type.

Returns:
a String naming a JDBC Type

isValidQualifierType

public boolean isValidQualifierType(String typeName,
                                    EOModel model)
Description copied from class: EOAdaptor
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.

Specified by:
isValidQualifierType in class EOAdaptor
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.

connectionDictionaryURL

protected String connectionDictionaryURL()
Returns the JDBC URL from the adaptor's connection dictionary.

Returns:
the JDBC URL

connectionURL

public String connectionURL()
Returns the JDBC URL that should be used for connecting to the database as specified by the plugin.

Returns:
the JDBC URL
See Also:
JDBCPlugIn.connectionURL()

username

public String username()
Returns the user name from the adaptor's connection dictionary.

Returns:
the user name

password

public String password()
Returns the password from the adaptor's connection dictionary.

Returns:
the password

driverName

public String driverName()
Returns the JDBC driver's name.

Returns:
the JDBC driver's name
See Also:
JDBCPlugIn.defaultDriverName()

createAttribute

public EOAttribute createAttribute(String name,
                                   String columnName,
                                   int columnType,
                                   String externalType,
                                   int precision,
                                   int scale,
                                   int isNullable)
Returns a new EOAttribute based on the arguments. This method is called during reverse engineering.

Parameters:
name - the name of the attribute
columnType - the JDBC type for the attribute
externalType - the external type for the attribute
precision - the precision (or width) of the attribute
scale - the scale of the attribute
isNullable - boolean indicating if the attribute allows NULL
Returns:
an EOAttribute

typeInfoForModel

protected static NSDictionary typeInfoForModel(EOModel model)

getJDBCInfoWithConnectionDictionary

protected static NSDictionary getJDBCInfoWithConnectionDictionary(NSDictionary connectionDictionary)
                                                           throws JDBCAdaptorException
Throws:
JDBCAdaptorException

stringRepresentationForJDBCType

public static String stringRepresentationForJDBCType(int columnType)

isDroppedConnectionException

public boolean isDroppedConnectionException(Exception exception)
Returns true if exception is a JDBCAdaptorException and it is considered a "dropped" connection; otherwise false. The adaptor will try to reconnect automatically from a dropped connection. The decision is based on the SQLState of the underlying SQLException that is wrapped by the JDBCAdaptorException. For any other type of Exception, this method returns false.

This method defer the decision to the plug-in so that each database vendor can customize teh error detection.

Overrides:
isDroppedConnectionException in class EOAdaptor
Parameters:
exception - An exception object.
Returns:
true if exception is a "dropped" connection; otherwise false
See Also:
EOAdaptor.handleDroppedConnection(), EOAdaptor.Delegate.reconnectionDictionaryForAdaptor( EOAdaptor adaptor)

assignExternalTypeForAttribute

public void assignExternalTypeForAttribute(EOAttribute attribute)
Assigns an appropriate external type to the attribute. The attribute should already have a value class, scale and precision. This method is invoked when reverse engineering or switching adaptors.

Overrides:
assignExternalTypeForAttribute in class EOAdaptor
Parameters:
attribute - The attribute for which to set a corresponding external type.
See Also:
EOAdaptor.assignExternalInfoForEntireModel(EOModel model)

Last updated June 2008

Copyright © 2000-2008 Apple Inc.