com.lightstreamer.ls_proxy
Class Item

java.lang.Object
  com.lightstreamer.ls_proxy.Item

public final class Item
extends java.lang.Object

Specifies a subscription Item, that is, an information Item supplied by Lightstreamer Server through a Data Adapter, together with subscription preferences. We will refer to subscription Items simply as Items and will refer to Subscription Items with MERGE subscription mode as MERGE Items (and so on). Subscription Item instances related to the same information Item and with the same subscription preferences are equal to one another. Subscription requests for equal Items will be shared. There is a number of cases in which sharing subscription requests is not desirable:

• If a MERGE Item is being subscribed twice with different schemas and the two subscriptions are not enclosed in a transaction, sharing the second subscription with the first one may imply that the Snapshot and the very first Updates for the second subscription contain unknown values for some Fields.
• If a non-MERGE Item is being subscribed twice with different schemas and the two subscriptions are not enclosed in a transaction, sharing the second subscription with the first one may not be allowed and the second subscription attempt may fail.

To prevent all these problems, subscription Item instances related to the same information Item and with the same subscription preferences can be set as different, by calling the setUnique() method on them.

Field Summary

static java.lang.String	ADD_COMMAND String constant for ADD value of COMMAND field in COMMAND subscription mode.
static java.lang.String	COMMAND String constant for COMMAND subscription mode.
static java.lang.String	COMMAND_FIELD String constant for COMMAND field in COMMAND subscription mode.
static java.lang.String	DELETE_COMMAND String constant for DELETE value of COMMAND field in COMMAND subscription mode.
static java.lang.String	DISTINCT String constant for DISTINCT subscription mode.
static java.lang.String	KEY_FIELD String constant for KEY field in COMMAND subscription mode.
static java.lang.String	MERGE String constant for MERGE subscription mode.
static java.lang.String	RAW String constant for RAW subscription mode.
static java.lang.String	UPDATE_COMMAND String constant for UPDATE value of COMMAND field in COMMAND subscription mode.

Constructor Summary

Item(java.lang.String name, java.lang.String mode)
Constructs a subscription Item with a supplied subscription mode and default subscription preferences.

Item(java.lang.String name, java.lang.String dataAdapter, java.lang.String mode)
Constructs a subscription Item with a supplied subscription mode and Data Adapter name and default subscription preferences.

Method Summary

boolean	equals(java.lang.Object other) Compares two Item instances and declares them as equal if all of the following conditions apply: the instances refer to the same information Item; all subscription preferences coincide; neither Item has been set as unique.
java.lang.Integer	getBufferSize() Gets the maximum size for the Server ItemEventBuffer for the Item.
java.lang.String	getDataAdapter() Gets the name of the Data Adapter (within the Adapter Set used by the current session) that supplies the Item.
int	getDistinctSnapshotLength() Gets the length of the Snapshot to be maintained for the Item, if the Item is to be subscribed in DISTINCT mode
java.lang.Double	getMaxFrequency() Gets the maximum Server update frequency for the Item.
java.lang.String	getMode() Gets the subscription mode of the Item.
java.lang.String	getName() Gets the name of the information Item supplied by Lightstreamer Server through a Data Adapter.
java.lang.String	getSelector() Gets the optional selector associated to the Item.
int	hashCode() Supplies a hash code consistent with object equality.
boolean	isUnfiltered() Gets the setting for unfiltered dispatching.
void	requestUnfilteredDispatching() Requests that events for the Item are dispatched in an unfiltered way.
void	setDistinctSnapshotLength(int length) Sets the length of the Snapshot to be maintained for an Item subscribed in DISTINCT mode.
void	setRequestedBufferSize(int bufferSize) Sets the requested size for the Server ItemEventBuffer for the Item.
void	setRequestedMaxFrequency(double maxFrequency) Sets the maximum Server update frequency for the Item.
void	setSelector(java.lang.String selector) Specifies a selector to be applied by the Server to the updates pertaining to the Item.
void	setUnique() Forces the Item instance not to be equal to other Item instances related to the same information Item and with the same subscription preferences.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MERGE

public static final java.lang.String MERGE

String constant for MERGE subscription mode.

See Also:

Constant Field Values

DISTINCT

public static final java.lang.String DISTINCT

String constant for DISTINCT subscription mode.

See Also:

Constant Field Values

RAW

public static final java.lang.String RAW

String constant for RAW subscription mode.

See Also:

Constant Field Values

COMMAND

public static final java.lang.String COMMAND

String constant for COMMAND subscription mode.

See Also:

Constant Field Values

KEY_FIELD

public static final java.lang.String KEY_FIELD

String constant for KEY field in COMMAND subscription mode.

See Also:

Constant Field Values

COMMAND_FIELD

public static final java.lang.String COMMAND_FIELD

String constant for COMMAND field in COMMAND subscription mode.

See Also:

Constant Field Values

ADD_COMMAND

public static final java.lang.String ADD_COMMAND

String constant for ADD value of COMMAND field in COMMAND subscription mode.

See Also:

Constant Field Values

UPDATE_COMMAND

public static final java.lang.String UPDATE_COMMAND

String constant for UPDATE value of COMMAND field in COMMAND subscription mode.

See Also:

Constant Field Values

DELETE_COMMAND

public static final java.lang.String DELETE_COMMAND

String constant for DELETE value of COMMAND field in COMMAND subscription mode.

See Also:

Constant Field Values

Constructor Detail

Item

public Item(java.lang.String name,
            java.lang.String mode)
     throws ItemException

Constructs a subscription Item with a supplied subscription mode and default subscription preferences. The Item is intended to be supplied by the default Data Adapter (within the Adapter Set used by the current session).

Parameters:

name - name of an information Item supplied by Lightstreamer Server through a Data Adapter.

mode - a subscription mode. Must be chosen among the constants defined in this class.

Throws:

ItemException - thrown in case of inconsistency in the supplied parameters.

See Also:

getDataAdapter(), ConnectionInfo.adapter

Item

public Item(java.lang.String name,
            java.lang.String dataAdapter,
            java.lang.String mode)
     throws ItemException

Constructs a subscription Item with a supplied subscription mode and Data Adapter name and default subscription preferences.

Parameters:

name - name of an information Item supplied by Lightstreamer Server through a Data Adapter.

dataAdapter - name of the Data Adapter (within the current Adapter Set) that supplies the item.

mode - a subscription mode. Must be chosen among the constants defined in this class.

Throws:

ItemException - thrown in case of inconsistency in the supplied parameters.

See Also:

getDataAdapter()

Method Detail

setUnique

public void setUnique()

Forces the Item instance not to be equal to other Item instances related to the same information Item and with the same subscription preferences.

setSelector

public void setSelector(java.lang.String selector)

Specifies a selector to be applied by the Server to the updates pertaining to the Item.

Parameters:

selector - name of a Selector. It will be interpreted by the Metadata Adapter.

setRequestedBufferSize

public void setRequestedBufferSize(int bufferSize)
                            throws ItemException

Sets the requested size for the Server ItemEventBuffer for the Item. If not specified, a 1 element buffer is intended if mode is MERGE and a 0 value (unlimited buffer) is intended if mode is DISTINCT. However, the real Server buffer size can be limited by the Metadata Adapter. The buffer size can be specified only for MERGE and DISTINCT Items mode. It is ignored if requestUnfilteredDispatching() is also called.

Parameters:

bufferSize - the size requested for the ItemEventBuffer. It must not be negative.

Throws:

ItemException - thrown if buffer size setting is not compatible with the Item subscription mode.

setRequestedMaxFrequency

public void setRequestedMaxFrequency(double maxFrequency)
                              throws ItemException

Sets the maximum Server update frequency for the Item. It can only be used in order to lower the frequency granted by the Metadata Adapter. The update frequency can be specified only for MERGE, DISTINCT and COMMAND Item mode; in the latter case, the frequency limit only applies to consecutive UPDATE events for the same key value. It is ignored if requestUnfilteredDispatching() is also called.

Parameters:

maxFrequency - the frequency requested for the Item Updates, in updates/sec. It must not be negative.

Throws:

ItemException - thrown if maximum frequency setting is not compatible with the Item subscription mode.

Edition Note:

A further global frequency limit is also imposed by the Server, if it is running in Presto edition; this specific limit also applies to RAW mode and to unfiltered dispatching.

requestUnfilteredDispatching

public void requestUnfilteredDispatching()
                                  throws ItemException

Requests that events for the Item are dispatched in an unfiltered way. This setting is stronger than the setting of the maximum update frequency and can lead to the subscription refusal by the Metadata Adapter. It is also stronger than the setting for the buffer size. The unfiltered dispatching can be specified only for MERGE, DISTINCT and COMMAND Items mode.

Throws:

ItemException - Thrown if unfiltered dispatching is not compatible with the Item subscription mode.

setDistinctSnapshotLength

public void setDistinctSnapshotLength(int length)
                               throws ItemException

Sets the length of the Snapshot to be maintained for an Item subscribed in DISTINCT mode. This setting both affects snapshot requests to Lightstreamer Server upon subscription and internal caching of the Snapshot.

Parameters:

length - the Snapshot length. It must not be negative. A zero value means that no snapshot will be received for the Item.

Throws:

ItemException - thrown if the Item subscription mode is not DISTINCT.

getName

public java.lang.String getName()

Gets the name of the information Item supplied by Lightstreamer Server through a Data Adapter.

Returns:

the information Item name.

getDataAdapter

public java.lang.String getDataAdapter()

Gets the name of the Data Adapter (within the Adapter Set used by the current session) that supplies the Item.
The Data Adapter name is configured on the server side through the "name" attribute of the "data_provider" element, in the "adapters.xml" file that defines the Adapter Set. Omitting the attribute configures the "DEFAULT" name.

Returns:

the Data Adapter name or null, to mean the default Data Adapter, which is named "DEFAULT".

getMode

public java.lang.String getMode()

Gets the subscription mode of the Item.

Returns:

a subscription mode. The value can be checked for identity against the constants defined in this class.

getSelector

public java.lang.String getSelector()

Gets the optional selector associated to the Item.

Returns:

a selector name, or null if no selector was associated to the Item.

getBufferSize

public java.lang.Integer getBufferSize()

Gets the maximum size for the Server ItemEventBuffer for the Item. This setting is ignored if requestUnfilteredDispatching() has been called.

Returns:

the requested buffer size, or null if no specific buffer size has been requested.

getMaxFrequency

public java.lang.Double getMaxFrequency()

Gets the maximum Server update frequency for the Item. This setting is ignored if requestUnfilteredDispatching() has been called.

Returns:

the requested frequency, in updates/sec, or null if no update frequency restraint has been requested.

isUnfiltered

public boolean isUnfiltered()

Gets the setting for unfiltered dispatching.

Returns:

true if unfiltered dispatching has been requested.

getDistinctSnapshotLength

public int getDistinctSnapshotLength()

Gets the length of the Snapshot to be maintained for the Item, if the Item is to be subscribed in DISTINCT mode

Returns:

the maintained Snapshot length; it can also be 0.

equals

public boolean equals(java.lang.Object other)

Compares two Item instances and declares them as equal if all of the following conditions apply:

• the instances refer to the same information Item;
• all subscription preferences coincide;
• neither Item has been set as unique.

Overrides:

equals in class java.lang.Object

Parameters:

other - object to compare.

Returns:

true if the two objects can be considered as equal with respect to the possibility of sharing their subscription requests.

hashCode

public int hashCode()

Supplies a hash code consistent with object equality.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code for the object.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object