com.lightstreamer.interfaces.metadata
Interface MetadataProvider

All Known Implementing Classes:

MetadataProviderAdapter

public interface MetadataProvider

Provides an interface to be implemented by a Metadata Adapter in order to attach a Metadata Provider to Lightstreamer Kernel. The configuration of an Adapter instance requires the following items:

• a unique identification for the instance;
• the Adapter class name;
• optional configuration parameters.

A Metadata Provider is used by Lightstreamer Kernel in combination with one or multiple Data Providers, uniquely associated with it. The configuration is accomplished through the "adapters.xml" configuration files, by which one or more "Adapter Sets" can be installed into the Server, where each Adapter Set is made up of exactly one Metadata Adapter and one or multiple Data Adapters.
A single instance of each configured Metadata Adapter is created by Lightstreamer Kernel at startup, then its init method is called, providing it with the configuration information. For this purpose, any Metadata Adapter must provide a void constructor.
A Metadata Provider is consulted by Lightstreamer Kernel in order to manage the push Requests intended for the associated Data Providers. A Metadata Provider supplies informations for several different goals:

• the resolution of the macro 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 (other than init(Map, File)) should be nonblocking, because they are called in threads taken from limited pools. Slow execution on one call related to a particular client session may cause delays on the execution of other sessions. If the access to some external resource is needed in order to gather user or item information, then the access should preferably be limited to init(Map, File), notifyUser(String, String, Map), getItems(String, String, String) and getSchema(String, String, String, String). In this case, the size of the thread pool devoted to to the management of the client requests should be properly set, through the "server_pool_max_size" flag in the Server configuration file.

Method Summary

void	customizeUpdate(java.lang.String user, java.lang.String item, CustomizableItemEvent event) Called by Lightstreamer Kernel in order to customize events pertaining to an ItemEventBuffer, if such customization has been requested through the enableUpdateCustomization method.
boolean	enableUpdateCustomization(java.lang.String user, java.lang.String item) Called by Lightstreamer Kernel to know whether the Metadata Adapter must or must not be given a chance to modify the values carried by the updates for a supplied Item in a push Session owned by a supplied User.
int	getAllowedBufferSize(java.lang.String user, java.lang.String item) Called by Lightstreamer Kernel to ask for the maximum size allowed for the buffer internally used to enqueue subsequent ItemUpdates for the same Item.
double	getAllowedMaxBandwidth(java.lang.String user) Called by Lightstreamer Kernel to ask for the bandwidth level to be allowed to a User for a push Session.
double	getAllowedMaxItemFrequency(java.lang.String user, java.lang.String item) Called by Lightstreamer Kernel to ask for the ItemUpdate frequency to be allowed to a User for a specific Item.
int	getDistinctSnapshotLength(java.lang.String item) Called by Lightstreamer Kernel to ask for the maximum allowed length for a Snapshot of an Item that has been requested with publishing Mode DISTINCT.
java.lang.String[]	getItems(java.lang.String user, java.lang.String session, java.lang.String id) Called by Lightstreamer Kernel to resolve a Group name supplied in a Request.
double	getMinSourceFrequency(java.lang.String item) Called by Lightstreamer Kernel to ask for the minimum ItemEvent frequency from the supplier Data Adapter at which the events for an Item are guaranteed to be delivered to the Clients without loss of information.
java.lang.String[]	getSchema(java.lang.String user, java.lang.String session, java.lang.String id, java.lang.String schema) Called by Lightstreamer Kernel to resolve a Schema name supplied in a Request.
java.lang.String[]	getUserSessions(java.lang.String user) Deprecated.
void	init(java.util.Map params, java.io.File configDir) Called by Lightstreamer Kernel to provide initialization information to the Metadata Adapter.
boolean	isModeAllowed(java.lang.String user, java.lang.String item, Mode mode) Called by Lightstreamer Kernel to ask for the allowance of a publishing Mode for an Item.
boolean	isSelected(java.lang.String user, java.lang.String item, java.lang.String selector, ItemEvent event) Called by Lightstreamer Kernel in order to filter events pertaining to an ItemEventBuffer, if the related Item was requested within a table with an associated Selector.
boolean	isSelectorAllowed(java.lang.String user, java.lang.String item, java.lang.String selector) Called by Lightstreamer Kernel to ask for the allowance of a Selector for an Item.
boolean	modeMayBeAllowed(java.lang.String item, Mode mode) Called by Lightstreamer Kernel to ask for the allowance of a publishing Mode for an Item (for at least one User).
void	notifyNewSession(java.lang.String user, java.lang.String session, java.util.Map clientContext) Called by Lightstreamer Kernel to check that a User is enabled to open a new push Session.
void	notifyNewTables(java.lang.String user, java.lang.String session, TableInfo[] tables) Called by Lightstreamer Kernel to check that a User is enabled to add some Tables to a push Session.
void	notifySessionClose(java.lang.String session) Called by Lightstreamer Kernel to notify the Metadata Adapter that a push Session has been closed.
void	notifyTablesClose(java.lang.String session, TableInfo[] tables) Called by Lightstreamer Kernel to notify the Metadata Adapter that some Tables have been removed from a push Session.
void	notifyUser(java.lang.String user, java.lang.String password, java.util.Map httpHeaders) Called by Lightstreamer Kernel as a preliminary check that a user is enabled to make Requests to any of the related Data Providers.
void	notifyUserMessage(java.lang.String user, java.lang.String session, java.lang.String message) Called by Lightstreamer Kernel to forward a message received by a User.
boolean	wantsTablesNotification(java.lang.String user) Called by Lightstreamer Kernel to know whether the Metadata Adapter must or must not be notified any time a Table is added or removed from a push Session owned by a supplied User.

Method Detail

init

void init(java.util.Map params,
          java.io.File configDir)
          throws MetadataProviderException

Called by Lightstreamer Kernel to provide initialization information to the Metadata Adapter. If an exception occurs in this method, Lightstreamer Kernel can't complete the startup and must exit.

Parameters:

params - A Map-type value object that contains name-value pairs corresponding to the "param" elements supplied in the Metadata Adapter configuration file under the "metadata_provider" element. Both names and values are represented as String objects.

configDir - The path of the directory on the local disk where the Metadata Adapter configuration file resides.

Throws:

MetadataProviderException - if an error occurs that prevents the correct behavior of the Metadata Adapter. This causes the Server not to complete the startup and to exit.

notifyUser

void notifyUser(java.lang.String user,
                java.lang.String password,
                java.util.Map httpHeaders)
                throws AccessException,
                       CreditsException

Called by Lightstreamer Kernel as a preliminary check that a user is enabled to make Requests to any of 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.

Parameters:

user - A User name.

password - A password optionally required to validate the User.

httpHeaders - A Map-type value object that contains a name-value pair for each header found in the HTTP request that originated the call. For headers defined multiple times, a unique name-value pair is reported, where the value is a concatenation of all the supplied header values, separated by a "," and, possibly, by some white spaces; this holds regardless that the HTTP specifications allow the specific header to be defined multiple times.

Throws:

AccessException - if the User name is not known or the supplied password is not correct.

CreditsException - if the User is known but is not enabled to make further Requests at the moment.

getItems

java.lang.String[] getItems(java.lang.String user,
                            java.lang.String session,
                            java.lang.String id)
                            throws ItemsException

Called by Lightstreamer Kernel to resolve a Group name supplied in a Request. The names of the Items in the Group must be returned.
Possibly, the content of a Group may be dependant on the User who is issuing the Request or on the specific Session instance.
A special case is when the Group name is made of a space-separated list of the names of the items in the Group. This convention is used by some of the subscription methods provided by the various client libraries. The specifications for these methods require that "A LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the Request". When any of these interface methods is used by client code accessing this Metadata Adapter, the supplied id 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; returning decorated or alternative item names is also possible: they will be associated to the corresponding names used in the supplied id by client library code.

Parameters:

user - A User name.

session - The name of a Session owned by the User.

id - A Group name.

Returns:

An array with the names of the Items in the Group.

Throws:

ItemsException - if the supplied Group name is not recognized.

getSchema

java.lang.String[] getSchema(java.lang.String user,
                             java.lang.String session,
                             java.lang.String id,
                             java.lang.String schema)
                             throws ItemsException,
                                    SchemaException

Called by Lightstreamer Kernel to resolve a Schema name supplied in a Request. The names of the Fields in the Schema must be returned.
Possibly, the content of a Schema may be dependant on the User who is issuing the Request, on the specific Session instance or on the Group to which the Request is related.
A special case is when the Schema name 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. The specifications for these methods require that "A LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the Request". When any of these interface methods is used by client code accessing this 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 schema by client library code.

Parameters:

user - A User name.

session - The name of a Session owned by the User.

id - The name of a Group whose Items the Schema is to be applied to.

schema - A Schema name.

Returns:

An array with the names of the Fields in the Schema.

Throws:

ItemsException - if the supplied Group name is not recognized.

SchemaException - if the supplied Schema name is not recognized.

getAllowedMaxBandwidth

double getAllowedMaxBandwidth(java.lang.String user)

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

Parameters:

user - A User name.

Returns:

The allowed bandwidth, in Kbit/sec. A zero return value means an unlimited bandwidth.

Edition Note:

Bandwidth control is not enabled in Allegro edition.

Edition Note:

Bandwidth control is not enabled in Moderato edition.

getAllowedMaxItemFrequency

double getAllowedMaxItemFrequency(java.lang.String user,
                                  java.lang.String item)

Called by Lightstreamer Kernel 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.

Parameters:

user - A User name.

item - An Item Name.

Returns:

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

Edition Note:

A further global frequency limit is imposed in Presto edition; this specific limit also applies to RAW mode and to unfiltered dispatching.

Edition Note:

A further global frequency limit is imposed in Allegro edition; this specific limit also applies to RAW mode and to unfiltered dispatching.

Edition Note:

A further global frequency limit is imposed in Moderato edition; this specific limit also applies to RAW mode and to unfiltered dispatching.

getAllowedBufferSize

int getAllowedBufferSize(java.lang.String user,
                         java.lang.String item)

Called by Lightstreamer Kernel 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.

Parameters:

user - A User name.

item - An Item Name.

Returns:

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

isModeAllowed

boolean isModeAllowed(java.lang.String user,
                      java.lang.String item,
                      Mode mode)

Called by Lightstreamer Kernel 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.

Parameters:

user - A User name.

item - An Item name.

mode - A publishing Mode.

Returns:

true if the publishing Mode is allowed.

modeMayBeAllowed

boolean modeMayBeAllowed(java.lang.String item,
                         Mode mode)

Called by Lightstreamer Kernel 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.

Parameters:

item - An Item name.

mode - A publishing Mode.

Returns:

true if the publishing Mode is allowed.

isSelectorAllowed

boolean isSelectorAllowed(java.lang.String user,
                          java.lang.String item,
                          java.lang.String selector)

Called by Lightstreamer Kernel to ask for the allowance of a Selector for an Item. Typically, a Selector is intended for one Item or for a specific set of Items with some characteristics. Moreover, a Selector can or cannot be allowed depending on the User.

Parameters:

user - A User name.

item - An Item name.

selector - A selector name.

Returns:

true if the Selector is allowed.

isSelected

boolean isSelected(java.lang.String user,
                   java.lang.String item,
                   java.lang.String selector,
                   ItemEvent event)

Called by Lightstreamer Kernel in order to filter events pertaining to an ItemEventBuffer, if the related Item was requested within a table with an associated Selector. If the return value is true, the event is dispatched to the ItemEventBuffer; otherwise, it is filtered out. If any consistency rule for the update flow is guaranteed by the Server for the Item (e.g. mandatory snapshot in MERGE mode or ADD-UPDATE-DELETE sequencing in COMMAND mode), it is a responsibility of the isSelected method implementation to ensure that these consistency rules keep being honoured.

Parameters:

user - A User name.

item - An Item name.

selector - A selector name.

event - An update event for the Item.

Returns:

true if the event is to be processed by the ItemEventBuffer.

enableUpdateCustomization

boolean enableUpdateCustomization(java.lang.String user,
                                  java.lang.String item)

Called by Lightstreamer Kernel to know whether the Metadata Adapter must or must not be given a chance to modify the values carried by the updates for a supplied Item in a push Session owned by a supplied User. If this method returns true, the customizeUpdate method will be called for each update for these Item and User. If it returns false, the customizeUpdate method will never be called for these Item and User, saving some processing time.

Parameters:

user - A User name.

item - An Item name.

Returns:

true if the Metadata Adapter must be notified any time an update for the Item is received in a Session owned by the User.

customizeUpdate

void customizeUpdate(java.lang.String user,
                     java.lang.String item,
                     CustomizableItemEvent event)

Called by Lightstreamer Kernel in order to customize events pertaining to an ItemEventBuffer, if such customization has been requested through the enableUpdateCustomization method. The supplied event can be changed inside this method before being processed by the ItemEventBuffer. Note that the applied changes only affect one ItemEventBuffer instance. This means that impacts on overall performance may be significant if customization for some items applies to all sessions. If any consistency rule for the update is guaranteed by the Server for the Item, it is a responsibility of the customizeUpdate method implementation to ensure that these consistency rules keep being honoured; for example, "key" and "command" fields for an Item to be requested in COMMAND mode should not be altered.

Parameters:

user - A User name.

item - An Item name.

event - An update event for the Item, ready to be changed.

getMinSourceFrequency

double getMinSourceFrequency(java.lang.String item)

Called by Lightstreamer Kernel to ask for the minimum ItemEvent frequency from the supplier 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 the specified frequency, Lightstreamer Kernel may prefilter the events flow down to this frequency. 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 supplier 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.

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.

getDistinctSnapshotLength

int getDistinctSnapshotLength(java.lang.String item)

Called by Lightstreamer Kernel 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 lenght of the buffer is limited by the value returned by this method. The maximum Snapshot size cannot be unlimited.

Parameters:

item - An Item Name.

Returns:

The maximum allowed length for the Snapshot; a zero return value means that no Snapshot information should be kept.

getUserSessions

java.lang.String[] getUserSessions(java.lang.String user)
                                   throws AccessException

Deprecated.

Called by Lightstreamer Kernel to get the names of the Sessions currently owned by a User. This information is required in order to execute the special Request to kill all the active Sessions of a specified User. For security matters, the Metadata Adapter may refuse to answer to this method; in such a case, only the special killing Requests would be compromised.

Parameters:

user - A User name.

Returns:

An array containing the names of the currently active Session for the User.

Throws:

AccessException - if the functionality is not available for this User or for all Users.

notifyUserMessage

void notifyUserMessage(java.lang.String user,
                       java.lang.String session,
                       java.lang.String message)
                       throws CreditsException,
                              NotificationException

Called by Lightstreamer Kernel 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.

Parameters:

user - A User name.

session - The name of a Session owned by the User.

message - A non-null string.

Throws:

CreditsException - if the User is not enabled to send the message or the message cannot be correctly managed.

NotificationException - if something is wrong in the parameters, such as a nonexistent Session name.

notifyNewSession

void notifyNewSession(java.lang.String user,
                      java.lang.String session,
                      java.util.Map clientContext)
                      throws CreditsException,
                             NotificationException

Called by Lightstreamer Kernel 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.

Parameters:

user - A User name.

session - The name of a new Session.

clientContext - A Map-type value object that contains 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

Throws:

CreditsException - if the User is not enabled to open the new Session. If the user would be enabled as soon as another Session were closed, a ConflictingSessionException can be thrown, in which the name of the other Session must be specified.

NotificationException - if something is wrong in the parameters, such as a name of a Session already open for this or a different User.

notifySessionClose

void notifySessionClose(java.lang.String session)
                        throws NotificationException

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

Parameters:

session - A Session name.

Throws:

NotificationException - if something is wrong in the parameters, such as a name of a Session that is not currently open.

wantsTablesNotification

boolean wantsTablesNotification(java.lang.String user)

Called by Lightstreamer Kernel to know whether the Metadata Adapter must or must not be notified any time a Table is added or removed from a push Session owned by a supplied User. If this method returns false, the methods notifyNewTables and notifyTablesClose 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 he wants.

Parameters:

user - A User name.

Returns:

true if the Metadata Adapter must be notified any time a Table is added or removed from a Session owned by the User.

notifyNewTables

void notifyNewTables(java.lang.String user,
                     java.lang.String session,
                     TableInfo[] tables)
                     throws CreditsException,
                            NotificationException

Called by Lightstreamer Kernel to check that a User is enabled to add some Tables to a push Session. If the check succeeds, this also notifies the Metadata Adapter that the Tables are being added to the Session.

Parameters:

user - A User name.

session - The name of a Session owned by the User.

tables - An array of TableInfo instances, each of them containing the details of a Table to be added to the Session.

Throws:

CreditsException - if the User is not allowed to add the specified Tables to the Session.

NotificationException - if something is wrong in the parameters, such as a name of a Session that is not currently open or inconsistent informations about a Table.

notifyTablesClose

void notifyTablesClose(java.lang.String session,
                       TableInfo[] tables)
                       throws NotificationException

Called by Lightstreamer Kernel to notify the Metadata Adapter that some Tables have been removed from a push Session.

Parameters:

session - A Session name.

tables - An array of TableInfo instances, each of them containing the details of a Table that has been removed from the Session.

Throws:

NotificationException - if something is wrong in the parameters, such as a name of a Session that is not currently open or a Table that is not contained in the Session.