public interface Query
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.
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
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 |
---|
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
.
Method Detail |
---|
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.