Class Subscription
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
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" leveraging the ItemGroup property. - "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" leveraging the Items property or by specifying it in the constructor.
- "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" leveraging the FieldSchema property. - "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 or can contain spaces.
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" leveraging the Fields property or by specifying it in the constructor.
Inherited Members
Namespace: com.lightstreamer.client
Assembly: Lightstreamer.DotNetStandard.Client.dll
Syntax
public class Subscription
Constructors
Subscription(string)
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
subscribe(Subscription) and
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
RequestedMaxFrequency.
Declaration
public Subscription(string subscriptionMode)
Parameters
Type | Name | Description |
---|---|---|
string | subscriptionMode | the subscription mode for the items, required by Lightstreamer Server. Permitted values are:
|
Subscription(string, string, string[])
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
subscribe(Subscription) and
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
RequestedMaxFrequency.
Declaration
public Subscription(string subscriptionMode, string item, string[] fields)
Parameters
Type | Name | Description |
---|---|---|
string | subscriptionMode | the subscription mode for the items, required by Lightstreamer Server. Permitted values are:
|
string | item | the item name to be subscribed to through Lightstreamer Server. |
string[] | fields | an array of fields for the items to be subscribed to through Lightstreamer Server. |
Subscription(string, string[], string[])
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
subscribe(Subscription) and
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
RequestedMaxFrequency.
Declaration
public Subscription(string subscriptionMode, string[] items, string[] fields)
Parameters
Type | Name | Description |
---|---|---|
string | subscriptionMode | the subscription mode for the items, required by Lightstreamer Server. Permitted values are:
|
string[] | items | an array of items to be subscribed to through Lightstreamer server. |
string[] | fields | an array of fields for the items to be subscribed to through Lightstreamer Server. |
Properties
Active
Declaration
public virtual bool Active { get; }
Property Value
Type | Description |
---|---|
bool | Read-only property |
See Also
CommandPosition
Declaration
public virtual int CommandPosition { get; }
Property Value
Type | Description |
---|---|
int | Read-only property |
CommandSecondLevelDataAdapter
Declaration
public virtual string CommandSecondLevelDataAdapter { get; set; }
Property Value
Type | Description |
---|---|
string | Property |
CommandSecondLevelFieldSchema
Declaration
public virtual string CommandSecondLevelFieldSchema { get; set; }
Property Value
Type | Description |
---|---|
string | Property Lifecycle: This method can only be called while the Subscription instance is in its "inactive" state. |
CommandSecondLevelFields
Declaration
public virtual string[] CommandSecondLevelFields { get; set; }
Property Value
Type | Description |
---|---|
string[] | Property |
DataAdapter
Declaration
public virtual string DataAdapter { get; set; }
Property Value
Type | Description |
---|---|
string | Property |
FieldSchema
Declaration
public virtual string FieldSchema { get; set; }
Property Value
Type | Description |
---|---|
string | Property |
Fields
Declaration
public virtual string[] Fields { get; set; }
Property Value
Type | Description |
---|---|
string[] | Property |
ItemGroup
Declaration
public virtual string ItemGroup { get; set; }
Property Value
Type | Description |
---|---|
string | Property |
Items
Declaration
public virtual string[] Items { get; set; }
Property Value
Type | Description |
---|---|
string[] | Property |
KeyPosition
Declaration
public virtual int KeyPosition { get; }
Property Value
Type | Description |
---|---|
int | Read-only property |
Listeners
Returns a list containing the SubscriptionListener instances that were added to this client.
Declaration
public virtual IList<SubscriptionListener> Listeners { get; }
Property Value
Type | Description |
---|---|
IList<SubscriptionListener> | a list containing the listeners that were added to this client. |
See Also
Mode
Declaration
public virtual string Mode { get; }
Property Value
Type | Description |
---|---|
string | Read-only property |
RequestedBufferSize
Declaration
public virtual string RequestedBufferSize { get; set; }
Property Value
Type | Description |
---|---|
string | Property |
RequestedMaxFrequency
Declaration
public virtual string RequestedMaxFrequency { get; set; }
Property Value
Type | Description |
---|---|
string | Property
Default value: null, meaning to lean on the Server default based on the subscription mode. This consists, for all modes, in not applying any frequency limit to the subscription (the same as "unlimited"); see the "General Concepts" document for further details. |
RequestedSnapshot
Declaration
public virtual string RequestedSnapshot { get; set; }
Property Value
Type | Description |
---|---|
string | Property |
Selector
Declaration
public virtual string Selector { get; set; }
Property Value
Type | Description |
---|---|
string | Property |
Subscribed
Declaration
public virtual bool Subscribed { get; }
Property Value
Type | Description |
---|---|
bool | Read-only property |
Methods
addListener(SubscriptionListener)
Adds a listener that will receive events from the Subscription instance.
The same listener can be added to several different Subscription instances.
Lifecycle: A listener can be added at any time. A call to add a listener already present will be ignored.
Declaration
public virtual void addListener(SubscriptionListener listener)
Parameters
Type | Name | Description |
---|---|---|
SubscriptionListener | listener | An object that will receive the events as documented in the SubscriptionListener interface. |
See Also
getCommandValue(int, string, int)
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
(see CommandSecondLevelFields and CommandSecondLevelFieldSchema)
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.
Declaration
public virtual string getCommandValue(int itemPos, string keyValue, int fieldPos)
Parameters
Type | Name | Description |
---|---|---|
int | itemPos | the 1-based position of an item within the configured "Item Group" or "Item List" |
string | keyValue | the value of a key received on the COMMAND subscription. |
int | fieldPos | the 1-based position of a field within the configured "Field Schema" or "Field List" |
Returns
Type | Description |
---|---|
string | 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). |
getCommandValue(int, string, string)
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
(see CommandSecondLevelFields and CommandSecondLevelFieldSchema)
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.
Declaration
public virtual string getCommandValue(int itemPos, string keyValue, string fieldName)
Parameters
Type | Name | Description |
---|---|---|
int | itemPos | the 1-based position of an item within the configured "Item Group" or "Item List" |
string | keyValue | the value of a key received on the COMMAND subscription. |
string | fieldName | a field in the configured "Field List" |
Returns
Type | Description |
---|---|
string | 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). |
getCommandValue(string, string, int)
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
(see CommandSecondLevelFields and CommandSecondLevelFieldSchema)
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.
Declaration
public virtual string getCommandValue(string itemName, string keyValue, int fieldPos)
Parameters
Type | Name | Description |
---|---|---|
string | itemName | an item in the configured "Item List" |
string | keyValue | the value of a key received on the COMMAND subscription. |
int | fieldPos | the 1-based position of a field within the configured "Field Schema" or "Field List" |
Returns
Type | Description |
---|---|
string | 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). |
getCommandValue(string, string, string)
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
(see CommandSecondLevelFields and CommandSecondLevelFieldSchema)
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.
Declaration
public virtual string getCommandValue(string itemName, string keyValue, string fieldName)
Parameters
Type | Name | Description |
---|---|---|
string | itemName | an item in the configured "Item List" |
string | keyValue | the value of a key received on the COMMAND subscription. |
string | fieldName | a field in the configured "Field List" |
Returns
Type | Description |
---|---|
string | 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). |
getValue(int, int)
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(int, string, int) instead.
Note that internal data is cleared when the Subscription is
unsubscribed from.
Returns null if no value has been received yet for the specified item/field pair.
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.
Declaration
public virtual string getValue(int itemPos, int fieldPos)
Parameters
Type | Name | Description |
---|---|---|
int | itemPos | the 1-based position of an item within the configured "Item Group" or "Item List" |
int | fieldPos | the 1-based position of a field within the configured "Field Schema" or "Field List" |
Returns
Type | Description |
---|---|
string | the current value for the specified field of the specified item (possibly null), or null if no value has been received yet. |
getValue(int, string)
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(int, string, string) instead.
Note that internal data is cleared when the Subscription is
unsubscribed from.
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.
Declaration
public virtual string getValue(int itemPos, string fieldName)
Parameters
Type | Name | Description |
---|---|---|
int | itemPos | the 1-based position of an item within the configured "Item Group" or "Item List" |
string | fieldName | a field in the configured "Field List" |
Returns
Type | Description |
---|---|
string | the current value for the specified field of the specified item (possibly null), or null if no value has been received yet. |
getValue(string, int)
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(string, string, int) instead.
Note that internal data is cleared when the Subscription is
unsubscribed from.
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.
Declaration
public virtual string getValue(string itemName, int fieldPos)
Parameters
Type | Name | Description |
---|---|---|
string | itemName | an item in the configured "Item List" |
int | fieldPos | the 1-based position of a field within the configured "Field Schema" or "Field List" |
Returns
Type | Description |
---|---|
string | the current value for the specified field of the specified item (possibly null), or null if no value has been received yet. |
getValue(string, string)
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(string, string, string) instead.
Note that internal data is cleared when the Subscription is
unsubscribed from.
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.
Declaration
public virtual string getValue(string itemName, string fieldName)
Parameters
Type | Name | Description |
---|---|---|
string | itemName | an item in the configured "Item List" |
string | fieldName | a field in the configured "Field List" |
Returns
Type | Description |
---|---|
string | the current value for the specified field of the specified item (possibly null), or null if no value has been received yet. |
removeListener(SubscriptionListener)
Removes a listener from the Subscription instance so that it will not receive events anymore.
Lifecycle: a listener can be removed at any time.
Declaration
public virtual void removeListener(SubscriptionListener listener)
Parameters
Type | Name | Description |
---|---|---|
SubscriptionListener | listener | The listener to be removed. |