it.list.jft
Interface Filter

All Superinterfaces:
ActivityLifeCycle, CommunicationLifeCycle, LifeCycle
All Known Subinterfaces:
EntityFilter

public interface Filter
extends ActivityLifeCycle

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.

Filter Usage

A filter is defined by: The precise meaning of these 4 things depends from the particular filter and, in general, must be agreed between the client and the server.
In brief:
Filters are locally created by 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.

Filter Lifecycle

See Also:
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

STATUS_CREATING

static final int STATUS_CREATING
Lifecycle status: Filter 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 onFilterCreate() call.
Status Exit:
STATUS_CREATINGonFilterCreate() ok → STATUS_CREATED.
STATUS_CREATINGonFilterCreate() bad → STATUS_DESTROYED.

See Also:
Filter lifecycle, Constant Field Values

STATUS_CREATED

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

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

See Also:
Filter lifecycle, Constant Field Values

STATUS_DESTROYING

static final int STATUS_DESTROYING
Lifecycle status: Filter 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 onFilterDestroy() call.
Status Exit:
STATUS_DESTROYINGonFilterDestroy()STATUS_DESTROYED.

See Also:
Filter lifecycle, Constant Field Values

STATUS_DESTROYED

static final int STATUS_DESTROYED
Lifecycle status: Filter 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 Filter in this status.

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

See Also:
Filter lifecycle, Constant Field Values
Method Detail

create

int create()
Try to create this filter 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 Filter.

Returns:

set

int set(String value)
Try to extend this filter on the server.

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

If this method invocation completed successfully,
then

otherwise

In any case the current status remains unchanged.

Parameters:
value - filter extension of the new filter.
Returns:

destroy

int destroy()
Try to destroy this filter 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 Filter immediately after this method invocation without handling the returned value.

Returns:


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