com.webobjects.jdbcadaptor
Class JDBCChannel

java.lang.Object
  com.webobjects.eoaccess.EOAdaptorChannel
      com.webobjects.jdbcadaptor.JDBCChannel

public class JDBCChannel

extends EOAdaptorChannel

Nested Class Summary

Nested classes inherited from class com.webobjects.eoaccess.EOAdaptorChannel

EOAdaptorChannel.Delegate

Field Summary

Fields inherited from class com.webobjects.eoaccess.EOAdaptorChannel

AdaptorFailureKey, AdaptorOperationsKey, AdaptorOptimisticLockingFailure, FailedAdaptorOperationKey

Constructor Summary

JDBCChannel(JDBCContext context)

Method Summary

void	addStoredProceduresNamed(NSArray storedProcedureNames, EOModel model) The default implementation of this method does nothing.
NSArray	attributesToFetch() An abstract method that should be implemented by subclasses to return the set of attributes to retrieve when fetchRow is next invoked.
void	cancelFetch() An abstract method that should be implemented by subclasses to clear all result sets established by the last selectAttributes, executeStoredProcedure, or evaluateExpression message and terminate the current fetch, so that isFetchInProgress returns false.
void	closeChannel() An abstract method that should be implemented by subclasses to close the EOAdaptorChannel so that it can't perform operations with the server.
int	deleteRowsDescribedByQualifier(EOQualifier qualifier, EOEntity entity) An abstract method that should be implemented by subclasses to delete the rows described by qualifier from the database table corresponding to entity.
EOModel	describeModelWithTableNames(NSArray tableNames) The default implementation of this method returns null.
NSArray	describeResults() An abstract method that should be implemented by subclasses to return an array of EOAttributes describing the properties available in the current result set, as determined by selectAttributes, executeStoredProcedure, or a statement evaluated by evaluateExpression.
NSArray	describeStoredProcedureNames() The default implementation of this method returns an empty array.
NSArray	describeTableNames() The default implementation of this method returns an empty array.
void	evaluateExpression(EOSQLExpression expression) An abstract method that should be implemented by subclasses to send expression to the database server for evaluation, beginning a transaction first and committing it after evaluation if a transaction isn't already in progress.
void	executeStoredProcedure(EOStoredProcedure storedProcedure, NSDictionary dictionary) An abstract method that should be implemented by subclasses to execute storedProcedure.
NSMutableDictionary	fetchRow() An abstract method that should be implemented by subclasses to fetch the next row from the result set of the last selectAttributes, executeStoredProcedure, or evaluateExpression message sent to the receiver.
NSDictionary	generateExecuteStoredProcedureExpression(EOStoredProcedure storedProcedure, NSDictionary values) Invoked by executeStoredProcedure to parse the supplied text, usually from an EOModel, and generate a string for the expression and an NSArray of bindings for the values of the stored procedure's parameters.
void	insertRow(NSDictionary row, EOEntity entity) An abstract method that should be implemented by subclasses to insert the values of row into the table in the database that corresponds to entity.
boolean	isFetchInProgress() An abstract method that should be implemented by subclasses to return true if the receiver is fetching, false otherwise.
boolean	isOpen() An abstract method that should be implemented by subclasses to return true if the channel has been opened with openChannel, false if not.
void	openChannel() An abstract method that should be implemented by subclasses to put the channel, and both its context and adaptor, into a state where they are ready to perform database operations.
NSDictionary	primaryKeyForNewRowWithEntity(EOEntity entity)
NSArray	primaryKeysForNewRowsWithEntity(int count, EOEntity entity) Returns an NSArray of primary key dictionaries for the number of new rows specified by count in the database table that corresponds to entity.
NSDictionary	returnValuesForLastStoredProcedureInvocation() An abstract method that should be implemented by subclasses to return values from the execution of a stored procedure.
int	rowsProcessedCount()
void	selectAttributes(NSArray attributes, EOFetchSpecification fetchSpec, boolean yn, EOEntity entity) An abstract method that should be implemented by subclasses to select attributes in rows matching the qualifier in fetchSpecification and set the receiver's attributes to fetch.
void	setAttributesToFetch(NSArray attributes) An abstract method that should be implemented by subclasses to specify the set of attributes used to describe fetch data from a corresponding select.
int	updateValuesInRowsDescribedByQualifier(NSDictionary row, EOQualifier qualifier, EOEntity entity) An abstract method that should be implemented by subclasses to update the rows described by qualifier with the values in row.

Methods inherited from class com.webobjects.eoaccess.EOAdaptorChannel

adaptorContext, delegate, deleteRowDescribedByQualifier, dictionaryWithObjectsForAttributes, lockRowComparingAttributes, performAdaptorOperation, performAdaptorOperations, setDelegate, updateValuesInRowDescribedByQualifier

Methods inherited from class java.lang.Object

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

Constructor Detail

JDBCChannel

public JDBCChannel(JDBCContext context)

Method Detail

addStoredProceduresNamed

public void addStoredProceduresNamed(NSArray storedProcedureNames,
                                     EOModel model)

Description copied from class: EOAdaptorChannel

The default implementation of this method does nothing. It can be overridden by subclasses to create EOStoredProcedure objects for the stored procedures named in storedProcedureNames and then to add them to model. Should throw a runtime exception if an error occurs.

This method is used in conjunction with describeStoredProcedureNames to build a default model in EOModeler.

Overrides:

addStoredProceduresNamed in class EOAdaptorChannel

Parameters:

storedProcedureNames - The names of stored procedures to add to a model.

model - The model to which to add stored procedures.

See Also:

EOAdaptorChannel.describeStoredProcedureNames(), EOModel, EOStoredProcedure

attributesToFetch

public NSArray attributesToFetch()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to return the set of attributes to retrieve when fetchRow is next invoked.

Specified by:

attributesToFetch in class EOAdaptorChannel

Returns:

Should return the array of attributes used by the adaptor for a particular fetch.

See Also:

EOAdaptorChannel.fetchRow()

cancelFetch

public void cancelFetch()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to clear all result sets established by the last selectAttributes, executeStoredProcedure, or evaluateExpression message and terminate the current fetch, so that isFetchInProgress returns false.

Specified by:

cancelFetch in class EOAdaptorChannel

See Also:

EOAdaptorChannel.selectAttributes(NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOAdaptorChannel.executeStoredProcedure(EOStoredProcedure storedProcedure, NSDictionary values), EOAdaptorChannel.evaluateExpression(EOSQLExpression expression), EOAdaptorChannel.isFetchInProgress()

closeChannel

public void closeChannel()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to close the EOAdaptorChannel so that it can't perform operations with the server. Any fetch in progress should be canceled.

If the receiver is the last open channel in an adaptor context and if the channel's adaptor context has outstanding transactions, closing the channel has server-dependent results: some database servers roll back all outstanding transactions but others do nothing. Regardless of whether outstanding transactions are rolled back, this method has the side effect of closing the receiver's adaptor context's connection with the database if the receiver is its adaptor context's last open channel.

Specified by:

closeChannel in class EOAdaptorChannel

See Also:

EOAdaptorChannel.cancelFetch(), EOAdaptorContext.hasOpenTransaction()

deleteRowsDescribedByQualifier

public int deleteRowsDescribedByQualifier(EOQualifier qualifier,
                                          EOEntity entity)

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to delete the rows described by qualifier from the database table corresponding to entity. Should return the number of rows deleted. Should throw a runtime exception on failure. Some possible reasons for failure are:

• The adaptor channel isn't open.
• The adaptor channel is in an invalid state (for example, it's fetching).
• An error occurs in the database server.

Specified by:

deleteRowsDescribedByQualifier in class EOAdaptorChannel

Parameters:

qualifier - Describes the row(s) to delete.

entity - The entity corresponding to the row(s) to delete.

Returns:

Should return the number of rows deleted.

See Also:

EOAdaptorChannel.deleteRowDescribedByQualifier(EOQualifier qualifier, EOEntity entity), EOAdaptorChannel.isFetchInProgress(), EOAdaptorContext.hasOpenTransaction(), EOEntity, EOQualifier

describeModelWithTableNames

public EOModel describeModelWithTableNames(NSArray tableNames)

Description copied from class: EOAdaptorChannel

The default implementation of this method returns null. It can be overridden by subclasses to create and return a default model containing entities for the tables specified in tableNames and assign the adaptor name and connection dictionary to the new model. This method is typically used in conjunction with describeTableNames and describeStoredProcedureNames.

Overrides:

describeModelWithTableNames in class EOAdaptorChannel

Parameters:

tableNames - The entity names for database tables.

Returns:

Should return a default model containing entities for the tables specified in tableNames.

See Also:

EOAdaptorChannel.describeTableNames(), EOAdaptorChannel.describeStoredProcedureNames(), EOModel

describeResults

public NSArray describeResults()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to return an array of EOAttributes describing the properties available in the current result set, as determined by selectAttributes, executeStoredProcedure, or a statement evaluated by evaluateExpression. Only invoke this method if a fetch is in progress as determined by isFetchInProgress.

Specified by:

describeResults in class EOAdaptorChannel

Returns:

Should return an array of attributes describing the properties available in the current result set.

See Also:

EOAdaptorChannel.selectAttributes(NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOAdaptorChannel.executeStoredProcedure(EOStoredProcedure storedProcedure, NSDictionary values), EOAdaptorChannel.evaluateExpression(EOSQLExpression expression), EOAdaptorChannel.isFetchInProgress(), EOAttribute

describeStoredProcedureNames

public NSArray describeStoredProcedureNames()

Description copied from class: EOAdaptorChannel

The default implementation of this method returns an empty array. It can be overridden by subclasses to read and return an array of stored procedure names from the database. Should throw a runtime exception if an error occurs.

This method is used in conjunction with addStoredProceduresNamed to build a default model in EOModeler.

Overrides:

describeStoredProcedureNames in class EOAdaptorChannel

Returns:

Should return an array of stored procedure names from the database.

See Also:

EOAdaptorChannel.addStoredProceduresNamed( NSArray storedProcedureNames, EOModel model)

describeTableNames

public NSArray describeTableNames()

Description copied from class: EOAdaptorChannel

The default implementation of this method returns an empty array. It can be overridden by subclasses to read and return an array of table names from the database metadata.

This method is used in conjunction with describeStoredProcedureNames to build a default model in EOModeler.

Overrides:

describeTableNames in class EOAdaptorChannel

Returns:

An array of table names from the database.

See Also:

EOAdaptorChannel.describeModelWithTableNames(NSArray tableNames)

evaluateExpression

public void evaluateExpression(EOSQLExpression expression)

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to send expression to the database server for evaluation, beginning a transaction first and committing it after evaluation if a transaction isn't already in progress. Should throw a runtime exception if an error occurs. An adaptor channel uses this method to send SQL expressions to the database.

If expression results in a select operation being performed, you can fetch the results as you would if you had invoked selectAttributes. You must use the method setAttributesToFetch before you begin fetching. If expression evaluates to multiple result sets, you must invoke setAttributesToFetch before you begin fetching each subsequent set.

evaluateExpression invokes the delegate methods adaptorChannelShouldEvaluateExpression and adaptorChannelDidEvaluateExpression.

The upper layers of the Framework never invoke evaluateExpression directly. Thus, in adaptors for data stores that don't naturally support an expression language (for example, flat file adaptors), the implementation of this method doesn't need to do anything in order for the adaptor to work with the Framework.

Specified by:

evaluateExpression in class EOAdaptorChannel

Parameters:

expression - An expression to be evaluated by the database server.

See Also:

EOAdaptorChannel.fetchRow(), EOAdaptorChannel.selectAttributes( NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOAdaptorChannel.setAttributesToFetch(NSArray attributes), EOAdaptorChannel.Delegate.adaptorChannelShouldEvaluateExpression( EOAdaptorChannel channel, EOSQLExpression expression), EOAdaptorChannel.Delegate.adaptorChannelDidEvaluateExpression( EOAdaptorChannel channel, EOSQLExpression expression), EOSQLExpression

executeStoredProcedure

public void executeStoredProcedure(EOStoredProcedure storedProcedure,
                                   NSDictionary dictionary)

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to execute storedProcedure. Any arguments to the stored procedure are in values, a dictionary whose keys are the argument names. You should use fetchRow to get result rows and returnValuesForLastStoredProcedureInvocation to get return arguments and result status, if any. Should throw a runtime exception if an error occurs.

The upper layers of the Framework never invoke executeStoredProcedure directly. Thus, in adaptors for data stores that don't naturally support stored procedures, the implementation of this method doesn't need to do anything in order for the adaptor to work with the Framework.

Specified by:

executeStoredProcedure in class EOAdaptorChannel

Parameters:

storedProcedure - The stored procedure to execute.

dictionary - A dictionary whose keys are the argument names and whose values are the argument values to be passed to storedProcedure.

See Also:

EOAdaptorChannel.returnValuesForLastStoredProcedureInvocation(), EOAdaptorChannel.fetchRow(), (EOStoredProcedure storedProcedure, NSDictionary values), EOStoredProcedure

fetchRow

public NSMutableDictionary fetchRow()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to fetch the next row from the result set of the last selectAttributes, executeStoredProcedure, or evaluateExpression message sent to the receiver. Should return values for the receiver's attributesToFetch in a dictionary whose keys are the attribute names. When there are no more rows in the current result set, this method should return null and invoke the delegate method adaptorChannelDidChangeResultSet if there are more results sets.

When there are no more rows or result sets, this method should return null, end the fetch, and invoke adaptorChannelDidFinishFetching. isFetchInProgress returns true until the fetch is canceled or until this method exhausts all result sets and returns null.

This method should also invoke the delegate methods adaptorChannelWillFetchRow and adaptorChannelDidFetchRow. Should throw a runtime exception if an error occurs.

Specified by:

fetchRow in class EOAdaptorChannel

Returns:

Should return values for the receiver's attributesToFetch in a dictionary whose keys are the attribute names.

See Also:

EOAdaptorChannel.executeStoredProcedure(EOStoredProcedure storedProcedure, NSDictionary values), EOAdaptorChannel.selectAttributes(NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOAdaptorChannel.evaluateExpression(EOSQLExpression expression), EOAdaptorChannel.attributesToFetch(), (EOAdaptorChannel channel), EOAdaptorChannel.Delegate.adaptorChannelDidFinishFetching( EOAdaptorChannel channel), EOAdaptorChannel.Delegate.adaptorChannelWillFetchRow( EOAdaptorChannel channel), EOAdaptorChannel.Delegate.adaptorChannelDidFetchRow(EOAdaptorChannel channel , NSMutableDictionary row), EOAdaptorChannel.setAttributesToFetch(NSArray attributes)

generateExecuteStoredProcedureExpression

public NSDictionary generateExecuteStoredProcedureExpression(EOStoredProcedure storedProcedure,
                                                             NSDictionary values)

Invoked by executeStoredProcedure to parse the supplied text, usually from an EOModel, and generate a string for the expression and an NSArray of bindings for the values of the stored procedure's parameters.

Parameters:

storedProcedure - The stored procedure to execute.

values - A dictionary whose keys are the argument names and whose values are the argument values to be passed to storedProcedure.

Returns:

Should return a dictionary of the stored procedure's expression and an NSArray of the bindings.

Throws:

IllegalArgumentException - if the expression does not parse correctly

insertRow

public void insertRow(NSDictionary row,
                      EOEntity entity)

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to insert the values of row into the table in the database that corresponds to entity. row is a dictionary whose keys are attribute names and whose values are the values to insert. Row keys must refer to attributes that all belong to entity and that are either non- flattened or all flattened through the same relationship path. Should throw a runtime exception on failure. Some possible reasons for failure are:

• The user logged in to the database doesn't have permission to insert a new row.
• The adaptor channel is in an invalid state (for example, fetching).
• The row fails to satisfy a constraint defined in the database server.

Specified by:

insertRow in class EOAdaptorChannel

Parameters:

row - An NSDictionary whose keys are attribute names and whose values are the values that will be inserted.

entity - The entity that corresponds to row.

See Also:

EOEntity

isFetchInProgress

public boolean isFetchInProgress()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to return true if the receiver is fetching, false otherwise. An adaptor channel is fetching if:

• It has successfully invoked selectAttributes.
• A stored procedure that returns rows has been successfully executed using executeStoredProcedure.
• An expression sent through evaluateExpression resulted in a select operation being performed.

An adaptor channel stops fetching when there are no more records to fetch or when cancelFetch is invoked.

Specified by:

isFetchInProgress in class EOAdaptorChannel

Returns:

Should return true if the receiver is fetching, else false.

See Also:

EOAdaptorChannel.fetchRow(), EOAdaptorChannel.evaluateExpression(EOSQLExpression expression), EOAdaptorChannel.selectAttributes(NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOAdaptorChannel.executeStoredProcedure(EOStoredProcedure storedProcedure, NSDictionary values)

isOpen

public boolean isOpen()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to return true if the channel has been opened with openChannel, false if not.

Specified by:

isOpen in class EOAdaptorChannel

Returns:

Should return true if the channel has been opened with openChannel().

See Also:

EOAdaptorChannel.openChannel(), EOAdaptorChannel.closeChannel()

openChannel

public void openChannel()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to put the channel, and both its context and adaptor, into a state where they are ready to perform database operations. Should throw a runtime exception if an error occurs.

Specified by:

openChannel in class EOAdaptorChannel

See Also:

EOAdaptorChannel.isOpen(), EOAdaptorChannel.closeChannel()

primaryKeyForNewRowWithEntity

public NSDictionary primaryKeyForNewRowWithEntity(EOEntity entity)

Overrides:

primaryKeyForNewRowWithEntity in class EOAdaptorChannel

See Also:

EOAdaptorChannel.primaryKeysForNewRowsWithEntity(int count, EOEntity entity)

primaryKeysForNewRowsWithEntity

public NSArray primaryKeysForNewRowsWithEntity(int count,
                                               EOEntity entity)

Description copied from class: EOAdaptorChannel

Returns an NSArray of primary key dictionaries for the number of new rows specified by count in the database table that corresponds to entity. The primary keys returned from this method are dictionaries whose keys are the primary key attribute names. For example, suppose you've got a table MOVIE with primary key MOVIE_ID, and the corresponding Movie entity's primary key attribute is movieID. In this scenario, each dictionary in the NSArray returned from this method has one entry whose key is movieID and whose value is the unique value to assign.

If the primary key is compound (made up of more than one attribute), the dictionary should contain an entry for each primary key attribute. Note, however, that the Enterprise Objects Frameworks adaptors don't handle compound primary keys; they return null if the primary key is compound.

Overrides:

primaryKeysForNewRowsWithEntity in class EOAdaptorChannel

Parameters:

count - The number of new rows for which to generate primary keys.

entity - The entity for which to assign primary keys.

Returns:

An array of dictionaries whose keys are the primary key attribute names, or null if the adaptor is unable to provide the primary key values.

See Also:

EOEntity

returnValuesForLastStoredProcedureInvocation

public NSDictionary returnValuesForLastStoredProcedureInvocation()

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to return values from the execution of a stored procedure. Used in conjunction with executeStoredProcedure. The dictionary returned by this method should have entries whose keys are the names of the stored procedure's parameters and whose values are the parameter values. The dictionary also should contain a special entry for the stored procedure's return value with the key "returnValue".

Should return an empty dictionary for stored procedures that have void return types. Should return null if the stored procedure has results to fetch. In this case, you must use fetchRow until there are no more results to fetch before the return value will be available.

Specified by:

returnValuesForLastStoredProcedureInvocation in class EOAdaptorChannel

Returns:

Should return a dictionary of the stored procedure's parameter names and values, and its return value.

See Also:

EOAdaptorChannel.executeStoredProcedure(EOStoredProcedure storedProcedure, NSDictionary values), EOAdaptorChannel.fetchRow(), EOStoredProcedure

rowsProcessedCount

public int rowsProcessedCount()

selectAttributes

public void selectAttributes(NSArray attributes,
                             EOFetchSpecification fetchSpec,
                             boolean yn,
                             EOEntity entity)

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to select attributes in rows matching the qualifier in fetchSpecification and set the receiver's attributes to fetch. The selected rows compose one or more result sets, each row of which should be returned by subsequent fetchRow calls according to fetchSpecification's sort orderings. If the yn flag is true, the rows should be locked if possible so that no other user can modify them. The lock specification in fetchSpecification should be ignored. Should throw a runtime exception if an error occurs. Some possible reasons for failure are:

• The adaptor channel is in an invalid state (for example, fetching).
• The database failed to lock the specified rows.

Specified by:

selectAttributes in class EOAdaptorChannel

Parameters:

attributes - An array of the attributes to select.

fetchSpec - Describes the row(s) to select.

yn - true if rows should be locked.

entity - The entity corresponding to the row(s) to be selected.

See Also:

EOAdaptorChannel.fetchRow(), EOEntity, EOFetchSpecification, EOSortOrdering

setAttributesToFetch

public void setAttributesToFetch(NSArray attributes)

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to specify the set of attributes used to describe fetch data from a corresponding select. attribute is an array of the attributes to fetch. This method should be invoked after evaluateExpression but before the first call to fetchRow. This method should throw a runtime exception if invoked when there is no fetch in progress.

Specified by:

setAttributesToFetch in class EOAdaptorChannel

Parameters:

attributes - An array of the attributes to fetch.

See Also:

EOAdaptorChannel.selectAttributes( NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOAdaptorChannel.evaluateExpression(EOSQLExpression expression), EOAdaptorChannel.fetchRow()

updateValuesInRowsDescribedByQualifier

public int updateValuesInRowsDescribedByQualifier(NSDictionary row,
                                                  EOQualifier qualifier,
                                                  EOEntity entity)

Description copied from class: EOAdaptorChannel

An abstract method that should be implemented by subclasses to update the rows described by qualifier with the values in row. row is a dictionary whose keys are attribute names and whose values are the new values for those attributes (the dictionary need only contain entries for the attributes being changed). Should return the number of updated rows. Should throw a runtime exception if an error occurs. Some possible reasons for failure are:

• The user logged in to the database doesn't have permission to update.
• The adaptor channel is in an invalid state (for example, fetching).
• The new values fail to satisfy a constraint defined in the database server.

Specified by:

updateValuesInRowsDescribedByQualifier in class EOAdaptorChannel

Parameters:

row - The new values for row(s).

qualifier - Describes row(s) to update.

entity - The entity corresponding to the row(s) to update.

Returns:

Should return the number of updated rows.

See Also:

(NSDictionary row, EOQualifier qualifier, EOEntity entity), EOEntity, EOQualifier