Class powersoft.jcm.db.Query
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class powersoft.jcm.db.Query

java.lang.Object
   |
   +----powersoft.jcm.db.DataSourceBase
           |
           +----powersoft.jcm.db.Query

public class Query
extends DataSourceBase
Query is a proxy class for the real query driver class that actually handles the query operations. The real query classes are subclasses of the Query class.

Notes: JDBCQuery is the only subclass of Query.

See Also:
Transaction, DataSource

Constructor Index

 o Query()

Method Index

 o add(boolean, boolean)
Prepares to add a new row to the data source.
 o cancelUpdate(boolean)
Cancels a pending update or add operation.

Notes: Use this method to abort an update or add operation.

 o close()
Closes the query object, if it is open.
 o create(Transaction)
Associates the query object with the specified transaction object.
 o delete(boolean, boolean)
Deletes the current row.
 o destroy()
Closes the query object, destroys its association with its transaction object.
 o edit()
Prepares to edit the current row.
 o execute(String)
Executes the specified SQL statement.
 o getAutoEdit()
 o getAutoPrepare()
Determines whether the SQL statement is to be prepared when the query object is opened.
 o getAutoRefresh()
 o getBOF()
 o getColumn(int)
 o getColumnCount()
 o getColumnIndex(String)
 o getCurrentOffset()
 o getEditMode()
returns one of READ_MODE, EDIT_MODE, ADD_MODE
 o getEOF()
 o getForwardOnly()
Tests whether the query object supports only forward movement but no backward movements.
 o getOpened()
Tests whether a result set is opened.
 o getParameter(int)
 o getPrimaryKeyColumn()
Gets the name of the primary key column set by #setPrimaryKeyColumn.
 o getReadOnly()
 o getResultSetMetaDataObject()
Gets the java.sql.ResultSetMetaData object of the internal java.sql.ResultSet object used by this Query object.
 o getRowChanged()
 o getSQL()
 o getTraceToLog()
Notes: property ignored in release target
 o getTransactionObject()
Gets the transaction Object that the query obejct is associated with.
 o getValue(int)
 o getValue(int, byte)
 o isFirstRow()
 o isLastRow()
 o log(String, Object)
 o log(Throwable, Object)
 o move(int, byte, boolean, boolean)
Moves the cursor to the specified row in the result set.
 o open()
Executes the SQL statement associated with the query object.

Notes: You can check on the status of the result set using the ColumnCount property.

 o prepare()
Prepares (pre-processes) the query object's SQL statement for submission.
 o refresh()
Refreshes the currently held row(s) from the result set by refetching them.

Notes: If the cursor cannot be moved to the current row (the row may have been deleted), the cursor is moved to the first row of the result set.

The query object's bound controls will be refreshed if the move was successful.

 o resubmit()
Resubmits a query containing bound parameters.
 o setAutoEdit(boolean)
 o setAutoPrepare(boolean)
Determines whether the SQL statement is to be prepared when the query object is opened.
 o setAutoRefresh(boolean)
 o setParameter(int, DataValue)
 o setPrimaryKeyColumn(String)
Sets the name of the primary key column in the SQL statement if any.
 o setRowChanged(boolean)
 o setSQL(String)
 o setTraceToLog(boolean)
Notes: property ignored in release target
 o setTransactionObject(Transaction)
Specifies the transaction object that the query object is associated with.

Notes: A query object can be associated with one and only one transaction object.

 o setValue(int, DataValue)
 o update(boolean, boolean)
Updates the data source.

Constructors

 o Query
  public Query()

Methods

 o add
  public boolean add(boolean copyValue,
                     boolean append)
Prepares to add a new row to the data source.

Notes: This method attempts to set the EditMode to ADD_MODE. If it is successful, you will need to use the Value property to set the values of the new row and the Update method to actually add the new row to the data source.

Parameters:
copyValues - If true, the current row's values are copied to the new row. If false, the new row remains empty until you use the Value property to set its values.
append - If true, the new row is added to the end of the result set. If false, the new row is inserted immediately following the current row.
Returns:
true if the EditMode is successfully set to or is already set to ADD; false if EditMode is EDIT or the ReadOnly property is true.
Overrides:
add in class DataSourceBase
 o cancelUpdate
  public boolean cancelUpdate(boolean notify)
Cancels a pending update or add operation.

Notes: Use this method to abort an update or add operation. This property sets the EditMode to WDSEditModeRead.

Parameters:
notify - if true, bound controls are notified that a pending update or add operation has been canceled by triggering their DataAvailable events. If false, the bound controls are not notified.
Returns:
true is the pending operation was successfully cancelled. false if the EditMode was already READ_MODE.
Overrides:
cancelUpdate in class DataSourceBase
 o close
  public boolean close()
Closes the query object, if it is open.
Returns:
true if the query object already closed or was successfully closed; false otherwise.
Overrides:
close in class DataSourceBase
 o create
  public boolean create(Transaction trans)
Associates the query object with the specified transaction object.
Returns:
true if the query object was successfully associated with the specified transaction object.
Throws: IllegalArgumentException
if trans is not a JDBCTransaction
Throws: InvalidStateException
if the query object is already associated with a transaction object or has been created
 o delete
  public boolean delete(boolean validate,
                        boolean notify)
Deletes the current row.
Parameters:
validate - If true, a ValidateDataEvent is triggered on the query object before performing the deletion. If false, this event is not triggered.
notify - If true, bound controls are notified that a row has been deleted by triggering their DataAvailable events. If false, the bound controls are not notified.
Returns:
true if the row was successfully deleted; false if the row could not be deleted, the query is closed, the PrimaryKey property has not been set, the data source is empty, the EditMode property is not in READ_MODE, or either BOF or EOF is true.
Overrides:
delete in class DataSourceBase
 o destroy
  public boolean destroy()
Closes the query object, destroys its association with its transaction object.
Returns:
true if the operation was successful; false otherwise.
 o edit
  public boolean edit()
Prepares to edit the current row.
Returns:
true if EditMode is successfully set to or is already set to EDIT_MODE. false if EditMode is ADD_MODE, or if any one of the ReadOnly, BOF, or EOF properties are true, or if the PrimaryKey property has not been set.
Overrides:
edit in class DataSourceBase
 o execute
  public boolean execute(String str)
Executes the specified SQL statement. This statement must not generate a result set.

Notes: Use this method for any statement other than SELECT. The submitted statement must not generate a result set and will not be prepared prior to execution.

If the query object is open, it will be closed prior to executing the statement.

If 'str' is the null string, this method executes the string given by the query's SQL property.

Parameters:
str - The SQL statement to be executed.
Returns:
true if the statement was successfully excecuted, false otherwise.
 o move
  public boolean move(int row,
                      byte moveType,
                      boolean validate,
                      boolean notify)
Moves the cursor to the specified row in the result set. This row becomes the current row.

Notes: The data in the row can be accessed using the Value properties and through the bound controls.

Parameters:
row - Specifies the index of the row to move to. This parameter applies only when moveType is Absolute or Relative. See the description of the type parameter below.
moveType - Specifies the location of the row relative to either the current row or the result set. Use one of the constants in the MoveType interface.
validate - %%%
notify - If true, bound controls are notified that a move has occurred via their DataAvailable events. If false, no notifications are issued.
Returns:
true if the cursor was successfully moved; false otherwise.
Overrides:
move in class DataSourceBase
 o open
  public boolean open()
Executes the SQL statement associated with the query object.

Notes: You can check on the status of the result set using the ColumnCount property. If it is greater than 0, a result set containing 0 or more rows was generated. If the ColumnCount property is 0, no result set was generated.

Returns:
true if the statement was successfully executed; false otherwise.
Overrides:
open in class DataSourceBase
 o prepare
  public boolean prepare()
Prepares (pre-processes) the query object's SQL statement for submission.

Notes: If the query is open, it will be closed before submitting the statement for preparation.

Preparing a statement is only beneficial if the statement will be used more that once. You can change parameter values between statement executions.

A statement is prepared by having the data source compile the statement and prepare an access plan for it. This step is then not required the next time the statement is executed.

You can use the AutoPrepare property to determine whether statements are automatically prepared when opened.

Returns:
true if the statement is successfully prepared; false otherwise.
See Also:
setAutoPrepare
 o refresh
  public boolean refresh()
Refreshes the currently held row(s) from the result set by refetching them.

Notes: If the cursor cannot be moved to the current row (the row may have been deleted), the cursor is moved to the first row of the result set.

The query object's bound controls will be refreshed if the move was successful. Refresh can therefore be used after an update to the database to ensure that current values are displayed in the bound objects.

This method would be useful when the AutoRefresh property is set to false and you want to refresh the bound controls with intermediate results without changing AutoRefresh to true. Simply invoke the Refresh method to update the bound controls so that they reflect the changes made so far. Later, the AutoRefresh property can be set to true so that the bound controls are automatically updated.

Returns:
true if the cursor was successfully moved to the current row or, if that failed, to the first row of the result set; false otherwise.
Overrides:
refresh in class DataSourceBase
 o resubmit
  public boolean resubmit()
Resubmits a query containing bound parameters.

Notes: Resubmit is typically to used to resubmit a query after you have assigned new values to bound parameters. The action of Resubmit is similar to closing the query and then opening it again, but substantially faster.

Returns:
true if the query is successfully resubmitted; false otherwise.
 o update
  public boolean update(boolean validate,
                        boolean notify)
Updates the data source. Either updates the modified current row or adds a new row.
Parameters:
validate - If true, the ValidateDataEvent will be triggered. The ValidateDataEvent can be used to abort the update.
If - true, bound controls are notified that an update has occurred, via the DataAvailable event. If false, the bound controls are not notified.
Returns:
true if the row was successfully updated or did not need to be updated. false if EditMode is read-only or the ValidateData event handler cancelled the update.
Overrides:
update in class DataSourceBase
See Also:
ValidateDataEvent
 o isFirstRow
  public boolean isFirstRow()
Overrides:
isFirstRow in class DataSourceBase
 o isLastRow
  public boolean isLastRow()
Overrides:
isLastRow in class DataSourceBase
 o getSQL
  public String getSQL()
 o setSQL
  public void setSQL(String sql)
 o getAutoEdit
  public boolean getAutoEdit()
 o setAutoEdit
  public void setAutoEdit(boolean autoEdit)
 o getAutoPrepare
  public boolean getAutoPrepare()
Determines whether the SQL statement is to be prepared when the query object is opened.
 o setAutoPrepare
  public void setAutoPrepare(boolean autoPrepare)
Determines whether the SQL statement is to be prepared when the query object is opened.

Notes: If the property is false and you want the statement to be prepared prior to execution, you will need to invoke the #prepare method manually.

Parameters:
autoPrepare - If true and the statement has not already been prepared, the statement will be prepared when the query object is opened. If false, the statement will not be prepared automatically.
See Also:
prepare, open
 o getAutoRefresh
  public boolean getAutoRefresh()
 o setAutoRefresh
  public void setAutoRefresh(boolean autoRefresh)
 o getBOF
  public boolean getBOF()
Overrides:
getBOF in class DataSourceBase
 o getColumn
  public DataColumn getColumn(int index)
Overrides:
getColumn in class DataSourceBase
 o getColumnCount
  public int getColumnCount()
Overrides:
getColumnCount in class DataSourceBase
 o getColumnIndex
  public int getColumnIndex(String str)
Overrides:
getColumnIndex in class DataSourceBase
 o getCurrentOffset
  public int getCurrentOffset()
Overrides:
getCurrentOffset in class DataSourceBase
 o getEditMode
  public byte getEditMode()
returns one of READ_MODE, EDIT_MODE, ADD_MODE
Overrides:
getEditMode in class DataSourceBase
 o getEOF
  public boolean getEOF()
Overrides:
getEOF in class DataSourceBase
 o getForwardOnly
  public boolean getForwardOnly()
Tests whether the query object supports only forward movement but no backward movements.
Overrides:
getForwardOnly in class DataSourceBase
 o getOpened
  public boolean getOpened()
Tests whether a result set is opened.
Overrides:
getOpened in class DataSourceBase
 o getParameter
  public DataValue getParameter(int paramNum)
Parameters:
paramNum - The parameter number whose value you want to determine or set. Parameters are numbered beginning at 1 (for the first parameter in the query statement).
See Also:
DataValue
 o setParameter
  public void setParameter(int paramNum,
                           DataValue value)
Parameters:
paramNum - The parameter number whose value you want to determine or set. Parameters are numbered beginning at 1 (for the first parameter in the query statement).
val - The value you want to assign to the parameter.
See Also:
DataValue
 o getPrimaryKeyColumn
  public String getPrimaryKeyColumn()
Gets the name of the primary key column set by #setPrimaryKeyColumn.
Returns:
The name of the primary key column.
 o setPrimaryKeyColumn
  public void setPrimaryKeyColumn(String primaryKeys)
Sets the name of the primary key column in the SQL statement if any.

Notes: If this property is not set, this Query object cannot go into the Edit mode.

 o getReadOnly
  public boolean getReadOnly()
Overrides:
getReadOnly in class DataSourceBase
 o getResultSetMetaDataObject
  public ResultSetMetaData getResultSetMetaDataObject()
Gets the java.sql.ResultSetMetaData object of the internal java.sql.ResultSet object used by this Query object.
Returns:
The JDBC ResultSetMetaData object if a result set is opened; null if no result set is opened.
 o getRowChanged
  public boolean getRowChanged()
Overrides:
getRowChanged in class DataSourceBase
 o setRowChanged
  public void setRowChanged(boolean changed)
Overrides:
setRowChanged in class DataSourceBase
 o getTraceToLog
  public boolean getTraceToLog()
Notes: property ignored in release target
 o setTraceToLog
  public void setTraceToLog(boolean traceToLog)
Notes: property ignored in release target
 o getTransactionObject
  public Transaction getTransactionObject()
Gets the transaction Object that the query obejct is associated with.
See Also:
setTransactionObject
 o setTransactionObject
  public void setTransactionObject(Transaction trans)
Specifies the transaction object that the query object is associated with.

Notes: A query object can be associated with one and only one transaction object. If the query object is already associated with a transaction object that association is destroyed before the new association is made.

The query object's transaction object must be established before the query object is opened.

Parameters:
trans - The transaction object with which the query object is to be associated.
Throws: IllegalArgumentException
if trans is not derived from JDBCTransaction
 o getValue
  public DataValue getValue(int index)
Overrides:
getValue in class DataSourceBase
 o getValue
  public DataValue getValue(int index,
                            byte type)
Overrides:
getValue in class DataSourceBase
 o setValue
  public boolean setValue(int index,
                          DataValue val)
Overrides:
setValue in class DataSourceBase
 o log
  protected void log(String err,
                     Object obj)
Overrides:
log in class DataSourceBase
 o log
  protected void log(Throwable err,
                     Object obj)
Overrides:
log in class DataSourceBase

All Packages  Class Hierarchy  This Package  Previous  Next  Index