WebObjects 5.2

com.webobjects.jdbcadaptor
Class JDBCPlugIn

java.lang.Object
  |
  +--com.webobjects.jdbcadaptor.JDBCPlugIn
Direct Known Subclasses:
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:
plugInNameForURL(java.lang.String)

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().
 EOSynchronizationFactory createSynchronizationFactory()
          Creates a new EOSynchronizationFactory using the plugin's response to adaptor().
 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 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.
 NSArray newPrimaryKeys(int count, EOEntity entity, JDBCChannel channel)
          Generates a batch of new primary keys for entity.
 String newPrimaryKeySelectString(String pkTableName, String entityRootName)
           
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 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.
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()
          Returns the EOSynchronizationFactory, creating a new one if necessary.
 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

DefaultPlugInClassName

protected static final String DefaultPlugInClassName

DefaultPlugInSuffix

protected static final String DefaultPlugInSuffix
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

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:
an - EOAttribute
See Also:
EOAdaptor.assignExternalTypeForAttribute(com.webobjects.eoaccess.EOAttribute), EOAdaptorChannel.describeResults()

canDescribeStoredProcedure

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

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

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

createAttributeForRow

public EOAttribute createAttributeForRow(NSDictionary row)
Deprecated.  

This method is not used by the adaptor.

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:
expressionFactory()

createSynchronizationFactory

public EOSynchronizationFactory createSynchronizationFactory()
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:
synchronizationFactory()

databaseInformation

public NSDictionary databaseInformation()
Deprecated.  

This method is not used by the adaptor.

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

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

expressionFactory

public EOSQLExpressionFactory expressionFactory()
Returns the JDBCExpressionFactory, creating a new one if necessary.
Returns:
a JDBCExpressionFactory
See Also:
createExpressionFactory()

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)
See Also:
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)
See Also:
updateLOBs(com.webobjects.jdbcadaptor.JDBCChannel, com.webobjects.jdbcadaptor.JDBCExpression, com.webobjects.foundation.NSDictionary, com.webobjects.eoaccess.EOEntity)

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

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

newPrimaryKeySelectString

public String newPrimaryKeySelectString(String pkTableName,
                                        String entityRootName)

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:
primaryKeyTableName(), EOEntity.primaryKeyAttributes()

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:

The Properties file in the Resource directory of the JDBC Adaptor framework has some additional comments.
Returns:
JDBCPlugIn class name
See Also:
setPlugInNameForSubprotocol(java.lang.String, java.lang.String)

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)

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:
newPrimaryKeys(int, com.webobjects.eoaccess.EOEntity, com.webobjects.jdbcadaptor.JDBCChannel)

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:
setPlugInNameForSubprotocol(java.lang.String, java.lang.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()

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:
removePlugInNameForSubprotocol(java.lang.String)

sqlStatementForGettingProcedureNames

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

sqlStatementForGettingTableNames

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

sqlStatementForTableNamed

public String sqlStatementForTableNamed(String tablename)
Deprecated.  

This method is not used by the adaptor.

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:
storedProcedureSchemaPattern()

storedProcedureNamed

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)

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:
storedProcedureCatalogPattern()

synchronizationFactory

public EOSynchronizationFactory synchronizationFactory()
Returns the EOSynchronizationFactory, creating a new one if necessary.
Returns:
a EOSynchronizationFactory
See Also:
createSynchronizationFactory()

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

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:
fetchBLOB(java.sql.ResultSet, int, com.webobjects.eoaccess.EOAttribute, boolean), fetchCLOB(java.sql.ResultSet, int, com.webobjects.eoaccess.EOAttribute, boolean)

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

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

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

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.