com.webobjects.jdbcadaptor
Class JDBCPlugIn

java.lang.Object
  com.webobjects.jdbcadaptor.JDBCPlugIn

Direct Known Subclasses:

DerbyPlugIn, FrontbasePlugIn, MicrosoftPlugIn, MySQLPlugIn, OpenBasePlugIn, OraclePlugIn, SybasePlugIn

public class JDBCPlugIn
extends Object

JDBCPlugIn is used to customize the JDBCAdaptor for a particular database and its JDBC driver. The JDBCPlugIn for a model can be specified in the model's connection dictionary. If it's left unspecified, the adaptor takes a guess.

See Also:

JDBCPlugIn.plugInNameForURL(java.lang.String)

Nested Class Summary

protected static class

JDBCPlugIn.LobEntry

Field Summary

protected static String	DefaultPlugInClassName
protected static String	DefaultPlugInSuffix

Constructor Summary

JDBCPlugIn(JDBCAdaptor adaptor)
Create a new JDBCPlugIn.

Method Summary

JDBCAdaptor	adaptor() Returns the JDBCAdaptor associated with this plugin.
void	assignTypeForAttribute(EOAttribute attribute) The adaptor invokes this method to allow the JDBCPlugIn to customize the newly created attribute.
boolean	canDescribeStoredProcedure(String spName) Deprecated.
Properties	connectionPropertiesForConnectionDictionary(NSDictionary connectionDictionary) Returns a Properties object that should be used for setting up a connection environment.
String	connectionURL() Returns the JDBC URL to use for connecting to the database.
EOAttribute	createAttributeForRow(NSDictionary row) Deprecated.
EOSQLExpressionFactory	createExpressionFactory() Creates a new JDBCExpresionFactory using the plugin's response to adaptor().
EOSchemaSynchronizationFactory	createSchemaSynchronizationFactory() Creates a new EOSynchronizationFactory using the plugin's response to adaptor().
EOSynchronizationFactory	createSynchronizationFactory() Deprecated. since 5.4
NSDictionary	databaseInformation() Deprecated.
String	databaseProductName() Returns a string identifying the database.
String	defaultDriverName() Returns a fully qualified name of the JDBC driver class that this plugin prefers to use.
Class	defaultExpressionClass() Returns the Java Class to use as the expression class.
EOSQLExpressionFactory	expressionFactory() Returns the JDBCExpressionFactory, creating a new one if necessary.
Object	fetchBLOB(ResultSet rs, int column, EOAttribute attribute, boolean materialize) Fetch a BLOB.
Object	fetchCLOB(ResultSet rs, int column, EOAttribute attribute, boolean materialize) Fetch a CLOB.
boolean	isDroppedConnectionException(JDBCAdaptorException exception) Returns true if exception is considered a "dropped" connection; otherwise false.
boolean	isPseudoColumnName(String columnName) Determines if the column is a "pseudo" column.
NSDictionary	jdbcInfo() Returns database-specific information about the JDBC data source.
int	jdbcTypeForUnknownExternalType(String externalType, int precision, int scale) Returns a JDBC type that might be more useful than Types.OTHER.
String	name() Returns the plugin's name.
NSArray	newPrimaryKeys(int count, EOEntity entity, JDBCChannel channel) Generates a batch of new primary keys for entity.
String	newPrimaryKeySelectString(String pkTableName, String entityRootName) The statement for selecting the primary key for a given entity.
static String	plugInNameForURL(String url) Returns the class name of the JDBCPlugIn that should be used with the given JDBC URL url.
Object	plugInValueForValue(Object value, EOAttribute attribute) Allows the plugIn to influence the value seen by JDBCAdaptor.fetchedValueForValue.
String	primaryKeyLockString(String pkTableName, String entityRootName)
String	primaryKeyTableCreateString(String pkTableName, EOSQLExpression getRowExpr, EOAttribute primAttribute) The statement for creating the primaryKeyTable can be overridden here.
String	primaryKeyTableName() Default returns "EO_PK_TABLE".
static void	removePlugInNameForSubprotocol(String subprotocol) Removes any special internal mapping associated with subprotocol that might have been used to guess a plugin an appropriate plugin.
String	schemaNameForEntity(EOEntity entity) Return the schema associated with entity.
EOSchemaSynchronizationFactory	schemaSynchronizationFactory() Returns the EOSynchronizationFactory, creating a new one if necessary.
static void	setPlugInNameForSubprotocol(String pluginName, String subprotocol) Sets the internal mapping of subprotocol to pluginName for guessing which plugin to use.
String	sqlStatementForGettingProcedureNames() Deprecated.
String	sqlStatementForGettingTableNames() Deprecated.
String	sqlStatementForTableNamed(String tablename) Deprecated.
String	storedProcedureCatalogPattern() The standard reverse engineering implementation for stored procedures calls this method to get the catalog pattern used with the JDBC method getProcedures.
EOStoredProcedure	storedProcedureNamed(String spName, JDBCChannel channel, NSDictionary jdbcTypeDictionary) Deprecated.
String	storedProcedureSchemaPattern() The standard reverse engineering implementation for stored procedures calls this method to get the schema pattern used with the JDBC method getProcedures.
EOSynchronizationFactory	synchronizationFactory() Deprecated. since 5.4
String[]	tableTypes() Return an array of Strings to use for describing the table types in the JDBC getTables method call.
void	updateLOBs(JDBCChannel channel, JDBCExpression expr, NSDictionary row, EOEntity entity) Update LOBs (BLOBs and CLOBs).
String	wildcardPatternForAttributes() Return the String to use for describing the column pattern in the JDBC getColumns method call.
String	wildcardPatternForSchema() Return the String to use for describing the schema pattern in the JDBC getTables method call.
String	wildcardPatternForTables() Return the String to use for describing the table pattern in the JDBC getTables method call.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DefaultPlugInSuffix

protected static final String DefaultPlugInSuffix

See Also:

Constant Field Values

DefaultPlugInClassName

protected static final String DefaultPlugInClassName

See Also:

Constant Field Values

Constructor Detail

JDBCPlugIn

public JDBCPlugIn(JDBCAdaptor adaptor)

Create a new JDBCPlugIn. Subclasses will typically just call super.

Method Detail

adaptor

public JDBCAdaptor adaptor()

Returns the JDBCAdaptor associated with this plugin.

Returns:

the JDBCAdaptor

name

public String name()

Returns the plugin's name. Subclasses of JDBCPlugIn need to override this method.

Returns:

The name of the receiver.

connectionURL

public String connectionURL()

Returns the JDBC URL to use for connecting to the database. The default implementation gets the URL from the adaptor.

Returns:

a JDBC URL

See Also:

JDBCAdaptor.connectionDictionaryURL()

connectionPropertiesForConnectionDictionary

public Properties connectionPropertiesForConnectionDictionary(NSDictionary connectionDictionary)

Returns a Properties object that should be used for setting up a connection environment. The default implementation asks the adaptor for the username and password.

Returns:

Properties for the connection environment

See Also:

JDBCAdaptor.username(), JDBCAdaptor.password()

setPlugInNameForSubprotocol

public static void setPlugInNameForSubprotocol(String pluginName,
                                               String subprotocol)

Sets the internal mapping of subprotocol to pluginName for guessing which plugin to use. The subprotocol is the second term in a JDBC URL.

Parameters:

pluginName - a String naming the plugin class

subprotocol - a JDBC subprotocol

See Also:

JDBCPlugIn.removePlugInNameForSubprotocol(java.lang.String)

removePlugInNameForSubprotocol

public static void removePlugInNameForSubprotocol(String subprotocol)

Removes any special internal mapping associated with subprotocol that might have been used to guess a plugin an appropriate plugin.

Parameters:

subprotocol - a JDBC subprotocol

See Also:

JDBCPlugIn.setPlugInNameForSubprotocol(java.lang.String, java.lang.String)

plugInNameForURL

public static String plugInNameForURL(String url)

Returns the class name of the JDBCPlugIn that should be used with the given JDBC URL url. The method considers the subprotocol of the url and looks for a match that was established by setPlugInNameForSubprotocol. If there is no match, it uses a default mapping of the form: "com.webobjects.jdbcadaptor.SubPlugIn", where Sub is replaced by the capitalized subprotocol string. For example, the URL "jdbc:oracle:thin:@myserver:1521:sid" maps to "com.webobjects.jdbcadaptor.OraclePlugIn". The default mapping can be overridden at start-up by the following Java Properties:

• jdbcadaptor.plugin.subprotocols - a colon-separated list of subprotocols that might have designated plugins
• jdbcadaptor.SUB.plugin - for a subprotocol SUB, the property defines the class name of the default plugin; SUB must be listed in jdbcadaptor.plugin.subprotocols

The Properties file in the Resource directory of the JDBC Adaptor framework has some additional comments.

Returns:

JDBCPlugIn class name

See Also:

JDBCPlugIn.setPlugInNameForSubprotocol(java.lang.String, java.lang.String)

databaseProductName

public String databaseProductName()

Returns a string identifying the database. Subclasses should override.

Returns:

a String identifying the database

defaultDriverName

public String defaultDriverName()

Returns a fully qualified name of the JDBC driver class that this plugin prefers to use. The adaptor will attempt to load this class when making a connection. Subclasses should override.

Returns:

JDBC driver class name

databaseInformation

@Deprecated
public NSDictionary databaseInformation()

Deprecated.

This method is not used by the adaptor.

defaultExpressionClass

public Class defaultExpressionClass()

Returns the Java Class to use as the expression class. The default is JDBCExpression. Subclasses will typically override to use their own subclass of JDBCExpression.

Returns:

a Java Class (subclass of JDBCExpression)

See Also:

JDBCExpression, JDBCAdaptor.defaultExpressionClass()

createExpressionFactory

public EOSQLExpressionFactory createExpressionFactory()

Creates a new JDBCExpresionFactory using the plugin's response to adaptor(). Subclasses rarely need to override this.

Returns:

a JDBCExpressionFactory

See Also:

JDBCPlugIn.expressionFactory()

expressionFactory

public EOSQLExpressionFactory expressionFactory()

Returns the JDBCExpressionFactory, creating a new one if necessary.

Returns:

a JDBCExpressionFactory

See Also:

JDBCPlugIn.createExpressionFactory()

createSchemaSynchronizationFactory

public EOSchemaSynchronizationFactory createSchemaSynchronizationFactory()

Creates a new EOSynchronizationFactory using the plugin's response to adaptor(). The default EOSynchronizationFactory supports only basic SQL table generation. Subclasses need to override this method to support schema synchronization.

Returns:

a JDBCExpressionFactory

Since:

5.4

See Also:

JDBCPlugIn.synchronizationFactory()

schemaSynchronizationFactory

public EOSchemaSynchronizationFactory schemaSynchronizationFactory()

Returns the EOSynchronizationFactory, creating a new one if necessary.

Returns:

a EOSynchronizationFactory

Since:

5.4

See Also:

JDBCPlugIn.createSynchronizationFactory()

createSynchronizationFactory

@Deprecated
public EOSynchronizationFactory createSynchronizationFactory()

Deprecated. since 5.4

Creates a new EOSynchronizationFactory using the plugin's response to adaptor(). The default EOSynchronizationFactory supports only basic SQL table generation. Subclasses need to override this method to support schema synchronization.

Returns:

a JDBCExpressionFactory

See Also:

JDBCPlugIn.synchronizationFactory()

synchronizationFactory

@Deprecated
public EOSynchronizationFactory synchronizationFactory()

Deprecated. since 5.4

Returns the EOSynchronizationFactory, creating a new one if necessary.

Returns:

a EOSynchronizationFactory

See Also:

JDBCPlugIn.createSynchronizationFactory()

primaryKeyTableName

public String primaryKeyTableName()

Default returns "EO_PK_TABLE". Subclasses typically don't override this.

Returns:

the name of the table used for generating primary keys

See Also:

JDBCPlugIn.newPrimaryKeys(int, com.webobjects.eoaccess.EOEntity, com.webobjects.jdbcadaptor.JDBCChannel)

wildcardPatternForAttributes

public String wildcardPatternForAttributes()

Return the String to use for describing the column pattern in the JDBC getColumns method call. This is used for reverse engineering. The default implementation returns "%".

Returns:

a wildcard pattern string

wildcardPatternForTables

public String wildcardPatternForTables()

Return the String to use for describing the table pattern in the JDBC getTables method call. This is used for reverse engineering. The default implementation returns "%".

Returns:

a wildcard pattern string

wildcardPatternForSchema

public String wildcardPatternForSchema()

Return the String to use for describing the schema pattern in the JDBC getTables method call. This is used for reverse engineering. The default implementation returns null.

Returns:

a wildcard pattern string

schemaNameForEntity

public String schemaNameForEntity(EOEntity entity)

Return the schema associated with entity. This is used as an argument to the JDBC method getColumns when reverse engineering. The default implementation gets the schema from the externalName of the entity.

Returns:

a schema String

See Also:

EOEntity.externalName()

tableTypes

public String[] tableTypes()

Return an array of Strings to use for describing the table types in the JDBC getTables method call. This is used for reverse engineering. The default implementation returns {"TABLE", "VIEW", "ALIAS", "SYNONYM"}.

Returns:

an array of table type Strings

sqlStatementForGettingTableNames

@Deprecated
public String sqlStatementForGettingTableNames()

Deprecated.

Returns a SQL statement to be used for fetching a list of available tables during reverse engineering. The result set should have a single column, the table name. The default implementation returns null, which tells the adaptor to use the standard JDBC method getTables. Subclasses might override this method.

Returns:

a SQL statement for fetching table names

canDescribeStoredProcedure

@Deprecated
public boolean canDescribeStoredProcedure(String spName)

Deprecated.

Returns true if the plugin has a private way of describing the stored procedure named spName when reverse engineering. The default implementation returns false indicating that the adaptor should use the normal JDBC API to reverse engineer the the stored procedure.

Parameters:

spName - the name of a stored procedure

storedProcedureNamed

@Deprecated
public EOStoredProcedure storedProcedureNamed(String spName,
                                                         JDBCChannel channel,
                                                         NSDictionary jdbcTypeDictionary)

Deprecated.

If canDescribeStoredProcedure returns true, this method is called to reverse engineer the stored procedure. The default implementation returns null. Most plugins do not need to override this.

Parameters:

spName - the name of a stored procedure

channel - a JDBCChannel (already connected)

jdbcTypeDictionary - an NSDictionary describing the external types

sqlStatementForGettingProcedureNames

@Deprecated
public String sqlStatementForGettingProcedureNames()

Deprecated.

The default implementation of this method returns null to indicate that the JDBC API should be used for reverse engineering stored procedures. Subclasses can implement a private scheme for reverse engineering stored procedures by returning a SQL statement to be used for fetching stored procedures names. The SQL statement should return a result set with one column named 'name'.

storedProcedureCatalogPattern

public String storedProcedureCatalogPattern()

The standard reverse engineering implementation for stored procedures calls this method to get the catalog pattern used with the JDBC method getProcedures. The default implementation returns null.

See Also:

JDBCPlugIn.storedProcedureSchemaPattern()

storedProcedureSchemaPattern

public String storedProcedureSchemaPattern()

The standard reverse engineering implementation for stored procedures calls this method to get the schema pattern used with the JDBC method getProcedures. The default implementation returns null.

See Also:

JDBCPlugIn.storedProcedureCatalogPattern()

sqlStatementForTableNamed

@Deprecated
public String sqlStatementForTableNamed(String tablename)

Deprecated.

This method is not used by the adaptor.

createAttributeForRow

@Deprecated
public EOAttribute createAttributeForRow(NSDictionary row)

Deprecated.

This method is not used by the adaptor.

newPrimaryKeySelectString

public String newPrimaryKeySelectString(String pkTableName,
                                        String entityRootName)

The statement for selecting the primary key for a given entity. Statement can be overridden in subclassers. By default return null. SELECT PK FROM EO_PK_TABLE WHERE NAME = 'MOVIE' FOR UPDATE

Returns:

SQL string for selecting primary key from EO_PK_TABLE for a given table

primaryKeyLockString

public String primaryKeyLockString(String pkTableName,
                                   String entityRootName)

primaryKeyTableCreateString

public String primaryKeyTableCreateString(String pkTableName,
                                          EOSQLExpression getRowExpr,
                                          EOAttribute primAttribute)

The statement for creating the primaryKeyTable can be overridden here. By default return null. CREATE TABLE (NAME CHAR(40), PK INTEGER)

Returns:

SQL string for creating EO_PK_TABLE

Since:

5.4

newPrimaryKeys

public NSArray newPrimaryKeys(int count,
                              EOEntity entity,
                              JDBCChannel channel)

Generates a batch of new primary keys for entity. It should return an NSArray of NSDictionary where each dictionary corresponds to a unique primary key value. The count of the NSArray should match count. The JDBChannel channel is already open and ready to use. If the primary key contains multiple attributes or is not of kind number, then the default implementation returns null. The default implementation uses a table named according to primaryKeyTableName containing the table name and the last primary key inserted in this table. If the row for a table name is not present, then it is automatically created. If the primaryKeyTableName table does not exists then it is automatically created. Subclasses should override the default implementation if they want to provide a more efficient mechanism for generating primary keys.

Parameters:

count - the batch size

entity - the entity requesting primary keys

channel - an open JDBCChannel

See Also:

JDBCPlugIn.primaryKeyTableName(), EOEntity.primaryKeyAttributes()

fetchBLOB

public Object fetchBLOB(ResultSet rs,
                        int column,
                        EOAttribute attribute,
                        boolean materialize)
                 throws SQLException

Fetch a BLOB. This supports a database-specific way of fetching a BLOB so plugin subclasses need to override the default, which simply returns null.

Parameters:

rs - the current ResultSet

column - the column index corresponding to the BLOB

attribute - the attribute mapped to the BLOB

materialize - a boolean that determines if the BLOB should be fully "materialized" (if true) or left as a reference (if false)

Throws:

SQLException

See Also:

JDBCPlugIn.updateLOBs(com.webobjects.jdbcadaptor.JDBCChannel, com.webobjects.jdbcadaptor.JDBCExpression, com.webobjects.foundation.NSDictionary, com.webobjects.eoaccess.EOEntity)

fetchCLOB

public Object fetchCLOB(ResultSet rs,
                        int column,
                        EOAttribute attribute,
                        boolean materialize)
                 throws SQLException

Fetch a CLOB. This supports a database-specific way of fetching a CLOB so plugin subclasses need to override the default, which simply returns null.

Parameters:

rs - the current ResultSet

column - the column index corresponding to the CLOB

attribute - the attribute mapped to the CLOB

materialize - a boolean that determines if the CLOB should be fully "materialized" (if true) or left as a reference (if false)

Throws:

SQLException

See Also:

JDBCPlugIn.updateLOBs(com.webobjects.jdbcadaptor.JDBCChannel, com.webobjects.jdbcadaptor.JDBCExpression, com.webobjects.foundation.NSDictionary, com.webobjects.eoaccess.EOEntity)

updateLOBs

public void updateLOBs(JDBCChannel channel,
                       JDBCExpression expr,
                       NSDictionary row,
                       EOEntity entity)

Update LOBs (BLOBs and CLOBs). This supports a database-specific way of updating LOBs so plugin subclasses need to override the default, which does nothing. This method is called after a new row is inserted or after an existing row is updated. The plugin's JDBCExpression subclass will typically have to keep some extra bookkeeping information in order to implement this functionality.

Parameters:

channel - an open JDBCChannel

expr - the JDBCExpression used to perform the insert or update

row - an NSDictionary of the row values used in the insert or update

entity - the entity of the row that was inserted or updated

See Also:

JDBCPlugIn.fetchBLOB(java.sql.ResultSet, int, com.webobjects.eoaccess.EOAttribute, boolean), JDBCPlugIn.fetchCLOB(java.sql.ResultSet, int, com.webobjects.eoaccess.EOAttribute, boolean)

jdbcInfo

public NSDictionary jdbcInfo()

Returns database-specific information about the JDBC data source. Subclasses may want to return a modified copy of the dictionary returned by calling super.

Returns:

an NSDictionary describing database-specific information about the JDBC data source

jdbcTypeForUnknownExternalType

public int jdbcTypeForUnknownExternalType(String externalType,
                                          int precision,
                                          int scale)

Returns a JDBC type that might be more useful than Types.OTHER. Some JDBC drivers return Types.OTHER for external types that actually match better to a well known type. This method provides the plugin a chance to substitute a better JDBC type when reverse engineering. The default implementation specifically recognizes BLOB and CLOB external types as mapping to Types.BLOB and Types.CLOB. If no better type is known, the method should return Types.OTHER.

Returns:

a java.sql.Types constant

assignTypeForAttribute

public void assignTypeForAttribute(EOAttribute attribute)

The adaptor invokes this method to allow the JDBCPlugIn to customize the newly created attribute. The default implementation does nothing.

Parameters:

attribute - an EOAttribute

See Also:

EOAdaptor.assignExternalTypeForAttribute(com.webobjects.eoaccess.EOAttribute), EOAdaptorChannel.describeResults()

isPseudoColumnName

public boolean isPseudoColumnName(String columnName)

Determines if the column is a "pseudo" column. A pseudo column is one that was not part of the CREATE TABLE statement, but was created automatically by the database. These columns usually should not be considered for reverse engineering.

Returns:

true if the column should not be reverse engineered; false otherwise

isDroppedConnectionException

public boolean isDroppedConnectionException(JDBCAdaptorException exception)

Returns true if exception 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.

Returns:

true if exception is a "dropped" connection; otherwise false

plugInValueForValue

public Object plugInValueForValue(Object value,
                                  EOAttribute attribute)

Allows the plugIn to influence the value seen by JDBCAdaptor.fetchedValueForValue. By default, it returns NSKeyValueCoding.NullValue if value is null; otherwise, value is returned unchanged.

Parameters:

value - the original value

attribute - the attribute corresponding to the database column in which value would be stored

Returns:

an Object that should be passed on to fetchedValueForValue

See Also:

JDBCAdaptor.fetchedValueForValue(java.lang.Object, com.webobjects.eoaccess.EOAttribute)