public interface Filter
A manner to restrict the set of values notified by a Subscription.
A filter may be used in a subscription to restrict (at the server level) the
set of entities that will be
notified
to the client application.
Context.makeFilter()
in which the filter
parameters are described by FilterParam
and the event listeners are
described by FilterListener
.
Once locally created a filter must be also server created, eventually server extended, used in the Subscription and then server destroyed.
Context.makeFilter()
,
FilterParam
,
FilterListener
Field Summary | |
---|---|
static int |
STATUS_CREATED
Lifecycle status: Filter created on the server and ready to be used. |
static int |
STATUS_CREATING
Lifecycle status: Filter waiting the create() server-answer. |
static int |
STATUS_DESTROYED
Lifecycle status: Filter destroyed into the server and ready to be released. |
static int |
STATUS_DESTROYING
Lifecycle status: Filter 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 filter on the server. |
int |
destroy()
Try to destroy this filter on the server. |
int |
set(String value)
Try to extend this filter on 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
.
onFilterCreate()
call.
STATUS_CREATING
→
onFilterCreate()
ok → STATUS_CREATED
. STATUS_CREATING
→
onFilterCreate()
bad → STATUS_DESTROYED
.
static final int STATUS_CREATED
LifeCycle.getStatus()
.
STATUS_CREATING
→
onFilterCreate()
ok → STATUS_CREATED
.
STATUS_CREATED
→ destroy()
ok →
STATUS_DESTROYING
.
static final int STATUS_DESTROYING
destroy()
server-answer. LifeCycle.getStatus()
.
STATUS_CREATED
→ destroy()
ok →
STATUS_DESTROYING
.
onFilterDestroy()
call.
STATUS_DESTROYING
→
onFilterDestroy()
→ STATUS_DESTROYED
.
static final int STATUS_DESTROYED
LifeCycle.getStatus()
.
It's always a good practice to release a Filter in this status.
STATUS_DESTROYING
→
onFilterDestroy()
→ 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
,
FilterListener.onFilterCreate()
will be automatically called to handle it.
otherwise
FilterListener.onFilterCreate()
will not be made,
In the latter case it is a good practice to release this Filter.
RESULT_OK
if the operation completed
successfully,
RESULT_INVALID_STATUS
if the
current status is not
STATUS_INIT
,
RESULT_INVALID_CONNECTION_STATUS
if the associated Connection
current status is not
Connection.STATUS_CONNECTED
,
RESULT_GENERIC_ERROR
otherwise.
int set(String value)
The filter extension is used to extend an already created filter.
The precise meaning of this value depends from the particular filter and, in general, it must be agreed between the client and the server.
The server may subsequently returns a
FilterSetEvent.RESULT_SYNTAX_ERROR
or a
FilterSetEvent.RESULT_INVALID_FILTER_LEN
failure-code if it does not understand this value or if this value is too
long.
This method must be called only when
STATUS_CREATED
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
FilterListener.onFilterSet()
will be automatically called to handle it.
otherwise
FilterListener.onFilterSet()
will not be made.
In any case the current status remains unchanged.
value
- filter extension of the new filter.
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.
the given filter value is null
or empty).
int destroy()
This method must be called only when
STATUS_CREATED
,
Connection.STATUS_CONNECTED
.
If this method invocation completed successfully,
then
STATUS_DESTROYING
,
FilterListener.onFilterDestroy()
will be automatically called to handle it.
otherwise
FilterListener.onFilterDestroy()
will not be made,
It's not a bad practice to unconditionally release this Filter 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.