com.lightstreamer.client

Class Subscription

java.lang.Object

com.lightstreamer.client.Subscription

public class Subscription
extends java.lang.Object

Class representing a Subscription to be submitted to a Lightstreamer Server. It contains subscription details and the listeners needed to process the real-time data.
After the creation, a Subscription object is in the "inactive" state. When a Subscription object is subscribed to on a LightstreamerClient object, through the LightstreamerClient.subscribe(Subscription) method, its state becomes "active". This means that the client activates a subscription to the required items through Lightstreamer Server and the Subscription object begins to receive real-time events.
A Subscription can be configured to use either an Item Group or an Item List to specify the items to be subscribed to and using either a Field Schema or Field List to specify the fields.
"Item Group" and "Item List" are defined as follows:

• "Item Group": an Item Group is a String identifier representing a list of items. Such Item Group has to be expanded into a list of items by the getItems method of the MetadataProvider of the associated Adapter Set. When using an Item Group, items in the subscription are identified by their 1-based index within the group.
  It is possible to configure the Subscription to use an "Item Group" using the setItemGroup(String) method.
• "Item List": an Item List is an array of Strings each one representing an item. For the Item List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getItems has to be configured in the associated Adapter Set.
  Note that no item in the list can be empty, can contain spaces or can be a number.
  When using an Item List, items in the subscription are identified by their name or by their 1-based index within the list.
  It is possible to configure the Subscription to use an "Item List" using the setItems(String[]) method or by specifying it in the constructor.

"Field Schema" and "Field List" are defined as follows:

• "Field Schema": a Field Schema is a String identifier representing a list of fields. Such Field Schema has to be expanded into a list of fields by the getFields method of the MetadataProvider of the associated Adapter Set. When using a Field Schema, fields in the subscription are identified by their 1-based index within the schema.
  It is possible to configure the Subscription to use a "Field Schema" using the setFieldSchema(String) method.
• "Field List": a Field List is an array of Strings each one representing a field. For the Field List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getFields has to be configured in the associated Adapter Set.
  Note that no field in the list can be empty, can contain spaces or can be a number.
  When using a Field List, fields in the subscription are identified by their name or by their 1-based index within the list.

It is possible to configure the Subscription to use a "Field List" using the setFields(String[]) method or by specifying it in the constructor.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	subMode

Constructor Summary

Constructors

Constructor and Description
Subscription(java.lang.String subscriptionMode) Creates an object to be used to describe a Subscription that is going to be subscribed to through Lightstreamer Server.
Subscription(java.lang.String subscriptionMode, java.lang.String[] items, java.lang.String[] fields) Creates an object to be used to describe a Subscription that is going to be subscribed to through Lightstreamer Server.
Subscription(java.lang.String subscriptionMode, java.lang.String item, java.lang.String[] fields) Creates an object to be used to describe a Subscription that is going to be subscribed to through Lightstreamer Server.

Method Summary

Modifier and Type	Method and Description
void	addListener(SubscriptionListener listener) Adds a listener that will receive events from the Subscription instance. The same listener can be added to several different Subscription instances.
protected void	addSubTable(int item, java.lang.String key)
protected void	debugDescriptor(java.lang.String debugString, com.lightstreamer.util.Descriptor desc)
int	getCommandPosition() Returns the position of the "command" field in a COMMAND Subscription. This method can only be used if the Subscription mode is COMMAND and the Subscription was initialized using a "Field Schema".
java.lang.String	getCommandSecondLevelDataAdapter() Inquiry method that can be used to read the second-level Data Adapter name configured through setCommandSecondLevelDataAdapter(String).
java.lang.String[]	getCommandSecondLevelFields() Inquiry method that can be used to read the "Field List" specified for second-level Subscriptions.
java.lang.String	getCommandSecondLevelFieldSchema() Inquiry method that can be used to read the "Field Schema" specified for second-level Subscriptions.
java.lang.String	getCommandValue(int itemPos, java.lang.String keyValue, int fieldPos) Returns the latest value received for the specified item/key/field combination.
java.lang.String	getCommandValue(int itemPos, java.lang.String keyValue, java.lang.String fieldName) Returns the latest value received for the specified item/key/field combination.
java.lang.String	getCommandValue(java.lang.String itemName, java.lang.String keyValue, int fieldPos) Returns the latest value received for the specified item/key/field combination.
java.lang.String	getCommandValue(java.lang.String itemName, java.lang.String keyValue, java.lang.String fieldName) Returns the latest value received for the specified item/key/field combination.
java.lang.String	getDataAdapter() Inquiry method that can be used to read the name of the Data Adapter specified for this Subscription through setDataAdapter(String).
java.lang.String[]	getFields() Inquiry method that can be used to read the "Field List" specified for this Subscription.
java.lang.String	getFieldSchema() Inquiry method that can be used to read the field schema specified for this Subscription.
java.lang.String	getItemGroup() Inquiry method that can be used to read the item group specified for this Subscription.
java.lang.String[]	getItems() Inquiry method that can be used to read the "Item List" specified for this Subscription.
int	getKeyPosition() Returns the position of the "key" field in a COMMAND Subscription. This method can only be used if the Subscription mode is COMMAND and the Subscription was initialized using a "Field Schema".
java.util.List<SubscriptionListener>	getListeners() Returns a list containing the SubscriptionListener instances that were added to this client.
java.lang.String	getMode() Inquiry method that can be used to read the mode specified for this Subscription.
java.lang.String	getRequestedBufferSize() Inquiry method that can be used to read the buffer size, configured though setRequestedBufferSize(java.lang.String), to be requested to the Server for this Subscription.
java.lang.String	getRequestedMaxFrequency() Inquiry method that can be used to read the max frequency, configured through setRequestedMaxFrequency(String), to be requested to the Server for this Subscription.
java.lang.String	getRequestedSnapshot() Inquiry method that can be used to read the snapshot preferences, configured through setRequestedSnapshot(String), to be requested to the Server for this Subscription.
java.lang.String	getSelector() Inquiry method that can be used to read the selector name specified for this Subscription through setSelector(String).
java.lang.String	getValue(int itemPos, int fieldPos) Returns the latest value received for the specified item/field pair. It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method. In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead. Note that internal data is cleared when the Subscription is unsubscribed from.
java.lang.String	getValue(int itemPos, java.lang.String fieldName) Returns the latest value received for the specified item/field pair. It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method. In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead. Note that internal data is cleared when the Subscription is unsubscribed from.
java.lang.String	getValue(java.lang.String itemName, int fieldPos) Returns the latest value received for the specified item/field pair. It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method. In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead. Note that internal data is cleared when the Subscription is unsubscribed from.
java.lang.String	getValue(java.lang.String itemName, java.lang.String fieldName) Returns the latest value received for the specified item/field pair. It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method. In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead. Note that internal data is cleared when the Subscription is unsubscribed from.
boolean	isActive() Inquiry method that checks if the Subscription is currently "active" or not.
boolean	isSubscribed() Inquiry method that checks if the Subscription is currently subscribed to through the server or not. This flag is switched to true by server sent Subscription events, and back to false in case of client disconnection, LightstreamerClient.unsubscribe(Subscription) calls and server sent unsubscription events.
void	removeListener(SubscriptionListener listener) Removes a listener from the Subscription instance so that it will not receive events anymore.
void	setCommandSecondLevelDataAdapter(java.lang.String dataAdapter) Setter method that sets the name of the second-level Data Adapter (within the Adapter Set used by the current session) that supplies all the second-level items. All the possible second-level items should be supplied in "MERGE" mode with snapshot available. 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 (a missing attribute configures the "DEFAULT" name).
void	setCommandSecondLevelFields(java.lang.String[] fields) Setter method that sets the "Field List" to be subscribed to through Lightstreamer Server for the second-level items.
void	setCommandSecondLevelFieldSchema(java.lang.String schemaName) Setter method that sets the "Field Schema" to be subscribed to through Lightstreamer Server for the second-level items.
void	setDataAdapter(java.lang.String dataAdapter) Setter method that sets the name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items for this Subscription. 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 (a missing attribute configures the "DEFAULT" name). Note that if more than one Data Adapter is needed to supply all the items in a set of items, then it is not possible to group all the items of the set in a single Subscription.
void	setFields(java.lang.String[] fields) Setter method that sets the "Field List" to be subscribed to through Lightstreamer Server. Any call to this method will override any "Field List" or "Field Schema" previously specified.
void	setFieldSchema(java.lang.String schemaName) Setter method that sets the "Field Schema" to be subscribed to through Lightstreamer Server. Any call to this method will override any "Field List" or "Field Schema" previously specified.
void	setItemGroup(java.lang.String groupName) Setter method that sets the "Item Group" to be subscribed to through Lightstreamer Server. Any call to this method will override any "Item List" or "Item Group" previously specified.
void	setItems(java.lang.String[] items) Setter method that sets the "Item List" to be subscribed to through Lightstreamer Server. Any call to this method will override any "Item List" or "Item Group" previously specified.
void	setRequestedBufferSize(java.lang.String size) Setter method that sets the length to be requested to Lightstreamer Server for the internal queuing buffers for the items in the Subscription.
void	setRequestedMaxFrequency(java.lang.String freq) Setter method that sets the maximum update frequency to be requested to Lightstreamer Server for all the items in the Subscription.
void	setRequestedSnapshot(java.lang.String required) Setter method that enables/disables snapshot delivery request for the items in the Subscription.
void	setSelector(java.lang.String selector) Setter method that sets the selector name for all the items in the Subscription.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

subMode

protected java.lang.String subMode

Constructor Detail

Subscription

public Subscription(java.lang.String subscriptionMode,
                    java.lang.String[] items,
                    java.lang.String[] fields)

Creates an object to be used to describe a Subscription that is going to be subscribed to through Lightstreamer Server. The object can be supplied to LightstreamerClient.subscribe(Subscription) and LightstreamerClient.unsubscribe(Subscription), in order to bring the Subscription to "active" or back to "inactive" state.
Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the "inactive" state; the only exception is setRequestedMaxFrequency(String).

Parameters:

subscriptionMode - the subscription mode for the items, required by Lightstreamer Server. Permitted values are:

• MERGE
• DISTINCT
• RAW
• COMMAND

items - an array of items to be subscribed to through Lightstreamer server.
It is also possible specify the "Item List" or "Item Group" later through setItems(String[]) and setItemGroup(java.lang.String).

fields - an array of fields for the items to be subscribed to through Lightstreamer Server.
It is also possible to specify the "Field List" or "Field Schema" later through setFields(String[]) and setFieldSchema(String).

Throws:

java.lang.IllegalArgumentException - If no or invalid subscription mode is passed.

java.lang.IllegalArgumentException - If either the items or the fields array is left null.

java.lang.IllegalArgumentException - If the specified "Item List" or "Field List" is not valid; see setItems(String[]) and setFields(String[]) for details.

Subscription

public Subscription(java.lang.String subscriptionMode,
                    java.lang.String item,
                    java.lang.String[] fields)

Creates an object to be used to describe a Subscription that is going to be subscribed to through Lightstreamer Server. The object can be supplied to LightstreamerClient.subscribe(Subscription) and LightstreamerClient.unsubscribe(Subscription), in order to bring the Subscription to "active" or back to "inactive" state.
Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the "inactive" state; the only exception is setRequestedMaxFrequency(String).

Parameters:

subscriptionMode - the subscription mode for the items, required by Lightstreamer Server. Permitted values are:

• MERGE
• DISTINCT
• RAW
• COMMAND

item - the item name to be subscribed to through Lightstreamer Server.

fields - an array of fields for the items to be subscribed to through Lightstreamer Server.
It is also possible to specify the "Field List" or "Field Schema" later through setFields(String[]) and setFieldSchema(String).

Throws:

java.lang.IllegalArgumentException - If no or invalid subscription mode is passed.

java.lang.IllegalArgumentException - If either the item or the fields array is left null.

java.lang.IllegalArgumentException - If the specified "Field List" is not valid; see setFields(String[]) for details..

Subscription

public Subscription(java.lang.String subscriptionMode)

Creates an object to be used to describe a Subscription that is going to be subscribed to through Lightstreamer Server. The object can be supplied to LightstreamerClient.subscribe(Subscription) and LightstreamerClient.unsubscribe(Subscription), in order to bring the Subscription to "active" or back to "inactive" state.
Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the "inactive" state; the only exception is setRequestedMaxFrequency(String).

Parameters:

subscriptionMode - the subscription mode for the items, required by Lightstreamer Server. Permitted values are:

• MERGE
• DISTINCT
• RAW
• COMMAND

Method Detail

addListener

public void addListener(SubscriptionListener listener)

Adds a listener that will receive events from the Subscription instance.
The same listener can be added to several different Subscription instances.

Parameters:

listener - An object that will receive the events as documented in the SubscriptionListener interface.

See Also:

removeListener(SubscriptionListener)

Lifecycle:

A listener can be added at any time. A call to add a listener already present will be ignored.

removeListener

public void removeListener(SubscriptionListener listener)

Removes a listener from the Subscription instance so that it will not receive events anymore.

Parameters:

listener - The listener to be removed.

See Also:

addListener(SubscriptionListener)

Lifecycle:

a listener can be removed at any time.

getListeners

public java.util.List<SubscriptionListener> getListeners()

Returns a list containing the SubscriptionListener instances that were added to this client.

Returns:

a list containing the listeners that were added to this client.

See Also:

addListener(SubscriptionListener)

isActive

public boolean isActive()

Inquiry method that checks if the Subscription is currently "active" or not. Most of the Subscription properties cannot be modified if a Subscription is "active".
The status of a Subscription is changed to "active" through the LightstreamerClient.subscribe(Subscription) method and back to "inactive" through the LightstreamerClient.unsubscribe(Subscription) one.

Returns:

true/false if the Subscription is "active" or not.

See Also:

LightstreamerClient.subscribe(Subscription), LightstreamerClient.unsubscribe(Subscription)

Lifecycle:

This method can be called at any time.

isSubscribed

public boolean isSubscribed()

Inquiry method that checks if the Subscription is currently subscribed to through the server or not.
This flag is switched to true by server sent Subscription events, and back to false in case of client disconnection, LightstreamerClient.unsubscribe(Subscription) calls and server sent unsubscription events.

Returns:

true/false if the Subscription is subscribed to through the server or not.

Lifecycle:

This method can be called at any time.

getDataAdapter

public java.lang.String getDataAdapter()

Inquiry method that can be used to read the name of the Data Adapter specified for this Subscription through setDataAdapter(String).

Returns:

the name of the Data Adapter; returns null if no name has been configured, so that the "DEFAULT" Adapter Set is used.

Lifecycle:

This method can be called at any time.

setDataAdapter

public void setDataAdapter(java.lang.String dataAdapter)

Setter method that sets the name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items for this Subscription.
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 (a missing attribute configures the "DEFAULT" name).
Note that if more than one Data Adapter is needed to supply all the items in a set of items, then it is not possible to group all the items of the set in a single Subscription. Multiple Subscriptions have to be defined.

Parameters:

dataAdapter - the name of the Data Adapter. A null value is equivalent to the "DEFAULT" name.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

See Also:

ConnectionDetails.setAdapterSet(String)

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

Default value:

The default Data Adapter for the Adapter Set, configured as "DEFAULT" on the Server.

getMode

public java.lang.String getMode()

Inquiry method that can be used to read the mode specified for this Subscription.

Returns:

the Subscription mode specified in the constructor.

Lifecycle:

This method can be called at any time.

getItems

public java.lang.String[] getItems()

Inquiry method that can be used to read the "Item List" specified for this Subscription. Note that if the single-item-constructor was used, this method will return an array of length 1 containing such item.

Returns:

the "Item List" to be subscribed to through the server.

Throws:

java.lang.IllegalStateException - if the Subscription was initialized with an "Item Group" or was not initialized at all.

Lifecycle:

This method can only be called if the Subscription has been initialized with an "Item List".

setItems

public void setItems(java.lang.String[] items)

Setter method that sets the "Item List" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Item List" or "Item Group" previously specified.

Parameters:

items - an array of items to be subscribed to through the server.

Throws:

java.lang.IllegalArgumentException - if any of the item names in the "Item List" contains a space or is a number or is empty/null.

java.lang.IllegalStateException - if the Subscription is currently "active".

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

getItemGroup

public java.lang.String getItemGroup()

Inquiry method that can be used to read the item group specified for this Subscription.

Returns:

the "Item Group" to be subscribed to through the server.

Throws:

java.lang.IllegalStateException - if the Subscription was initialized with an "Item List" or was not initialized at all.

Lifecycle:

This method can only be called if the Subscription has been initialized using an "Item Group"

setItemGroup

public void setItemGroup(java.lang.String groupName)

Setter method that sets the "Item Group" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Item List" or "Item Group" previously specified.

Parameters:

groupName - A String to be expanded into an item list by the Metadata Adapter.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

getFields

public java.lang.String[] getFields()

Inquiry method that can be used to read the "Field List" specified for this Subscription.

Returns:

the "Field List" to be subscribed to through the server.

Throws:

java.lang.IllegalStateException - if the Subscription was initialized with a "Field Schema" or was not initialized at all.

Lifecycle:

This method can only be called if the Subscription has been initialized using a "Field List".

setFields

public void setFields(java.lang.String[] fields)

Setter method that sets the "Field List" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Field List" or "Field Schema" previously specified.

Parameters:

fields - an array of fields to be subscribed to through the server.

Throws:

java.lang.IllegalArgumentException - if any of the field names in the list contains a space or is a number or is empty/null.

java.lang.IllegalStateException - if the Subscription is currently "active".

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

getFieldSchema

public java.lang.String getFieldSchema()

Inquiry method that can be used to read the field schema specified for this Subscription.

Returns:

the "Field Schema" to be subscribed to through the server.

Throws:

java.lang.IllegalStateException - if the Subscription was initialized with a "Field List" or was not initialized at all.

Lifecycle:

This method can only be called if the Subscription has been initialized using a "Field Schema"

setFieldSchema

public void setFieldSchema(java.lang.String schemaName)

Setter method that sets the "Field Schema" to be subscribed to through Lightstreamer Server.
Any call to this method will override any "Field List" or "Field Schema" previously specified.

Parameters:

schemaName - A String to be expanded into a field list by the Metadata Adapter.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

Partial implementation note:

In the current version, the implementation is incomplete; if the subscription is in COMMAND mode, using this call will result in a SubscriptionListener.onSubscriptionError(int, String) with code 23

getRequestedBufferSize

public java.lang.String getRequestedBufferSize()

Inquiry method that can be used to read the buffer size, configured though setRequestedBufferSize(java.lang.String), to be requested to the Server for this Subscription.

Returns:

the buffer size to be requested to the server.

Lifecycle:

This method can be called at any time.

setRequestedBufferSize

public void setRequestedBufferSize(java.lang.String size)

Setter method that sets the length to be requested to Lightstreamer Server for the internal queuing buffers for the items in the Subscription. A Queuing buffer is used by the Server to accumulate a burst of updates for an item, so that they can all be sent to the client, despite of bandwidth or frequency limits. It can be used only when the subscription mode is MERGE or DISTINCT and unfiltered dispatching has not been requested. Note that the Server may pose an upper limit on the size of its internal buffers.

Parameters:

size - The length of the internal queuing buffers to be used in the Server. If the string "unlimited" is supplied, then the buffer length is decided by the Server (the check is case insensitive).

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

java.lang.IllegalArgumentException - if the specified value is not null nor "unlimited" nor a valid positive integer number.

See Also:

setRequestedMaxFrequency(String)

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

Default value:

null, meaning to not request a buffer size to the server; this means that the buffer size will be 1 for MERGE subscriptions and "unlimited" for DISTINCT subscriptions. See the "General Concepts" document for further details.

getRequestedSnapshot

public java.lang.String getRequestedSnapshot()

Inquiry method that can be used to read the snapshot preferences, configured through setRequestedSnapshot(String), to be requested to the Server for this Subscription.

Returns:

the snapshot preference to be requested to the server.

Lifecycle:

This method can be called at any time.

setRequestedSnapshot

public void setRequestedSnapshot(java.lang.String required)

Setter method that enables/disables snapshot delivery request for the items in the Subscription. The snapshot can be requested only if the Subscription mode is MERGE, DISTINCT or COMMAND.

Parameters:

required - "yes"/"no" to request/not request snapshot delivery (the check is case insensitive). If the Subscription mode is DISTINCT, instead of "yes", it is also possible to supply a number, to specify the requested length of the snapshot (though the length of the received snapshot may be less than requested, because of insufficient data or server side limits); passing "yes" means that the snapshot length should be determined only by the Server. Null is also a valid value; if specified no snapshot preference will be sent to the server that will decide itself whether or not to send any snapshot.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

java.lang.IllegalArgumentException - if the specified value is not "yes" nor "no" nor null nor a valid integer positive number.

java.lang.IllegalArgumentException - if the specified value is not compatible with the mode of the Subscription:

• In case of a RAW Subscription only null is a valid value;
• In case of a non-DISTINCT Subscription only null "yes" and "no" are valid values.

See Also:

ItemUpdate.isSnapshot

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

Default value:

"yes" if the Subscription mode is not "RAW", null otherwise.

getRequestedMaxFrequency

public java.lang.String getRequestedMaxFrequency()

Inquiry method that can be used to read the max frequency, configured through setRequestedMaxFrequency(String), to be requested to the Server for this Subscription.

Returns:

the max frequency to be requested to the server.

Lifecycle:

This method can be called at any time.

setRequestedMaxFrequency

public void setRequestedMaxFrequency(java.lang.String freq)

Setter method that sets the maximum update frequency to be requested to Lightstreamer Server for all the items in the Subscription. It can be used only if the Subscription mode is MERGE, DISTINCT or COMMAND (in the latter case, the frequency limitation applies to the UPDATE events for each single key).
Note that frequency limits on the items can also be set on the server side and this request can only be issued in order to furtherly reduce the frequency, not to rise it beyond these limits.
This method can also be used to request unfiltered dispatching for the items in the Subscription. However, unfiltered dispatching requests may be refused if any frequency limit is posed on the server side for some item.

Parameters:

freq - The maximum update frequency (expressed in updates per second) for each item in the Subscription; for instance, with a setting of 0.5, for each single item, no more than one update every 2 seconds will be received. If the string "unlimited" is supplied, then the maximum frequency is decided by the Server. It is also possible to supply the string "unfiltered", to ask for unfiltered dispatching, if it is allowed for the items, or a null value to avoid sending any frequency request to the server. The check for the string constants is case insensitive.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active" and the current value of this property is null or "unfiltered".

java.lang.IllegalStateException - if the Subscription is currently "active" and the given parameter is null or "unfiltered".

java.lang.IllegalArgumentException - if the specified value is not null nor one of the special "unlimited" and "unfiltered" values nor a valid positive number.

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.

Edition Note:

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

Edition Note:

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

Lifecycle:

This method can can be called at any time with some differences based on the Subscription status:

• If the Subscription instance is in its "inactive" state then this method can be called at will.
• If the Subscription instance is in its "active" state then the method can still be called unless its current or target value is "unfiltered" or null. Also if the Subscription instance is in its "active" state and the connection to the server is currently open, then a request to change the frequency of the Subscription on the fly is sent to the server.

Default value:

null, meaning to not request any frequency limit to the server. As a consequence the server will try to not apply any frequency limit to the subscription (i.e.: "unlimited", see the "General Concepts" document for further details)

getSelector

public java.lang.String getSelector()

Inquiry method that can be used to read the selector name specified for this Subscription through setSelector(String).

Returns:

the name of the selector.

Lifecycle:

This method can be called at any time.

setSelector

public void setSelector(java.lang.String selector)

Setter method that sets the selector name for all the items in the Subscription. The selector is a filter on the updates received. It is executed on the Server and implemented by the Metadata Adapter.

Parameters:

selector - name of a selector, to be recognized by the Metadata Adapter, or null to unset the selector.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

Default value:

null (no selector).

getCommandPosition

public int getCommandPosition()

Returns the position of the "command" field in a COMMAND Subscription.
This method can only be used if the Subscription mode is COMMAND and the Subscription was initialized using a "Field Schema".

Returns:

the 1-based position of the "command" field within the "Field Schema".

Throws:

java.lang.IllegalStateException - if the Subscription mode is not COMMAND or if the SubscriptionListener.onSubscription() event for this Subscription was not yet fired.

java.lang.IllegalStateException - if a "Field List" was specified.

Lifecycle:

This method can be called at any time after the first SubscriptionListener.onSubscription() event.

getKeyPosition

public int getKeyPosition()

Returns the position of the "key" field in a COMMAND Subscription.
This method can only be used if the Subscription mode is COMMAND and the Subscription was initialized using a "Field Schema".

Returns:

the 1-based position of the "key" field within the "Field Schema".

Throws:

java.lang.IllegalStateException - if the Subscription mode is not COMMAND or if the SubscriptionListener.onSubscription() event for this Subscription was not yet fired.

Lifecycle:

This method can be called at any time.

getCommandSecondLevelDataAdapter

public java.lang.String getCommandSecondLevelDataAdapter()

Inquiry method that can be used to read the second-level Data Adapter name configured through setCommandSecondLevelDataAdapter(String).

Returns:

the name of the second-level Data Adapter.

Throws:

java.lang.IllegalStateException - if the Subscription mode is not COMMAND

See Also:

setCommandSecondLevelDataAdapter(String)

Lifecycle:

This method can be called at any time.

setCommandSecondLevelDataAdapter

public void setCommandSecondLevelDataAdapter(java.lang.String dataAdapter)

Setter method that sets the name of the second-level Data Adapter (within the Adapter Set used by the current session) that supplies all the second-level items.
All the possible second-level items should be supplied in "MERGE" mode with snapshot available.
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 (a missing attribute configures the "DEFAULT" name).

Parameters:

dataAdapter - the name of the Data Adapter. A null value is equivalent to the "DEFAULT" name.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

java.lang.IllegalStateException - if the Subscription mode is not "COMMAND".

See Also:

setCommandSecondLevelFields(String[]), setCommandSecondLevelFieldSchema(String)

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

Default value:

The default Data Adapter for the Adapter Set, configured as "DEFAULT" on the Server.

getCommandSecondLevelFields

public java.lang.String[] getCommandSecondLevelFields()

Inquiry method that can be used to read the "Field List" specified for second-level Subscriptions.

Returns:

the list of fields to be subscribed to through the server.

Throws:

java.lang.IllegalStateException - if the Subscription was initialized with a "Field Schema" or was not initialized at all.

java.lang.IllegalStateException - if the Subscription mode is not COMMAND

Lifecycle:

This method can only be called if the second-level of this Subscription has been initialized using a "Field List"

setCommandSecondLevelFields

public void setCommandSecondLevelFields(java.lang.String[] fields)

Setter method that sets the "Field List" to be subscribed to through Lightstreamer Server for the second-level items. It can only be used on COMMAND Subscriptions.
Any call to this method will override any "Field List" or "Field Schema" previously specified for the second-level.
Calling this method enables the two-level behavior:
in synthesis, each time a new key is received on the COMMAND Subscription, the key value is treated as an Item name and an underlying Subscription for this Item is created and subscribed to automatically, to feed fields specified by this method. This mono-item Subscription is specified through an "Item List" containing only the Item name received. As a consequence, all the conditions provided for subscriptions through Item Lists have to be satisfied. The item is subscribed to in "MERGE" mode, with snapshot request and with the same maximum frequency setting as for the first-level items (including the "unfiltered" case). All other Subscription properties are left as the default. When the key is deleted by a DELETE command on the first-level Subscription, the associated second-level Subscription is also unsubscribed from.
Specifying null as parameter will disable the two-level behavior.

Parameters:

fields - An array of Strings containing a list of fields to be subscribed to through the server.
Ensure that no name conflict is generated between first-level and second-level fields. In case of conflict, the second-level field will not be accessible by name, but only by position.

Throws:

java.lang.IllegalArgumentException - if any of the field names in the "Field List" contains a space or is a number or is empty/null.

java.lang.IllegalStateException - if the Subscription is currently "active".

java.lang.IllegalStateException - if the Subscription mode is not "COMMAND".

See Also:

setCommandSecondLevelFieldSchema(String)

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

getCommandSecondLevelFieldSchema

public java.lang.String getCommandSecondLevelFieldSchema()

Inquiry method that can be used to read the "Field Schema" specified for second-level Subscriptions.

Returns:

the "Field Schema" to be subscribed to through the server.

Throws:

java.lang.IllegalStateException - if the Subscription was initialized with a "Field List" or was not initialized at all.

java.lang.IllegalStateException - if the Subscription mode is not COMMAND

Lifecycle:

This method can only be called if the second-level of this Subscription has been initialized using a "Field Schema".

setCommandSecondLevelFieldSchema

public void setCommandSecondLevelFieldSchema(java.lang.String schemaName)

Setter method that sets the "Field Schema" to be subscribed to through Lightstreamer Server for the second-level items. It can only be used on COMMAND Subscriptions.
Any call to this method will override any "Field List" or "Field Schema" previously specified for the second-level.
Calling this method enables the two-level behavior:
in synthesis, each time a new key is received on the COMMAND Subscription, the key value is treated as an Item name and an underlying Subscription for this Item is created and subscribed to automatically, to feed fields specified by this method. This mono-item Subscription is specified through an "Item List" containing only the Item name received. As a consequence, all the conditions provided for subscriptions through Item Lists have to be satisfied. The item is subscribed to in "MERGE" mode, with snapshot request and with the same maximum frequency setting as for the first-level items (including the "unfiltered" case). All other Subscription properties are left as the default. When the key is deleted by a DELETE command on the first-level Subscription, the associated second-level Subscription is also unsubscribed from.
Specify null as parameter will disable the two-level behavior.

Parameters:

schemaName - A String to be expanded into a field list by the Metadata Adapter.

Throws:

java.lang.IllegalStateException - if the Subscription is currently "active".

java.lang.IllegalStateException - if the Subscription mode is not "COMMAND".

See Also:

setCommandSecondLevelFields(java.lang.String[])

Lifecycle:

This method can only be called while the Subscription instance is in its "inactive" state.

getValue

public java.lang.String getValue(java.lang.String itemName,
                                 java.lang.String fieldName)

Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemName - an item in the configured "Item List"

fieldName - a item in the configured "Field List"

Returns:

the current value for the specified field of the specified item (possibly null), or null if no value has been received yet.

Throws:

java.lang.IllegalArgumentException - if an invalid item name or field name is specified.

Lifecycle:

This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return null.

getValue

public java.lang.String getValue(int itemPos,
                                 int fieldPos)

Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemPos - the 1-based position of an item within the configured "Item Group" or "Item List"

fieldPos - the 1-based position of a field within the configured "Field Schema" or "Field List"

Returns:

the current value for the specified field of the specified item (possibly null), or null if no value has been received yet.

Throws:

java.lang.IllegalArgumentException - if the specified item position or field position is out of bounds.

Lifecycle:

This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return null.

getValue

public java.lang.String getValue(java.lang.String itemName,
                                 int fieldPos)

Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemName - an item in the configured "Item List"

fieldPos - the 1-based position of a field within the configured "Field Schema" or "Field List"

Returns:

the current value for the specified field of the specified item (possibly null), or null if no value has been received yet.

Throws:

java.lang.IllegalArgumentException - if an invalid item name is specified.

java.lang.IllegalArgumentException - if the specified field position is out of bounds.

Lifecycle:

This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return null.

getValue

public java.lang.String getValue(int itemPos,
                                 java.lang.String fieldName)

Returns the latest value received for the specified item/field pair.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use getCommandValue(java.lang.String, java.lang.String, java.lang.String) instead.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemPos - the 1-based position of an item within the configured "Item Group" or "Item List"

fieldName - a item in the configured "Field List"

Returns:

the current value for the specified field of the specified item (possibly null), or null if no value has been received yet.

Throws:

java.lang.IllegalArgumentException - if an invalid field name is specified.

java.lang.IllegalArgumentException - if the specified item position is out of bounds.

Lifecycle:

This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return null.

getCommandValue

public java.lang.String getCommandValue(java.lang.String itemName,
                                        java.lang.String keyValue,
                                        java.lang.String fieldName)

Returns the latest value received for the specified item/key/field combination. This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemName - an item in the configured "Item List"

keyValue - the value of a key received on the COMMAND subscription.

fieldName - a item in the configured "Field List"

Returns:

the current value for the specified field of the specified key within the specified item (possibly null), or null if the specified key has not been added yet (note that it might have been added and then deleted).

Throws:

java.lang.IllegalArgumentException - if an invalid item name or field name is specified.

java.lang.IllegalStateException - if the Subscription mode is not COMMAND.

getCommandValue

public java.lang.String getCommandValue(int itemPos,
                                        java.lang.String keyValue,
                                        int fieldPos)

Returns the latest value received for the specified item/key/field combination. This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemPos - the 1-based position of an item within the configured "Item Group" or "Item List"

keyValue - the value of a key received on the COMMAND subscription.

fieldPos - the 1-based position of a field within the configured "Field Schema" or "Field List"

Returns:

the current value for the specified field of the specified key within the specified item (possibly null), or null if the specified key has not been added yet (note that it might have been added and then deleted).

Throws:

java.lang.IllegalArgumentException - if the specified item position or field position is out of bounds.

java.lang.IllegalStateException - if the Subscription mode is not COMMAND.

getCommandValue

public java.lang.String getCommandValue(int itemPos,
                                        java.lang.String keyValue,
                                        java.lang.String fieldName)

Returns the latest value received for the specified item/key/field combination. This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemPos - the 1-based position of an item within the configured "Item Group" or "Item List"

keyValue - the value of a key received on the COMMAND subscription.

fieldName - a item in the configured "Field List"

Returns:

the current value for the specified field of the specified key within the specified item (possibly null), or null if the specified key has not been added yet (note that it might have been added and then deleted).

Throws:

java.lang.IllegalArgumentException - if an invalid field name is specified.

java.lang.IllegalArgumentException - if the specified item position is out of bounds.

java.lang.IllegalStateException - if the Subscription mode is not COMMAND.

getCommandValue

public java.lang.String getCommandValue(java.lang.String itemName,
                                        java.lang.String keyValue,
                                        int fieldPos)

Returns the latest value received for the specified item/key/field combination. This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper SubscriptionListener rather than probing this method.
Note that internal data is cleared when the Subscription is unsubscribed from.

Parameters:

itemName - an item in the configured "Item List"

keyValue - the value of a key received on the COMMAND subscription.

fieldPos - the 1-based position of a field within the configured "Field Schema" or "Field List"

Returns:

the current value for the specified field of the specified key within the specified item (possibly null), or null if the specified key has not been added yet (note that it might have been added and then deleted).

Throws:

java.lang.IllegalArgumentException - if an invalid item name is specified.

java.lang.IllegalArgumentException - if the specified field position is out of bounds.

addSubTable

protected void addSubTable(int item,
                           java.lang.String key)

debugDescriptor

protected void debugDescriptor(java.lang.String debugString,
                               com.lightstreamer.util.Descriptor desc)