com.webobjects.jdbcadaptor
Class JDBCAdaptor

java.lang.Object
  com.webobjects.eoaccess.EOAdaptor
      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)