Module org.eclipse.persistence.core
Package org.eclipse.persistence.internal.databaseaccess

Class DatabaseCall

java.lang.Object
org.eclipse.persistence.internal.databaseaccess.DatasourceCall
org.eclipse.persistence.internal.databaseaccess.DatabaseCall
All Implemented Interfaces:
Serializable, Cloneable, Call
Direct Known Subclasses:
SQLCall, StoredProcedureCall
public abstract class DatabaseCall extends DatasourceCall
INTERNAL: Purpose: Used as an abstraction of a database invocation. A call is an SQL string or procedure call with parameters.
See Also:

  • Field Details

    • executeReturnValue

      protected boolean executeReturnValue
      JPA 2.1 NamedStoredProcedureQuery execute API implementation.

    • MAXROW_FIELD

      public static final DatabaseField MAXROW_FIELD
      Following fields are used to bind MaxResults and FirstRow settings into the query instead of using the values stored in the call.

    • FIRSTRESULT_FIELD

      public static final DatabaseField FIRSTRESULT_FIELD

    • ignoreFirstRowSetting

      protected boolean ignoreFirstRowSetting
      Indicates if the FirstRow value in this call object is to be ignored. If true, it should mean it has been built into the SQL statement directly ex: using Oracle Rownum support

    • ignoreMaxResultsSetting

      protected boolean ignoreMaxResultsSetting
      Indicates if the MaxResults value in this call object is to be ignored. If true, it should mean it has been built into the SQL statement directly ex: using Oracle Rownum support

    • statement

      protected transient Statement statement

    • result

      protected transient ResultSet result

    • generatedKeys

      protected transient ResultSet generatedKeys

    • usesBinding

      protected Boolean usesBinding

    • shouldCacheStatement

      protected Boolean shouldCacheStatement

    • shouldReturnGeneratedKeys

      protected boolean shouldReturnGeneratedKeys

    • fields

      protected transient Vector<DatabaseField> fields

    • fieldsArray

      protected transient DatabaseField[] fieldsArray

    • isFieldMatchingRequired

      protected boolean isFieldMatchingRequired

    • hasOptimisticLock

      protected boolean hasOptimisticLock

    • isResultSetScrollable

      protected boolean isResultSetScrollable

    • resultSetFetchSize

      protected int resultSetFetchSize

    • resultSetType

      protected int resultSetType

    • resultSetConcurrency

      protected int resultSetConcurrency

    • queryTimeout

      protected int queryTimeout

    • queryTimeoutUnit

      protected TimeUnit queryTimeoutUnit

    • maxRows

      protected int maxRows

    • firstResult

      protected int firstResult

    • isCursorOutputProcedure

      protected boolean isCursorOutputProcedure
      Allow for a single cursored output parameter.

    • isMultipleCursorOutputProcedure

      protected boolean isMultipleCursorOutputProcedure
      Allow for multiple cursored output parameter.

    • returnsResultSet

      protected Boolean returnsResultSet

    • shouldBuildOutputRow

      protected boolean shouldBuildOutputRow

    • isCallableStatementRequired

      protected boolean isCallableStatementRequired

    • hasMultipleResultSets

      protected boolean hasMultipleResultSets
      Support multiple result sets.

    • returnMultipleResultSetCollections

      protected boolean returnMultipleResultSetCollections
      Support returning multiple results sets instead of just one list, i.e. support multiple results set mappings.

    • sqlString

      protected String sqlString
      The SQL string to execute.

    • hasAllocatedConnection

      protected boolean hasAllocatedConnection
      Indicates whether the call has allocated connection. May be set if the call has not finished

    • isBatchExecutionSupported

      protected boolean isBatchExecutionSupported
      Define if this query is compatible with batch writing. Some queries, such as DDL are not compatible.

  • Constructor Details

    • DatabaseCall

      protected DatabaseCall()

  • Method Details

    • hasMultipleResultSets

      public boolean hasMultipleResultSets()
      Return if the call returns multiple result sets.

    • setHasMultipleResultSets

      public void setHasMultipleResultSets(boolean hasMultipleResultSets)
      Set if the call returns multiple result sets.

    • appendParameter

      public void appendParameter(Writer writer, Object parameter, boolean shouldBind, AbstractSession session)
      Add the parameter.

      If binding is enabled, then bind the parameter; otherwise let the platform print it. The platform may also decide to bind the value.

      Overrides:
      appendParameter in class DatasourceCall

    • bindParameter

      public void bindParameter(Writer writer, Object parameter)
      Bind the parameter. Binding is determined by the parameter and second the platform.

    • buildNewQueryMechanism

      public DatabaseQueryMechanism buildNewQueryMechanism(DatabaseQuery query)
      Return the appropriate mechanism, with the call added as necessary.
      Specified by:
      buildNewQueryMechanism in interface Call
      Overrides:
      buildNewQueryMechanism in class DatasourceCall

    • buildOutputRow

      public AbstractRecord buildOutputRow(CallableStatement statement, DatabaseAccessor accessor, AbstractSession session) throws SQLException
      INTERNAL: Return Record containing output fields and values. Called only if shouldBuildOutputRow method returns true.
      Throws:
      SQLException

    • buildQueryMechanism

      public DatabaseQueryMechanism buildQueryMechanism(DatabaseQuery query, DatabaseQueryMechanism mechanism)
      Return the appropriate mechanism, with the call added as necessary.
      Specified by:
      buildQueryMechanism in interface Call
      Overrides:
      buildQueryMechanism in class DatasourceCall

    • createInOutParameter

      protected Object createInOutParameter(Object inValue, Object outParameter, AbstractSession session)
      INTERNAL: Returns INOUT parameter. The first parameter is value to pass in, the second DatabaseField for out.
      Overrides:
      createInOutParameter in class DatasourceCall

    • getCallString

      public String getCallString()
      INTERNAL: Return the SQL string for the call.

    • getFields

      public Vector<DatabaseField> getFields()
      The fields expected by the calls result set. null means that the fields are unknown and should be built from the result set.

    • getFieldsArray

      public DatabaseField[] getFieldsArray()
      INTERNAL: The array of fields returned by the call.

    • getFieldWithTypeFromDescriptor

      protected DatabaseField getFieldWithTypeFromDescriptor(DatabaseField outField)
      INTERNAL: Unfortunately can't avoid referencing query and descriptor: the call should be performed after the translateCustomSQL (in SQLCall) in the middle of prepare method (no parameter available earlier).

    • getCursorOutIndex

      public int getCursorOutIndex()
      INTERNAL: Return 1-based index of out cursor parameter, or -1.

    • getExecuteReturnValue

      public boolean getExecuteReturnValue()
      After an execute call the return value can be retrieved here.

    • getFirstResult

      public int getFirstResult()
      get first result

    • getLogString

      public String getLogString(Accessor accessor)
      Return the SQL string for logging purposes.
      Specified by:
      getLogString in interface Call
      Specified by:
      getLogString in class DatasourceCall

    • appendLogParameters

      public static void appendLogParameters(Collection parameters, Accessor accessor, StringWriter writer, AbstractSession session)
      Print the parameters to the write for logging purposes.

    • getMaxRows

      public int getMaxRows()
      get max rows returned from the call

    • getOutputRowFields

      public Vector getOutputRowFields()
      INTERNAL Returns the fields to be used in output row.

    • getQueryString

      public String getQueryString()
      INTERNAL: Return the query string (SQL) of the call.
      Overrides:
      getQueryString in class DatasourceCall

    • getQueryTimeout

      public int getQueryTimeout()
      Get timeout limit from the call

    • getGeneratedKeys

      public ResultSet getGeneratedKeys()
      The result set that stores the generated keys from the Statement

    • getResult

      public ResultSet getResult()
      The result set is stored for the return value of cursor selects.

    • getReturnsResultSet

      public boolean getReturnsResultSet()
      ADVANCED: This method returns a value that represents if the customer has set whether or not EclipseLink should expect the stored procedure to returning a JDBC ResultSet. The result of the method corresponds to false, true.

    • getResultSetConcurrency

      public int getResultSetConcurrency()

    • getResultSetFetchSize

      public int getResultSetFetchSize()

    • getResultSetType

      public int getResultSetType()

    • getSQLString

      public String getSQLString()
      Return the SQL string that will be executed.

    • getStatement

      public Statement getStatement()
      The statement is stored for the return value of cursor selects.

    • hasOptimisticLock

      public boolean hasOptimisticLock()
      This check is needed only when doing batch writing.

    • isCallableStatementRequired

      protected boolean isCallableStatementRequired()
      Callable statement is required if there is an output parameter.

    • isDynamicCall

      protected boolean isDynamicCall(AbstractSession session)
      Return if the call is dynamic SQL call. This means the call has no parameters, is not using binding, is not a stored procedure (CallableStatement), or cursor. This means that a Statement, not a PreparedStatement will be used for the call.

    • isCursorOutputProcedure

      public boolean isCursorOutputProcedure()
      Used for Oracle result sets through procedures.

    • isCursorReturned

      public boolean isCursorReturned()
      The return type is one of, NoReturn, ReturnOneRow or ReturnManyRows.
      Overrides:
      isCursorReturned in class DatasourceCall

    • isFieldMatchingRequired

      public boolean isFieldMatchingRequired()
      Return if field matching is required. Field matching is required for custom SQL statements where the result set field order is not known.

    • isFinished

      public boolean isFinished()
      Return whether all the results of the call have been returned.
      Specified by:
      isFinished in interface Call
      Overrides:
      isFinished in class DatasourceCall

    • isMultipleCursorOutputProcedure

      public boolean isMultipleCursorOutputProcedure()
      Used for Oracle result sets through procedures.

    • isNonCursorOutputProcedure

      public boolean isNonCursorOutputProcedure()
      Return true for procedures with any output (or in/out) parameters and no cursors

    • isResultSetScrollable

      public boolean isResultSetScrollable()

    • matchFieldOrder

      public void matchFieldOrder(ResultSet resultSet, DatabaseAccessor accessor, AbstractSession session)
      Allow for the field order to be matched if required. This is required for custom SQL.

    • prepare

      public void prepare(AbstractSession session)
      INTERNAL: Allow pre-printing of the SQL string for fully bound calls, to save from reprinting. Should be called before translation.
      Overrides:
      prepare in class DatasourceCall

    • prepareInternal

      protected void prepareInternal(AbstractSession session)
      INTERNAL: Called by prepare method only. May be overridden.

    • prepareInternalParameters

      protected void prepareInternalParameters(AbstractSession session)
      INTERNAL: Called by prepareInternal method only. May be overridden.

    • prepareStatement

      public Statement prepareStatement(DatabaseAccessor accessor, AbstractRecord translationRow, AbstractSession session) throws SQLException
      INTERNAL: Prepare the JDBC statement, this may be parameterize or a call statement. If caching statements this must check for the pre-prepared statement and re-bind to it.
      Throws:
      SQLException

    • returnMultipleResultSetCollections

      public boolean returnMultipleResultSetCollections()
      Return true if the multiple results 'lists' should be returned.

    • setFields

      public void setFields(Vector<DatabaseField> fields)
      The fields expected by the calls result set.

    • setFirstResult

      public void setFirstResult(int firstResult)
      The firstResult set on the result set

    • setHasOptimisticLock

      public void setHasOptimisticLock(boolean hasOptimisticLock)
      This check is needed only when doing batch writing and we hit on optimistic locking.

    • setIgnoreFirstRowSetting

      public void setIgnoreFirstRowSetting(boolean ignoreFirstRowSetting)
      INTERNAL: Sets the ignoreFirstRowSetting flag. If true, FirstResult option are assumed built into the SQL string and ignored if set in the call, and instead are added as query arguments. Default is false.

    • setIgnoreMaxResultsSetting

      public void setIgnoreMaxResultsSetting(boolean ignoreMaxResultsSetting)
      INTERNAL: Sets the ignoreMaxResultsSetting flag. If true, MaxRows option are assumed built into the SQL string and ignored if set in the call, and instead are added as query arguments. Default is false.

    • setShouldReturnGeneratedKeys

      public boolean setShouldReturnGeneratedKeys(boolean shouldReturnGeneratedKeys)
      Indicate that this call should set Statement.RETURN_GENERATED_KEYS when executing

      Only set to true if DatasourcePlatform.supportsReturnGeneratedKeys()

    • setIsCallableStatementRequired

      protected void setIsCallableStatementRequired(boolean isCallableStatementRequired)
      Callable statement is required if there is an output parameter.

    • setIsCursorOutputProcedure

      public void setIsCursorOutputProcedure(boolean isCursorOutputProcedure)
      Used for Oracle result sets through procedures.

    • setIsFieldMatchingRequired

      public void setIsFieldMatchingRequired(boolean isFieldMatchingRequired)
      Field matching is required for custom SQL statements where the result set field order is not known.

    • setIsMultipleCursorOutputProcedure

      public void setIsMultipleCursorOutputProcedure(boolean isMultipleCursorOutputProcedure)
      Used for Oracle result sets through procedures.

    • setIsResultSetScrollable

      public void setIsResultSetScrollable(boolean isResultSetScrollable)

    • setMaxRows

      public void setMaxRows(int maxRows)
      set query max returned row size to the JDBC Statement

    • setQueryString

      public void setQueryString(String queryString)
      INTERNAL: Set the query string (SQL) of the call.
      Overrides:
      setQueryString in class DatasourceCall

    • setQueryTimeout

      public void setQueryTimeout(int queryTimeout)
      set query timeout limit to the JDBC Statement

    • setQueryTimeoutUnit

      public void setQueryTimeoutUnit(TimeUnit queryTimeoutUnit)
      set query timeout limit unit to the JDBC Statement

    • setGeneratedKeys

      public void setGeneratedKeys(ResultSet generatedKeys)
      The result set that stores the generated keys from the Statement

    • setResult

      public void setResult(ResultSet result)
      The result set is stored for the return value of cursor selects.

    • setResultSetConcurrency

      public void setResultSetConcurrency(int resultSetConcurrency)

    • setSQLStringInternal

      protected void setSQLStringInternal(String sqlString)
      INTERNAL: Set the SQL string.

    • setResultSetFetchSize

      public void setResultSetFetchSize(int resultSetFetchSize)

    • setResultSetType

      public void setResultSetType(int resultSetType)

    • setReturnsResultSet

      public void setReturnsResultSet(boolean returnsResultSet)
      PUBLIC: Use this method to tell EclipseLink that the stored procedure will be returning a JDBC ResultSet

    • setReturnMultipleResultSetCollections

      public void setReturnMultipleResultSetCollections(boolean returnMultipleResultSetCollections)
      Set if the call returns multiple result sets.

    • setShouldBuildOutputRow

      protected void setShouldBuildOutputRow(boolean shouldBuildOutputRow)
      INTERNAL: Set whether the call has to build output row

    • setShouldCacheStatement

      public void setShouldCacheStatement(boolean shouldCacheStatement)
      Bound calls can use prepared statement caching.

    • setStatement

      public void setStatement(Statement statement)
      The statement is stored for the return value of cursor selects.

    • shouldBuildOutputRow

      public boolean shouldBuildOutputRow()
      Set whether the call has to build output row

    • shouldCacheStatement

      public boolean shouldCacheStatement(AbstractSession session)
      Bound calls can use prepared statement caching.

    • shouldCacheStatement

      public boolean shouldCacheStatement(DatabasePlatform databasePlatform)
      Bound calls can use prepared statement caching.

    • shouldIgnoreFirstRowSetting

      public boolean shouldIgnoreFirstRowSetting()
      INTERNAL: Returns the ignoreFirstRowSetting flag. If true, FirstResult option is assumed built into the SQL string and ignored if set in the call.

    • shouldIgnoreMaxResultsSetting

      public boolean shouldIgnoreMaxResultsSetting()
      INTERNAL: Returns the ignoreMaxResultsSetting flag. If true, MaxRows option is assumed built into the SQL string and ignored if set in the call.

    • shouldReturnGeneratedKeys

      public boolean shouldReturnGeneratedKeys()
      Indicate that this call should set Statement.RETURN_GENERATED_KEYS when executing

    • toString

      public String toString()
      INTERNAL: Print the SQL string.
      Overrides:
      toString in class Object

    • translate

      public void translate(AbstractRecord translationRow, AbstractRecord modifyRow, AbstractSession session)
      INTERNAL: Allow the call to translate from the translation for predefined calls.
      Overrides:
      translate in class DatasourceCall

    • isLOBLocatorNeeded

      public boolean isLOBLocatorNeeded()
      INTERNAL: Return if the locator is required for the LOB (BLOB and CLOB) writing.

    • addContext

      public void addContext(DatabaseField field, Object value)
      INTERNAL: Add a field - value pair for LOB field into the context.

    • getContexts

      public AbstractRecord getContexts()
      INTERNAL: Return the contexts (for LOB)

    • setContexts

      public void setContexts(AbstractRecord contexts)
      INTERNAL: Set the contexts (for LOB)

    • setExecuteReturnValue

      public void setExecuteReturnValue(boolean value)
      An execute return value will be set here after the call.

    • useUnnamedCursorOutputAsResultSet

      public void useUnnamedCursorOutputAsResultSet()
      PUBLIC: Used for Oracle result sets through procedures. The first OUT parameter is set as a cursor output.

    • isBatchExecutionSupported

      public boolean isBatchExecutionSupported()
      INTERNAL: Return if this query is compatible with batch writing. Some queries, such as DDL are not compatible.

    • setBatchExecutionSupported

      public void setBatchExecutionSupported(boolean isBatchExecutionSupported)
      INTERNAL: Set if this query is compatible with batch writing. Some queries, such as DDL are not compatible.

    • hasAllocatedConnection

      public boolean hasAllocatedConnection()
      INTERNAL:

    • setHasAllocatedConnection

      public void setHasAllocatedConnection(boolean hasAllocatedConnection)
      INTERNAL:

    • getOutputParameterValue

      public Object getOutputParameterValue(CallableStatement statement, int index, AbstractSession session) throws SQLException
      INTERNAL: Get the return object from the statement. Use the parameter index to determine what return object to get.
      Parameters:
      statement - SQL/JDBC statement to call stored procedure/function
      index - 0-based index in the argument list
      session - Active database session (in connected state).
      Throws:
      SQLException

    • getOutputParameterValue

      public Object getOutputParameterValue(CallableStatement statement, String name, AbstractSession session) throws SQLException
      INTERNAL: Get the return object from the statement. Use the parameter name to determine what return object to get.
      Parameters:
      statement - SQL/JDBC statement to call stored procedure/function
      name - parameter name
      session - Active database session (in connected state).
      Throws:
      SQLException