public interface Query extends ActivityLifeCycle
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.
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.
Context.makeQuery()
,
QueryParam
,
QueryListener
Modifier and Type | Field and Description |
---|---|
static int |
STATUS_CREATED
Lifecycle status: Query created on the server
and ready to be used.
|
static int |
STATUS_CREATING
|
static int |
STATUS_DESTROYED
|
static int |
STATUS_DESTROYING
|
RESULT_INVALID_CONNECTION_STATUS
RESULT_GENERIC_ERROR, RESULT_INVALID_STATUS, RESULT_OK, STATUS_INIT, STATUS_RELEASED
Modifier and Type | Method and Description |
---|---|
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.
|
getConnection
getContext, getListener, getParam
enumChilds, getStatus, release
static final int STATUS_CREATING
create()
server-answer. LifeCycle.getStatus()
.
STATUS_INIT
→ create()
ok →
STATUS_CREATING
.
onQueryCreate()
call.
STATUS_CREATING
→
onQueryCreate()
ok
→ STATUS_CREATED
. STATUS_CREATING
→
onQueryCreate()
bad
→ STATUS_DESTROYED
.
static final int STATUS_CREATED
LifeCycle.getStatus()
.
STATUS_CREATING
→
onQueryCreate()
ok
→ STATUS_CREATED
.
onQueryNotify()
to
retrieve the result-set one row at time.
STATUS_CREATED
→ destroy()
ok →
STATUS_DESTROYING
.
static final int STATUS_DESTROYING
destroy()
server-answer. LifeCycle.getStatus()
.
STATUS_CREATED
→ destroy()
ok →
STATUS_DESTROYING
.
onQueryDestroy()
call.
STATUS_DESTROYING
→
onQueryDestroy()
→ STATUS_DESTROYED
.
static final int STATUS_DESTROYED
LifeCycle.getStatus()
.
It's always a good practice to release a Query in this status.
STATUS_DESTROYING
→
onQueryDestroy()
→ STATUS_DESTROYED
.
LifeCycle.release()
.
STATUS_DESTROYED
→ LifeCycle.release()
→
STATUS_RELEASED
.
int create()
This method must be called only when
STATUS_INIT
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
STATUS_CREATING
,
QueryListener.onQueryCreate()
will be automatically called to handle it.
otherwise
QueryListener.onQueryCreate()
will not be made,
In the latter case it is a good practice to release this Query.
RESULT_OK
if the operation completed
successfully,
RESULT_INVALID_STATUS
if the
current status is not
STATUS_INIT
,
ActivityLifeCycle.RESULT_INVALID_CONNECTION_STATUS
if the
associated Connection
current status is not
Connection.STATUS_CONNECTED
,
RESULT_GENERIC_ERROR
otherwise.
int queryRows(int firstRow, int rowNumber)
The firstRow
and rowNumber
parameters
describe the subset of result-set to be retrieved.
This method must be called only when
STATUS_CREATED
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
QueryListener.onQueryRows()
will be automatically called to handle it.
otherwise
QueryListener.onQueryRows()
will not be made.
In any case the current status remains unchanged.
firstRow
- index (1-based) of the first row to be retrieved.rowNumber
- number of rows to be retrieved.RESULT_OK
if the operation completed
successfully,
RESULT_INVALID_STATUS
if
the current status is not
STATUS_CREATED
,
RESULT_INVALID_CONNECTION_STATUS
if the associated Connection
current status is not
Connection.STATUS_CONNECTED
,
RESULT_GENERIC_ERROR
otherwise (e.g. firstRow
<= 0 or
rowNumber <= 0
).
int destroy()
This method must be called only when
STATUS_CREATED
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
STATUS_DESTROYING
,
QueryListener.onQueryDestroy()
will be automatically called to handle it.
otherwise
QueryListener.onQueryDestroy()
will not be made,
It's not a bad practice to unconditionally release this Query immediately after this method invocation without handling the returned value.
RESULT_OK
if the operation completed
successfully,
RESULT_INVALID_STATUS
if the
current status is not STATUS_CREATED
,
RESULT_INVALID_CONNECTION_STATUS
if the associated Connection
current status is not
Connection.STATUS_CONNECTED
,
RESULT_GENERIC_ERROR
otherwise.
Submit a bug or feature to FT\API Programming Support