it.list.jft
Interface Query

All Superinterfaces:
ActivityLifeCycle, CommunicationLifeCycle, LifeCycle

public interface Query
extends ActivityLifeCycle

A client's request to a server to obtain a set of entities (or rows) from its own Data Base.

An entire result-set (or a part of it, as eventually requested by queryRows(int, int)) is returned to the client application, one row at time.

Query Usage

A query is defined by: The precise meaning of the QueryID identifier must be agreed between the client and the server.
In brief:
Queries are locally created by Context.makeQuery() in which the query parameters are described by QueryParam and the event listeners are described by QueryListener.

Once locally created a query must be also server created, eventually result-set partitioned, used and then server destroyed.

Query Lifecycle

See Also:
Context.makeQuery(), QueryParam, QueryListener

Field Summary
static int STATUS_CREATED
          Lifecycle status: Query created on the server and ready to be used.
static int STATUS_CREATING
          Lifecycle status: Query waiting the create() server-answer.
static int STATUS_DESTROYED
          Lifecycle status: Query destroyed into the server and ready to be released.
static int STATUS_DESTROYING
          Lifecycle status: Query waiting the destroy() server-answer.
 
Fields inherited from interface ActivityLifeCycle
RESULT_INVALID_CONNECTION_STATUS
 
Fields inherited from interface LifeCycle
RESULT_GENERIC_ERROR, RESULT_INVALID_STATUS, RESULT_OK, STATUS_INIT, STATUS_RELEASED
 
Method Summary
 int create()
          Try to create this query on the server.
 int destroy()
          Try to destroy this query on the server.
 int queryRows(int firstRow, int rowNumber)
          Try to retrieve a subset of the result-set of this query from the server.
 
Methods inherited from interface ActivityLifeCycle
getConnection
 
Methods inherited from interface CommunicationLifeCycle
getContext, getListener, getParam
 
Methods inherited from interface LifeCycle
enumChilds, getStatus, release
 

Field Detail

STATUS_CREATING

static final int STATUS_CREATING
Lifecycle status: Query waiting the create() server-answer.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_INITcreate() ok → STATUS_CREATING.
Status Activities:
none: waiting an automatic onQueryCreate() call.
Status Exit:
STATUS_CREATINGonQueryCreate() ok → STATUS_CREATED.
STATUS_CREATINGonQueryCreate() bad → STATUS_DESTROYED.

See Also:
Query lifecycle, Constant Field Values

STATUS_CREATED

static final int STATUS_CREATED
Lifecycle status: Query created on the server and ready to be used.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_CREATINGonQueryCreate() ok → STATUS_CREATED.
Status Activities:
Status Exit:
STATUS_CREATEDdestroy() ok → STATUS_DESTROYING.

See Also:
Query lifecycle, Constant Field Values

STATUS_DESTROYING

static final int STATUS_DESTROYING
Lifecycle status: Query waiting the destroy() server-answer.
This value may be returned by LifeCycle.getStatus().

Status Entry:
STATUS_CREATEDdestroy() ok → STATUS_DESTROYING.
Status Activities:
none: waiting an automatic onQueryDestroy() call.
Status Exit:
STATUS_DESTROYINGonQueryDestroy()STATUS_DESTROYED.

See Also:
Query lifecycle, Constant Field Values

STATUS_DESTROYED

static final int STATUS_DESTROYED
Lifecycle status: Query destroyed into the server and ready to be released.
This value may be returned by LifeCycle.getStatus().

It's always a good practice to release a Query in this status.

Status Entry:
STATUS_DESTROYINGonQueryDestroy()STATUS_DESTROYED.
Status Activities:
LifeCycle.release().
Status Exit:
STATUS_DESTROYEDLifeCycle.release()STATUS_RELEASED.

See Also:
Query lifecycle, Constant Field Values
Method Detail

create

int create()
Try to create this query on the server.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

In the latter case it is a good practice to release this Query.

Returns:

queryRows

int queryRows(int firstRow,
              int rowNumber)
Try to retrieve a subset of the result-set of this query from the server.

The firstRow and rowNumber parameters describe the subset of result-set to be retrieved.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

In any case the current status remains unchanged.

Parameters:
firstRow - index (1-based) of the first row to be retrieved.
rowNumber - number of rows to be retrieved.
Returns:

destroy

int destroy()
Try to destroy this query on the server.

This method must be called only when

If this method invocation completed successfully,
then

otherwise

It's not a bad practice to unconditionally release this Query immediately after this method invocation without handling the returned value.

Returns:


Submit a bug or feature to FT\API Programming Support<\font>