lightstreamer_adapter.interfaces package

Submodules

lightstreamer_adapter.interfaces.data module

This module contains all ABC classes and exceptions needed to create and manage a Remote Data Adapter.

class lightstreamer_adapter.interfaces.data.DataProvider

Bases: object

Provides an abstract class meant to be extended by a Remote Data Adapter in order to attach a Data Provider to Lightstreamer. An instance of a Remote Data Adapter is supplied to Lightstreamer through a lightstreamer_adapter.server.DataProviderServer instance. After initialization, Lightstreamer sets itself as the Remote Data Adapter listener, by calling the set_listener() method.

Data Providers are used by Lightstreamer Kernel to obtain all data to be pushed to the Clients. Any Item requested by a Client must refer to one supplied by the configured Data Adapters.

A Data Provider supplies data in a publish/subscribe way. Lightstreamer asks for data by calling the subscribe() and unsubscribe() methods for various Items and the Data Adapter sends ItemEvents to its listener in an asynchronous way.

A Data Adapter can also support Snapshot management. Upon subscription to an Item, the current state of the Item data can be sent to the Server before the updates. This allows the Server to maintain the Item state, by integrating the new ItemEvents into the state (in a way that depends on the Item type) and to make this state available to the Clients.

Note that the interaction between the Server and the Data Adapter and the interaction between the Server and any Client are independent activities. As a consequence, the very first ItemEvents sent by the Data Adapter to the Server for an Item just subscribed to might be processed before the Server starts feeding any client, even the client that caused the subscription to the Item to be invoked; then, such events would not be forwarded to any client. If it is desirable that a client receives all the ItemEvents that have been produced for an Item by the Data Adapter since subscription time, then the support for the Item Snapshot can be leveraged.

Lightstreamer Kernel ensures that calls to subscribe() and unsubscribe() for the same Item will be interleaved, without redundant calls; whenever subscribe raises an exception, the corresponding unsubscribe call is not issued.

initialize(parameters, config_file=None)

Called by the Remote Server to provide initialization information to the Data Adapter. The call must not be blocking; any polling cycle or similar must be started in a different thread. If an exception occurs in this method, Lightstreamer Kernel can’t complete the startup and must exit. The initialization information can be supplied in different ways, depending on the way the Remote Server is launched.

The call must not be blocking; any polling cycle or similar must be started in a different thread. Any delay in returning from this call will in turn delay the Server initialization. If an exception occurs in this method, Lightstreamer Server can’t complete the startup and must exit.

Parameters:
  • parameters (dict) –

    A dictionary object that contains key-value pairs corresponding to the parameters elements supplied for the Data Adapter configuration. Both key and values are represented as string objects.

    The parameters can be supplied through the lightstreamer_adapter.server.DataProviderServer.adapter_params() property of the DataProviderServer instance. More parameters can be added by leveraging the init_remote parameter in the Proxy Adapter configuration.

  • config_file (str) –

    The path on the local disk of the Data Adapter configuration file.

    The file path can be supplied by assigning the lightstreamer_adapter.server.DataProviderServer.adapter_config() property of the DataProviderServer instance used.
Raises:

lightstreamer_adapter.interfaces.data.DataProviderError – in case an error occurs that prevents the correct behavior of the Data Adapter.
set_listener(event_listener)

Called by the Remote Server to provide a listener to receive the Item Events carrying data and asynchronous error notifications for Lightstreamer Kernel. The listener is set before any subscribe is called and is never changed.

Parameters:event_listener (ItemEventListener) – A listener.
subscribe(item_name)

Called by Lightstreamer Remote Server to request data for an Item. If the request succeeds, the Remote Data Adapter can start sending an ItemEvent to the listener for any update of the Item value. Before sending the updates, the Remote Data Adapter may optionally send one or more ItemEvents to supply the current Snapshot.

The general rule to be followed for event dispatching is:

if issnapshot_available(itemName) == true
    SNAP* [EOS] UPD*
else
    UPD*

where:

The composition of the snapshot depends on the Mode in which the Item is to be processed. In particular, for MERGE mode, the snapshot consists of one event and the first part of the rule becomes:

[SNAP] [EOS] UPD*

where a missing snapshot is considered as an empty snapshot.

If an Item can be requested only in RAW mode, then DataProvider.issnapshot_available() should always return False; anyway, when an Item is requested in RAW mode, any snapshot is discarded.

Note that calling ItemEventListener.end_of_snapshot() is not mandatory; however, not calling it in DISTINCT or COMMAND mode may cause the server to keep the snapshot and forward it to the clients only after the first no-shapshot event has been received. The same happens for MERGE mode if neither the snapshot nor the endOfSnapshot call are supplied.

Unexpected snapshot events are converted to non-snapshot events (but for RAW mode, where they are ignored); unexpected ItemEventListener.end_of_snapshot() calls are ignored.

The method can be blocking, but, as the Proxy Adapter implements subscribe and unsubscribe asynchronously, subsequent subscribe-unsubscribe-subscribe-unsubscribe requests can still be issued by Lightstreamer Server to the Proxy Adapter. When this happens, the requests may be queued on the Remote Adapter, hence some Subscribe calls may be delayed.

Parameters:

item_name (str) – Name of an Item.
Raises:
unsubscribe(item_name)

Called by Lightstreamer Kernel through the Remote Server to end a previous request of data for an Item. After the call has returned, no more ItemEvents for the Item should be sent to the listener until requested by a new subscription for the same Item.

The method can be blocking, but, as the Proxy Adapter implements subscribe and unsubscribe asynchronously, subsequent subscribe-unsubscribe-subscribe-unsubscribe requests can still be issued by Lightstreamer Server to the Proxy Adapter. When this happens, the requests may be queued on the Remote Adapter, hence some Subscribe calls may be delayed.

Parameters:

item_name (str) – Name of an Item.
Raises:
issnapshot_available(item_name)

Called by Lightstreamer Kernel through the Remote Server to know whether the Data Adapter, after a subscription for an Item, will send some Snapshot Item Events before sending the updates. An Item Snapshot can be represented by zero, one or more Item Events, also depending on the Item type. The decision whether to supply or not to supply Snapshot information is entirely up to the Data Adapter.

The method should be nonblocking. The availability of the snapshot for an Item should be a known architectural property. When the snapshot, though expected, cannot be obtained at subscription time, then it can only be considered as empty.

Parameters:item_name (str) – Name of an Item.
Return bool:True if Snapshot information will be sent for this Item before the updates.
Raises:lightstreamer_adapter.interfaces.data.SubscribeError – in case the Data Adapter is unable to answer to the request.
class lightstreamer_adapter.interfaces.data.ItemEventListener

Bases: object

Internally implemented abstract interface, used by Lightstreamer Kernel to receive the Item Events and any asynchronous severe error notification from the Data Adapter. The listener instance is supplied to the Data Adapter by Lightstreamer Kernel (through the Remote Server) through a DataProvider.set_listener() call. The listener can manage Item Events implemented as dictionary objects, whose values can be expressed either as a string or as a bytes (the special mandatory fields for COMMAND Mode named key and command must be encoded as string).

When an Item Event instance has been sent to the listener, it is totally owned by Lightstreamer and it must not be anymore changed by the Data Adapter. The Remote Server may also hold the object for some time after the listener call has returned.

update(item_name, item_event, issnapshot)

Called by a Data Adapter to send an Item Event implemented as dictionary object to Lightstreamer Kernel.

The Remote Adapter should ensure that, after an DataProvider.unsubscribe() call for the Item has returned, no more Update calls are issued, until requested by a new subscription for the same Item. This assures that, upon a new subscription for the Item, no trailing events due to the previous subscription can be received by the Remote Server. Note that the method is nonblocking; moreover, it only takes locks to first order mutexes; so, it can safely be called while holding a custom lock.

Parameters:
  • item_name (str) – The name of the Item whose values are carried by the Item Event.
  • item_event (dict) – A dictionary object, in which every key-value pair represents a Field of the Item Event. A Field value can be expressed as either a string or a bytes, the latter case being the most efficient, though restricted to the ISO-8859-1 (ISO-LATIN-1) character set. A Field value can be None or missing if the Field is not to be reported in the event.
  • issnapshot (bool) – True if the Item Event carries the Item Snapshot.
end_of_snapshot(item_name)

Called by a Data Adapter to signal to Lightstreamer Kernel that no more Item Event belonging to the Snapshot are expected for an Item. This call is optional, because the Snapshot completion can also be inferred from the issnapshot flag in the update calls. However, this call allows Lightstreamer Kernel to be informed of the Snapshot completion before the arrival of the first non-snapshot event. Calling this function is recommended if the Item is to be subscribed in DISTINCT mode. In case the Data Adapter returned False to DataProvider.issnapshot_available() for the same Item, this function should not be called.

The Remote Adapter should ensure that, after an DataProvider.unsubscribe() call for the Item has returned, a possible pending end_of_snapshot call related with the previous subscription request is no longer issued. This assures that, upon a new subscription for the Item, no trailing events due to the previous subscription can be received by the Remote Server. Note that the method is nonblocking; moreover, it only takes locks to first order mutexes; so, it can safely be called while holding a custom lock.

Parameters:item_name (str) – The name of the Item whose snapshot has been completed
clear_snapshot(item_name)

Called by a Data Adapter to signal to Lightstreamer Kernel that the current Snapshot of the Item has suddenly become empty. More precisely:

  • for subscriptions in MERGE mode, the current state of the Item will be cleared, as though an update with all fields valued as null were issued;
  • for subscriptions in COMMAND mode, the current state of the Item will be cleared, as though a DELETE event for each key were issued;
  • for subscriptions in DISTINCT mode, a suitable notification that the Snapshot for the Item should be cleared will be sent to all the clients currently subscribed to the Item (clients based on some old client library versions may not be notified); at the same time, the current recent update history kept by the Server for the Item will be cleared and this will affect the Snapshot for new subscriptions;
  • for subscriptions in RAW mode, there will be no effect.

Note that this is a real-time event, not a Snapshot event; hence, in order to issue this call, it is not needed that the Data Adapter has returned True to DataProvider.issnapshot_available() for the specified Item; moreover, if invoked while the Snapshot is being supplied, the Kernel will infer that the Snapshot has been completed.

The Adapter should ensure that, after an DataProvider.unsubscribe() call for the Item has returned, a possible pending DataProvider.clear_snapshot() call related with the previous subscription request is no longer issued. This assures that, upon a new subscription for the Item, no trailing events due to the previous subscription can be received by the Kernel. Note that the method is nonblocking; moreover, it only takes locks to first order mutexes; so, it can safely be called while holding a custom lock.

Parameters:item_name (str) – The name of the Item whose Snapshot has become empty.
failure(exception)

Called by a Data Adapter to notify Lightstreamer Kernel of the occurrence of a severe problem that can compromise future operation of the Data Adapter.

Parameters:exception (Exception) – Any Excetion object, with the description of the problem.
exception lightstreamer_adapter.interfaces.data.DataError(msg)

Bases: Exception

Base class for all exceptions directly raised by the Data Adapter.

msg

The detail message

Type:str
exception lightstreamer_adapter.interfaces.data.DataProviderError(msg)

Bases: lightstreamer_adapter.interfaces.data.DataError

Raised by the DataProvider.initialize() method if there is some problem that prevents the correct behavior of the Data Adapter. If this exception occurs, Lightstreamer Kernel must give up the startup.

exception lightstreamer_adapter.interfaces.data.SubscribeError(msg)

Bases: lightstreamer_adapter.interfaces.data.DataError

Raised by the DataProvider.subscribe() and DataProvider.unsubscribe() methods if the request cannot be satisfied.

exception lightstreamer_adapter.interfaces.data.FailureError(msg)

Bases: lightstreamer_adapter.interfaces.data.DataError

Raised by the DataProvider.subscribe() and DataProvider.unsubscribe() methods if the method execution has caused a severe problem that can compromise future operation of the Data Adapter.

lightstreamer_adapter.interfaces.metadata module

This module contains all classes, enums and exceptions needed to create and manage a Remote Metadata Adapter.

class lightstreamer_adapter.interfaces.metadata.MetadataProvider

Bases: object

Provides a base class to be extended by a Remote Metadata Adapter in order to attach a Metadata Provider to Lightstreamer.

To facilitate the coding of the Adapter, each method provides a default implementation to allow a simple default behavoiur, which can be overridden by extending this class and supplying the custom implementation.

Such default behavoiur will be specified in this documentation trough the use of the marker: IMPLEMENTATION NOTE.

An instance of a Remote Metadata Adapter is supplied to Lightstreamer through a lightstreamer_adapter.server.MetadataProviderServer instance.

A Metadata Provider is used by Lightstreamer Kernel in combination with one or multiple Data Providers, uniquely associated with it; it is consulted in order to manage the push Requests intended for the associated Data Providers. A Metadata Provider supplies information for several different goals:

  • the resolution of the Group/Schema names used in the Requests;
  • the check of the User accessibility to the requested Items;
  • the check of the resource level granted to the User;
  • the request for specific characteristics of the Items.

Note: Each Item may be supplied by one or more of the associated Data Adapters and each client Request must reference to a specific Data Adapter. However, in the current version of the interface, no Data Adapter information is supplied to the Metadata Adapter methods. Hence, the Item names must provide enough information for the methods to give an answer. As a consequence, for instance, the frequency, snapshot length and other characteristics of an item are the same regardless of the Data Adapter it is requested from. More likely, for each item name defined, only one of the Data Adapters in the set is responsible for supplying that item.

All implementation methods should perform as fast as possible. See the notes on the corresponding methods in the Java In-Process interface for the method-related details. Also consider that the roundtrip time involved in the remote call adds up to each call time anyway.

In order to avoid that delays on calls for one session propagate to other sessions, the size of the thread pool devoted to the management of the client requests should be properly set, through the <server_pool_max_size> flag, in the Server configuration file.

Alternatively, a dedicated pool, properly sized, can be defined for the involved Adapter Set in the adapters.xml. Still more restricted dedicated pools can be defined for the authorization-related calls and for each Data Adapter in the Adapter Set. The latter pool would also run any Metadata Adapter method related to the items supplied by the specified Data Adapter.

initialize(parameters, config_file=None)

Called by Lightstreamer Kernel through the Remote Server to provide initialization information to the Metadata Adapter.

The call must not be blocking; any polling cycle or similar must be started in a different thread. Any delay in returning from this call will in turn delay the Server initialization. If an exception occurs in this method, Lightstreamer Kernel can’t complete the startup and must exit.

Parameters:
  • parameters (dict) – A dictionary object that contains key-value pairs corresponding to the parameters elements supplied for the Metadata Adapter configuration. Both key and values are represented as string objects. The parameters can be supplied through the lightstreamer_adapter.server.MetadataProviderServer.adapter_params() property of the MetadataProviderServer instance. More parameters can be added by leveraging the init_remote parameter in the Proxy Adapter configuration.
  • config_file (str) – The path on the local disk of the Metadata Adapter configuration file. The file path can be supplied through the lightstreamer_adapter.server.MetadataProviderServer.adapter_config() propery of the used MetadataProviderServer instance.
Raises:

lightstreamer_adapter.interfaces.metadata.MetadataProviderError – (never raised in the default implementation) in case an error occurs that prevents the correct behavior of the Metadata Adapter.

IMPLEMENTATION NOTE: does nothing.

notify_user(user, password, http_headers)

Called by Lightstreamer Kernel through the Remote Server as a preliminary check that a user is enabled to make Requests to the related Data Providers. It is invoked upon each session request and it is called prior to any other session-related request. So, any other method with a User argument can assume that the supplied User argument has already been checked.

The User authentication should be based on the user and password arguments supplied by the client. The full report of the request HTTP headers is also available; they could be used in order to gather information about the client, but should not be used for authentication, as they may not be under full control by client code. See also the discussion about the <use_protected_js> Server configuration element, if available.

This method runs in the Server authentication thread pool, if defined.

Parameters:
  • user (str) – A User name.
  • password (str) – A password optionally required to validate the User.
  • http_headers (dict) –

    A dictionary object that contains a key-value pair for each header found in the HTTP request that originated the call. The header names are reported in lower-case form.

    For headers defined multiple times, a unique key-value pair is reported, where the value is a concatenation of all the supplied header values, separated by a “,”. One pair is added by Lightstreamer Server; the name is “REQUEST_ID” and the value is a unique id assigned to the client request.
Raises:

IMPLEMENTATION NOTE: does nothing.

notify_user_with_principal(user, password, http_headers, client_principal=None)

Called by Lightstreamer Kernel, through the Remote Server, instead of calling the notify_user() method, in case the Server has been instructed to acquire the client principal from the client TLS/SSL certificate through the <use_client_auth> configuration flag.

Note that the above flag can be set for each listening port independently (and it can be set for TLS/SSL ports only), hence, both methods may be invoked, depending on the port used by the client. Also note that in case client certificate authentication is not forced on a listening port through <force_client_auth>, a client request issued on that port may not be authenticated, hence it may have no principal associated. In that case, if <use_client_auth> is set, this method will still be invoked, with None principal.

See notify_user() for other notes.

Edition Note: https is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Parameters:
  • user (str) – A User name.
  • password (str) – A password optionally required to validate the User.
  • http_headers (dict) –

    A dictionary object that contains a key-value pair for each header found in the HTTP request that originated the call. The header names are reported in lower-case form.

    For headers defined multiple times, a unique key-value pair is reported, where the value is a concatenation of all the supplied header values, separated by a “,”. One pair is added by Lightstreamer Server; the name is “REQUEST_ID” and the value is a unique id assigned to the client request.

  • client_principal (str) – the identification name reported in the client TLS/SSL certificate supplied on the socket connection used to issue the request that originated the call; it can be not specified if client has not authenticated itself or the authentication has failed.
Raises:

IMPLEMENTATION NOTE: invokes the notify_user() method, where the client_principal argument is discarded.

get_items(user, session_id, group)

Called by Lightstreamer Kernel through the Remote Server to resolve an Item Group name (or Item List specification) supplied in a Request. The names of the Items in the Group must be returned. For instance, the client could be allowed to specify the “NASDAQ100” Group name and, upon that, the list of all items corresponding to the stocks included in that index could be returned.

Possibly, the content of an Item Group may be dependant on the User who is issuing the Request or on the specific Session instance.

When an Item List specification is supplied, it is made of a space-separated list of the names of the Items in the List. This convention is used by some of the subscription methods provided by the various client libraries.

When any of these interface methods is used by client code accessing this Remote Metadata Adapter, the supplied “group” argument should be inspected as a space-separated list of Item names and an array with these names in the same order should be returned.

Another typical case is when the same Item has different contents depending on the User that is issuing the request. On the Data Adapter side, different Items (one for each User) can be used; nevertheless, on the client side, the same name can be specified in the subscription request and the actual user-related name can be determined and returned here. For instance:

if group == "portfolio":
    item_name = "PF_" + user
    return [item_name]
elif group.startswith("PF"):
    # protection from unauthorized use of user-specific items
    raise ItemsError("Unexpected group name");

Obviously, the two above techniques can be combined, hence any element of an Item List can be replaced with a decorated or alternative Item name: the related updates will be associated to the original name used in the supplied Item List specification by client library _code.

This method runs in the Server thread pool specific for the Data Adapter that supplies the involved Items, if defined.

Parameters:
  • user (str) – A User name.
  • session_id (str) – The ID of a Session owned by the User.
  • group (str) – An Item Group name (or Item List specification).
Returns:

A list of the names of the Items in the Group.
Return type:

list of strings
Raises:

lightstreamer_adapter.interfaces.metadata.ItemsError – if the supplied Item Group name (or Item List specification) is not recognized.

IMPLEMENTATION NOTE: handles Item List specifications, therefore the result is simply a list of all space-separated names forming the Item Group Name.

get_schema(user, session_id, group, schema)

Called by Lightstreamer Kernel through the Remote Server to resolve a Field Schema name (or Field List specification) supplied in a Request. The names of the Fields in the Schema must be returned.

Possibly, the content of a Field Schema may be dependent on the User who is issuing the Request, on the specific Session instance or on the Item Group (or Item List) to which the Request is related.

When a Field List specification is supplied, it is made of a space-separated list of the names of the Fields in the Schema. This convention is used by some of the subscription methods provided by the various client libraries.

When any of these interface methods is used by client code accessing this Remote Metadata Adapter, the supplied “schema” argument should be inspected as a space-separated list of Field names and an array with these names in the same order should be returned; returning decorated or alternative Field names is also possible: they will be associated to the corresponding names used in the supplied Field List specification by client library client_error_code.

This method runs in the Server thread pool specific for the Data Adapter that supplies the involved Items, if defined.

Parameters:
  • user (str) – A User name.
  • session_id (str) – The ID of a Session owned by the User.
  • group (str) – The name of the Item Group (or specification of the Item List) whose Items the Schema is to be applied to.
  • schema (str) – A Field Schema name (or Field List specification).
Returns:

A list of the names of the Fields in the Schema
Return type:

list of string
Raises:

IMPLEMENTATION NOTE: handles Field List specifications, therefore the result is simply a list of all space-separated names forming the Field Schema.

get_allowed_max_bandwidth(user)

Called by Lightstreamer Kernel through the Remote Server to ask for the bandwidth level to be allowed to a User for a push Session.

This method runs in the Server authentication thread pool, if defined.

Edition Note: Bandwidth Control is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Parameters:user (str) – An User
Returns:The allowed bandwidth, in Kbit/sec. A zero return value means an unlimited bandwidth.
Return type:float

IMPLEMENTATION NOTE: Always returns a zero value.

get_allowed_max_item_frequency(user, item)

Called by Lightstreamer Kernel through the Remote Server to ask for the ItemUpdate frequency to be allowed to a User for a specific Item. An unlimited frequency can also be specified. Such filtering applies only to Items requested with publishing Mode MERGE, DISTINCT and COMMAND (in the latter case, the frequency limitation applies to the UPDATE events for each single key). If an Item is requested with publishing Mode MERGE, DISTINCT or COMMAND and unfiltered dispatching has been specified, then returning any limited maximum frequency will cause the refusal of the request by the Kernel.

This method runs in the Server thread pool specific or the Data Adapter that supplies the involved items, if defined.

Edition Note: A further global frequency limit could also be imposed by the Server, depending on Edition and License Type; this specific limit also applies to RAW mode and to unfiltered dispatching. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Parameters:
  • user (str) – An User
  • item (str) – An Item name
Returns:

The allowed Update frequency, in Updates/sec. A zero return value means no frequency restriction.
Return type:

float

IMPLEMENTATION NOTE: always returns zero, to mean no frequency limit. This also enables unfiltered dispatching for Items subscribed in MERGE or DISTINCT mode.

get_allowed_buffer_size(user, item)

Called by Lightstreamer Kernel through the Remote Server to ask for the maximum size allowed for the buffer internally used to enqueue subsequent ItemUpdates for the same Item. If this buffer is more than 1 element deep, a short burst of ItemEvents from the Data Adapter can be forwarded to the Client without losses, though with some delay. The buffer size is specified in the Request. Its maximum allowed size can be different for different Users. Such buffering applies only to Items requested with publishing Mode MERGE or DISTINCT. However, if the Item has been requested with unfiltered dispatching, then the buffer size is always unlimited and buffer size settings are ignored.

This method runs in the Server thread pool specific for the Data Adapter that supplies the involved items, if defined.

Parameters:
  • user (str) – An User
  • item (str) – A Item Name
Returns:

The allowed buffer size. A zero return value means a potentially unlimited buffer.
Return type:

int

IMPLEMENTATION NOTE: always returns zero, to mean no size limit.

ismode_allowed(user, item, mode)

Called by Lightstreamer Kernel through the Remote Server to ask for the allowance of a publishing Mode for an Item. A publishing Mode can or cannot be allowed depending on the User. The Metadata Adapter should ensure that conflicting Modes are not both allowed for the same Item (even for different Users), otherwise some Requests will be eventually refused by Lightstreamer Kernel. The conflicting Modes are MERGE, DISTINCT and COMMAND.

This method runs in the Server thread pool specific for the Data Adapter that supplies the involved items, if defined.

Parameters:
  • user (str) – A User name.
  • item (str) – An Item Name.
  • mode (Mode) – A publishing Mode.
Returns:

True if the publishing Mode is allowed.
Return type:

bool

IMPLEMENTATION NOTE: always return True. As a consequence, conflicting Modes may be both allowed for the same Item, so the Clients should ensure that the same Item cannot be requested in two conflicting Modes.

mode_may_be_allowed(item, mode)

Called by Lightstreamer Kernel through the Remote Server to ask for the allowance of a publishing Mode for an Item (for at least one User). The Metadata Adapter should ensure that conflicting Modes are not both allowed for the same Item. The conflicting Modes are MERGE, DISTINCT and COMMAND.

This method runs in the Server thread pool specific for the Data Adapter that supplies the involved items, if defined.

Parameters:
  • item (str) – An Item Name.
  • mode (Mode) – A publishing Mode.
Returns:

True if the publishing Mode is allowed.
Return type:

bool

IMPLEMENTATION NOTE: always return True. As a consequence, conflicting Modes may be both allowed for the same Item, so the Clients should ensure that the same Item cannot be requested in two conflicting Modes. This is just to simplify the development phase; the implementation of the overriding method MUST be different, to ensure that conflicting modes (i.e. MERGE, DISTINCT and COMMAND) are not both allowed for the same Item.

get_min_source_frequency(item)

Called by Lightstreamer Kernel through the Remote Server to ask for the minimum ItemEvent frequency from the Data Adapter at which the events for an Item are guaranteed to be delivered to the Clients without loss of information. In case of an incoming ItemEvent frequency greater than this value, Lightstreamer Kernel may prefilter the events. Such prefiltering applies only for Items requested with publishing Mode MERGE or DISTINCT. The frequency set should be greater than the ItemUpdate frequencies allowed to the different Users for that Item. Moreover, because this filtering is made without buffers, the frequency set should be far greater than the ItemUpdate frequencies allowed for that Item for which buffering of event bursts is desired. If an Item is requested with publishing Mode MERGE or DISTINCT and unfiltered dispatching, then specifying any limited source frequency will cause the refusal of the request by the Kernel. This feature is just for ItemEventBuffers protection against Items with a very fast flow on the Data Adapter and a very slow flow allowed to the Clients. If this is the case, but just a few Clients need a fast or unfiltered flow for the same MERGE or DISTINCT Item, the use of two differently named Items that receive the same flow from the Data Adapter is suggested.

This method runs in the Server thread pool specific for the Data Adapter that supplies the involved items, if defined.

Parameters:item – An Item Name.
Returns:The minimum ItemEvent frequency that must be processed without loss of information, in ItemEvents/sec. A zero return value indicates that incoming ItemEvents must not be prefiltered. If the ItemEvents frequency for the Item is known to be very low, returning zero allows Lightstreamer Kernel to save any prefiltering effort.
Return type:float

IMPLEMENTATION NOTE: The Metadata Adapter can’t set any minimum frequency; this also enables unfiltered dispatching for Items subscribed in MERGE or DISTINCT mode. Therefore the method always returns zero, to mean that incoming ItemEvents must not be prefiltered.

get_distinct_snapshot_length(item)

Called by Lightstreamer Kernel through the Remote Server to ask for the maximum allowed length for a Snapshot of an Item that has been requested with publishing Mode DISTINCT. In fact, in DISTINCT publishing Mode, the Snapshot for an Item is made by the last events received for the Item and the Client can specify how many events it would like to receive. Thus, Lightstreamer Kernel must always keep a buffer with some of the last events received for the Item and the length of the buffer is limited by the value returned by this method. The maximum Snapshot size cannot be unlimited.

This method runs in the Server thread pool specific for the Data Adapter hat supplies the involved items, if defined.

Parameters:item (str) – An Item Name.
Returns:The maximum allowed length for the Snapshot; a zero return value means that no Snapshot information should be kept.
Return type:int

IMPLEMENTATION NOTE: always return a value of 0, to mean that no events are specified, so snapshot will not be managed

notify_user_message(user, session_id, message)

Called by Lightstreamer Kernel through the Remote Server to forward a message received by a User. The interpretation of the message is up to the Metadata Adapter. A message can also be refused.

This method runs in the Server thread pool specific for the Adapter Set, if defined.

Parameters:
  • user (str) – A User name.
  • session_id (str) – The ID of a Session owned by the User.
  • message (str) – A string.
Raises:
IMPLEMENTATION NOTE: the Metadata Adapter does never accept the
message, therefore a CreditsError is raised.
notify_new_session(user, session_id, client_context)

Called by Lightstreamer Kernel through the Remote Server to check that a User is enabled to open a new push Session. If the check succeeds, this also notifies the Metadata Adapter that the Session is being assigned to the User.

Request context information is also available; this allows for differentiating group, schema and message management based on specific Request characteristics.

This method runs in the Server thread pool specific for the Adapter Set, if defined.

Parameters:
  • user (str) – A User name.
  • session_id (str) – The ID of a new Session.
  • client_context (dict) –

    A dictionary object that contains key-value pairs with various information about the request context. All values are supplied as strings. Information related to a client connection refers to the HTTP request that originated the call. Available keys are:

    • ”REMOTE_IP” - string representation of the remote IP related to the current connection; it may be a proxy address
    • ”REMOTE_PORT” - string representation of the remote port related to the current connection
    • ”USER_AGENT” - the user-agent as declared in the current connection HTTP header
    • ”FORWARDING_INFO” - the content of the X-Forwarded-For HTTP header related to the current connection; intermediate proxies usually set this header to supply connection routing information
    • ”LOCAL_SERVER” - the name of the specific server socket that handles the current connection, as configured through the <http_server> or <https_server> element
    • ”CLIENT_TYPE” - the type of client API in use; the value may be null for some old client APIs
    • ”CLIENT_VERSION” - the signature, including version and build number, of the client API in use; the signature may be only partially complete, or even null, for some old client APIs and for some custom clients
    • ”REQUEST_ID” - the same id that has just been supplied to notify_user() method for the current client request instance; this allows for using local authentication-related details for the authorization task. Note: the Remote Adapter is responsible for disposing any cached information in case this method is not called because of any early error during request management.
Raises:

IMPLEMENTATION NOTE: does nothing.

notify_session_close(session_id)

Called by Lightstreamer Kernel through the Remote Server to notify the Metadata Adapter that a push Session has been closed.

This method is called by the Server asynchronously and does not consume a pooled thread on the Server. As a consequence, it is not guaranteed that no more calls related with this sessionID, like notify_new_tables, notify_tables_close, and get_items can occur after its invocation on parallel threads. Accepting them would have no effect. However, if the method may have side-effects on the Adapter, like notify_user_message, the Adapter is responsible for checking if the session is still valid.

Parameters:session_id (str) – A Session ID.
Raises:lightstreamer_adapter.interfaces.metadata.NotificationError – in case something is wrong in the parameters, such as the ID of a Session that is not currently open.

IMPLEMENTATION NOTE: does nothing, because the Metadata Adapter doesn’t need to remember the open Sessions

wants_tables_notification(user)

Called by Lightstreamer Kernel through the Remote Server to know whether the Metadata Adapter must or must not be notified any time a Table (i.e. Subscription) is added or removed from a push Session owned by a supplied User. If this method returns False, the methods notify_new_tables() and notify_tables_close() will never be called for this User, saving some processing time. In this case, the User will be allowed to add to his Sessions any Tables (i.e. Subscriptions) he wants.

This method runs in the Server authentication thread pool, if defined.

Parameters:user (str) – A User name.
Returns:True if the Metadata Adapter must be notified any time a Table (i.e. Subscription) is added or removed from a Session owned by the User.
Return type:bool

IMPLEMENTATION NOTE: always return False, to prevent being notified with notify_new_tables() and notify_tables_close(), as the the Metadata Adapter doesn’t require such notifications in this default implementation.

notify_new_tables(user, session_id, tables)

Called by Lightstreamer Kernel through the Remote Server to check that a User is enabled to add some Tables (i.e. Subscriptions) to a push Session. If the check succeeds, this also notifies the Metadata Adapter that the Tables are being added to the Session.

The method is invoked only if enabled for the User through wants_tables_notification().

This method runs in the Server thread pool specific for the Data Adapter that supplies the involved items, if defined.

Parameters:
  • user (str) – A User name.
  • session_id (str) – The ID of a Session owned by the User.
  • tables (list) – A list of TableInfo instances, each of them containing the details of a Table (i.e. Subscription) to be added to the Session. The elements in the list represent Tables (i.e.: Subscriptions) whose subscription is requested atomically by the client. A single element should be expected in the list, unless clients based on a very old version of a client library or text protocol may be in use.
Raises:

IMPLEMENTATION NOTE: unless the wants_tables_notification() method is overridden, this method will never be called.

notify_tables_close(session_id, tables)

Called by Lightstreamer Kernel through the Remote Server to notify the Metadata Adapter that some Tables (i.e. Subscriptions) have been removed from a push Session.

The method is invoked only if enabled for the User through wants_tables_notification().

This method is called by the Server asynchronously and does not consume a pooled thread on the Server.

Parameters:
  • session_id (str) – A Session ID.
  • tables (list) – A list of TableInfo instance each of them containing the details of a Table (i.e. Subscription) that has been removed from the Session. The supplied list is in 1:1 correspondence with the list supplied by notify_new_tables() in a previous call; the correspondence can be recognized by matching the TableInfo.win_index() property of the included TableInfo objects if multiple objects are included, it must be the same for all of them).
Raises:

lightstreamer_adapter.interfaces.metadata.NotificationError – in case something is wrong in the parameters, such as the ID of a Session that is not currently open or a Table (i.e. Subscription) that is not contained in the Session.

IMPLEMENTATION NOTE: does nothing, because the Metadata Adapter doesn’t need to remember the open Sessions.

notify_mpn_device_access(user, session_id, device)

Called by Lightstreamer Kernel through the Remote Server to check that a User is enabled to access the specified MPN device. The success of this method call is a prerequisite for all MPN operations, including the activation of a subscription, the deactivation of a subscription, the change of a device token, etc. Some of these operations have a subsequent specific notification, i.e. notify_mpn_subscription_activation() and notify_mpn_device_token_change().

Take particular precautions when authorizing device access, if possible ensure the user is entitled to the specific platform, device token and application ID.

Edition Note: Push Notifications is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Parameters:
  • user (str) – A User name.
  • session_id (str) – The ID of a Session owned by the User.
  • device (MpnDeviceInfo) – Specifies an MPN device.

IMPLEMENTATION NOTE: does nothing.

notify_mpn_subscription_activation(user, session_id, table, mpn_subscription)

Called by Lightstreamer Kernel through the Remote Server to check that a User is enabled to activate a Push Notification subscription. If the check succeeds, this also notifies the Metadata Adapter that Push Notifications are being activated.

Take particular precautions when authorizing subscriptions, if possible check for validity the trigger expression reported by the MpnSubscriptionInfo.trigger() property, as it may contain maliciously crafted code. The MPN notifiers configuration file contains a first-line validation mechanism based on regular expression that may also be used for this purpose.

Edition Note: Push Notifications is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Parameters:
  • user (str) – User name.
  • session_id (str) – The ID of a Session owned by the User. The session ID is provided for a thorough validation of the Table information, but Push Notification subscriptions are persistent and survive the session. Thus, any association between this Session ID and this Push Notification subscription should be considered temporary.
  • table (TableInfo) – A TableInfo instance, containing the details of a Table (i.e.: Subscription) for which Push Notification have to be activated.
  • mpn_subscription (MpnSubscriptionInfo) – A MpnSubscriptionInfo instance, containing the platform specific details of a PushNotification to be activated.
Raises:

IMPLEMENTATION NOTE: does nothing.

notify_mpn_device_token_change(user, session_id, device, new_device_token)

Called by Lightstreamer Kernel through the Remote Server to check that a User is enabled to change the token of an MPN device. If the check succeeds, this also notifies the Metadata Adapter that future client requests should be issued by specifying the new device token.

Take particular precautions when authorizing device token changes, if possible ensure the user is entitled to the new device token.

Edition Note: Push Notifications is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Parameters:
  • user (str) – A User name.
  • session_id (str) – The ID of a Session owned by the User.
  • device (MpnDeviceInfo) – Specifies an MPN device.
  • new_device_token (str) – The new token being assigned to the device.
Raises:

IMPLEMENTATION NOTE: does nothing.

class lightstreamer_adapter.interfaces.metadata.Mode

Bases: enum.Enum

Encapsulates a publishing Mode. The different Modes handled by Lightstreamer Kernel can be uniquely identified by the static constants defined in this class. See the technical documents for a detailed description of Modes.

RAW = 'R'

The RAW Mode

MERGE = 'M'

The MERGE Mode

DISTINCT = 'D'

The DISTINCT Mode

COMMAND = 'C'

The COMMAND Mode

class lightstreamer_adapter.interfaces.metadata.MpnPlatformType

Bases: enum.Enum

Identifies a Push Notifications platform type, used with MPN-related requests of the MetadataProvider. It is used by Lightstreamer to specify the platform associated with the notified client requests

The available constants refer to the platform types currently supported.

Edition Note: Push Notifications is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

APPLE = 'A'

Refers to Push Notifications for APPLE platforms, such as iOS, macOS and tvOS. The back-end service for APPLE platforms is APNs (“APPLE Push Notification service”). APPLE, iOS, macOS and tvOS are registered trademarks of APPLE, Inc.

GOOGLE = 'G'

Refers to Push Notifications for GOOGLE platforms, such as Android and Chrome. The back-end service for GOOGLE platforms is FCM (“Firebase Cloud Messaging”). GOOGLE, Android and Chrome are registered trademarks of GOOGLE Inc.

class lightstreamer_adapter.interfaces.metadata.MpnDeviceInfo(platform_type, application_id, device_token)

Bases: object

Specifies a target device for Push Notifications, used with MPN-related requests for the MetadataProvider. Note that the processing and the authorization of Push Notifications is per-device and per-application. While a physical device is uniquely identified by the platform type and a platform dependent device token, Lightstreamer considers the same device used by two different applications as two different MPN devices. Thus, an MpnDeviceInfo instance uniquely identifies both the physical device and the application for which it is being used.

An MpnDeviceInfo always provides the following identifiers:

  • The platform type.
  • The application ID.
  • The device token.
mpn_platform_type

The platform type of the device.

Type:MpnPlatformType
application_id

The application ID, also known as the package name or bundle ID on some platforms.

Type:str
device_token

The token of the device, also known as the registration ID on some platforms.

Type:str
class lightstreamer_adapter.interfaces.metadata.TableInfo(win_index, mode, group, schema, first_idx, last_idx, selector=None)

Bases: object

Used by MetadataProvider to provide value objects to the calls to methods notify_new_tables() and notify_tables_close(). The attributes of every Table (i.e.: Subscription) to be added or removed to a Session have to be written to a TableInfo instance.

win_index

The unique identifier of the client subscription request within the session. This allows for matching the corresponding subscription and unsubscription requests. Note that, for clients based on a very old version of a client library or text protocol, subscription requests may involve multiple Tables (i.e.: Subscriptions), hence multiple objects of this type can be supplied in a single array by MetadataProvider through notify_new_tables() notify_tables_close(). In this case, the value returned is the same for all these objects and the single Tables (i.e.: Subscriptions) can be identified by their relative position in the array.

Type:int
mode

The publishing Mode for the Items in the Table (i.e. Subscription) (it must be the same across all the Table).

Type:Mode
group

The name of the Item Group (or specification of the Item List) to which the subscribed Items belong.

Type:str
schema

The name of the Field Schema (or specification of the Field List) used for the subscribed Items.

Type:str
min

The index of the first Item in the Group to be considered in the Table (i.e. Subscription).

Type:int
max

The index of the last Item in the Group to be considered in the Table (i.e. Subscription).

Type:int
selector

The name of the optional Selector associated to the Table (i.e. Subscription).

Type:str
class lightstreamer_adapter.interfaces.metadata.MpnSubscriptionInfo(device, notification_format, trigger)

Bases: object

Specifies a Push Notifications subscription, used with MPN-related requests of the MetadataProvider.

For the actual description of the subscription we rely on a generic descriptor accessible via the notification_format property, where the structure of the descriptor depends on the platform.

Edition Note: Push Notifications is an optional feature, available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

device

MPN device of this subscription.

Type:MpnDeviceInfo
notification_format

The descriptor of the push notifications format of this subscription. The structure of the format descriptor depends on the platform type and it is represented in json.

Type:str
trigger

The optional expression that triggers the delivery of push notification.

Type:str
class lightstreamer_adapter.interfaces.metadata.MetadataError(msg)

Bases: Exception

Base exception class for all exceptions directly raised by the Metadata Adapter.

__init__(msg)

Constructs a MetadataError with the supplied detail message.

Parameters:msg (str) – the detail message.
msg

The detail message

Type:str
class lightstreamer_adapter.interfaces.metadata.MetadataProviderError(msg)

Bases: lightstreamer_adapter.interfaces.metadata.MetadataError

Raised by the MetadataProvider.initialize() method if there is some problem that prevents the correct behavior of the Metadata Adapter. If this exception occurs, Lightstreamer Kernel must give up the startup.

class lightstreamer_adapter.interfaces.metadata.NotificationError(msg)

Bases: lightstreamer_adapter.interfaces.metadata.MetadataError

Raised by the notify_* methods in MetadataProvider if there is some inconsistency in the supplied parameters. Lightstreamer Kernel ensures that such conditions will never occur, but they may be checked for debugging or documentation reasons.

class lightstreamer_adapter.interfaces.metadata.AccessError(msg)

Bases: lightstreamer_adapter.interfaces.metadata.MetadataError

Raised by the notify_* methods in MetadataProvider if the supplied User is not recognized or a functionality is not implemented for this User.

class lightstreamer_adapter.interfaces.metadata.ItemsError(msg)

Bases: lightstreamer_adapter.interfaces.metadata.MetadataError

Thrown by the MetadataProvider.get_items() and MetadataProvider.get_schema() methods if the supplied Item Group name (or Item List specification) is not recognized or cannot be resolved.

class lightstreamer_adapter.interfaces.metadata.SchemaError(msg)

Bases: lightstreamer_adapter.interfaces.metadata.MetadataError

Raised by the get_schema() method in MetadataProvider if the supplied Field Schema name (or Field List specification) is not recognized or cannot be resolved.

class lightstreamer_adapter.interfaces.metadata.CreditsError(client_error_code, msg, user_msg=None)

Bases: lightstreamer_adapter.interfaces.metadata.MetadataError

Thrown by the notify_* methods in MetadataProvider if some functionality cannot be allowed to the supplied User. This may occur if the user is not granted some resource or if the user would exceed the granted amount. Different kinds of problems can be distinguished by an error client_error_code. Both the error message detail and the error client_error_code will be forwarded by Lightstreamer Kernel to the Client.

__init__(client_error_code, msg, user_msg=None)

Constructs a CreditsError with supplied error client_error_code and message text to be forwarded to the Client. An internal error message text can also be specified.

Parameters:
  • client_error_code (int) – Error code that can be used to distinguish the kind of problem. It must be a negative integer, or zero to mean an unspecified problem.
  • msg (str) – the detail message.
  • user_msg (str) – A detail message to be forwarded to the Client. If None or missing, an empty string message will be forwarded. The message is free, but if it is not in simple ASCII or if it is multiline, it might be altered in order to be sent to very old non-TLCP clients.
client_error_code

The error client_error_code to be forwarded to the client.

Type:str
client_user_msg

The error detail message to be forwarded to the client.

Type:str
class lightstreamer_adapter.interfaces.metadata.ConflictingSessionError(code, msg, conflicting_session_id, user_msg=None)

Bases: lightstreamer_adapter.interfaces.metadata.CreditsError

Thrown by the MetadataProvider.notify_new_session() method f a User is not enabled to open a new Session but he would be enabled as soon as another Session were closed. By using this exception, the ID of the other Session is also supplied. After receiving this exception, the Server may try to close the specified session and invoke MetadataProvider.notify_new_session() again.

__init__(code, msg, conflicting_session_id, user_msg=None)

Constructs a ConflictingSessionError with supplied error client_error_code and message text that will be forwarded to the Client in case the Server can’t solve the issue by closing the conflicting session. An internal error message text can also be specified.

Parameters:
  • client_error_code (int) – Error code that can be used to distinguish the kind of problem. It must be a negative integer, or zero to mean an unspecified problem.
  • msg (str) – The detail message.
  • conflicting_session_id (str) – ID of a Session that can be closed in order to eliminate the reported problem. It must not be null.
  • user_msg (str) – A detail message to be forwarded to the Client. If None or missing, an empty string message will be forwarded. The message is free, but if it is not in simple ASCII or if it is multiline, it might be altered in order to be sent to very old non-TLCP clients.
conflicting_session_id

The ID of a Session that can be closed in order to eliminate the problem reported in this exception.

Type:str