public interface MetadataProvider
Modifier and Type | Method and Description |
---|---|
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 sessionID,
java.lang.String group)
Called by Lightstreamer Kernel to resolve an Item Group name (or Item List specification) 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 sessionID,
java.lang.String group,
java.lang.String schema)
Called by Lightstreamer Kernel to resolve a Field Schema name (or Field List specification) supplied in
a Request.
|
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
(i.e.: Subscription) 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 |
notifyMpnDeviceAccess(java.lang.String user,
MpnDeviceInfo device)
Called by Lightstreamer Kernel to check that a User is enabled to access
the specified MPN device.
|
void |
notifyMpnDeviceTokenChange(java.lang.String user,
MpnDeviceInfo device,
java.lang.String newDeviceToken)
Called by Lightstreamer Kernel to check that a User is enabled to change
the token of a MPN device.
|
void |
notifyMpnSubscriptionActivation(java.lang.String user,
java.lang.String sessionID,
TableInfo table,
MpnSubscriptionInfo mpnSubscription)
Called by Lightstreamer Kernel to check that a User is enabled
to activate a Push Notification subscription.
|
void |
notifyNewSession(java.lang.String user,
java.lang.String sessionID,
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 sessionID,
TableInfo[] tables)
Called by Lightstreamer Kernel to check that a User is enabled to add
some Tables (i.e.: Subscriptions) to a push Session.
|
void |
notifySessionClose(java.lang.String sessionID)
Called by Lightstreamer Kernel to notify the Metadata Adapter that
a push Session has been closed.
|
void |
notifyTablesClose(java.lang.String sessionID,
TableInfo[] tables)
Called by Lightstreamer Kernel to notify the Metadata Adapter that
some Tables (i.e.: Subscriptions) 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 |
notifyUser(java.lang.String user,
java.lang.String password,
java.util.Map httpHeaders,
java.lang.String clientPrincipal)
Called by Lightstreamer Kernel, instead of calling the 3-arguments
version, 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.
|
void |
notifyUserMessage(java.lang.String user,
java.lang.String sessionID,
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 (i.e.: Subscription)
is added or removed from a push Session owned by a supplied User.
|
void init(java.util.Map params, java.io.File configDir) throws MetadataProviderException
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.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.void notifyUser(java.lang.String user, java.lang.String password, java.util.Map httpHeaders) throws AccessException, CreditsException
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.
The header names are reported in lower-case form.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.notifyUser(String, String, Map, String)
void notifyUser(java.lang.String user, java.lang.String password, java.util.Map httpHeaders, java.lang.String clientPrincipal) throws AccessException, CreditsException
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.clientPrincipal
- 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 null if client has not
authenticated itself or the authentication has failed.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.java.lang.String[] getItems(java.lang.String user, java.lang.String sessionID, java.lang.String group) throws ItemsException
if (group.equals("portfolio")) {
String itemName = "PF_" + user;
return new String[] { itemName };
} else if (group.startsWith("PF_")) {
// protection from unauthorized use of user-specific items
throw new ItemsException("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.
notifyUser(String, String, Map)
. If the implementation
is slow, it might delay the subscription request management.
In that case, configuring a dedicated "SET" thread pool for requests
on this Adapter Set is recommended, in order not to block operations
for different Adapter Sets. If the delay affects requests for a
specific Data Adapter, then configuring a dedicated "DATA" thread pool
for that Data Adapter is a better option.user
- A User name.sessionID
- The ID of a Session owned by the User.group
- An Item Group name (or Item List specification).ItemsException
- if the supplied Item Group name (or Item List specification) is not recognized.java.lang.String[] getSchema(java.lang.String user, java.lang.String sessionID, java.lang.String group, java.lang.String schema) throws ItemsException, SchemaException
getItems(String, String, String)
.user
- A User name.sessionID
- The ID of a Session owned by the User.group
- The name of the Item Group (or specification of the Item List)
whose Items the Schema is to be applied to.schema
- A Field Schema name (or Field List specification).ItemsException
- if the supplied Item Group name (or Item List specification) is not recognized.SchemaException
- if the supplied Field Schema name (or Field List specification) is not recognized.double getAllowedMaxBandwidth(java.lang.String user)
notifyUser(String, String, Map)
. If the implementation
is slow, it might delay the client session activation.
In that case, configuring a dedicated "SET" thread pool for requests
on this Adapter Set is recommended, in order not to block operations
for different Adapter Sets.user
- A User name.double getAllowedMaxItemFrequency(java.lang.String user, java.lang.String item)
getItems(String, String, String)
.user
- A User name.item
- An Item Name.int getAllowedBufferSize(java.lang.String user, java.lang.String item)
getItems(String, String, String)
.user
- A User name.item
- An Item Name.boolean isModeAllowed(java.lang.String user, java.lang.String item, Mode mode)
getItems(String, String, String)
.user
- A User name.item
- An Item name.mode
- A publishing Mode.boolean modeMayBeAllowed(java.lang.String item, Mode mode)
item
- An Item name.mode
- A publishing Mode.boolean isSelectorAllowed(java.lang.String user, java.lang.String item, java.lang.String selector)
getItems(String, String, String)
.user
- A User name.item
- An Item name.selector
- A selector name.boolean isSelected(java.lang.String user, java.lang.String item, java.lang.String selector, ItemEvent event)
ItemEventListener.clearSnapshot(java.lang.String)
request issued by the Data Adapter for an item in COMMAND mode, a special
event is associated, with "key" field null and "command" field valued
with "DELETEALL"; this event is equivalent to a DELETE event for each
active key and it is shown to allow for keeping the item state and to
help obeying the consistency rules, but it cannot be filtered out.
notifyUser(String, String, Map)
. If the implementation
were slow, the whole update delivery process, even for different
sessions, would be slowed down.user
- A User name.item
- An Item name.selector
- A selector name.event
- An update event for the Item.boolean enableUpdateCustomization(java.lang.String user, java.lang.String item)
getItems(String, String, String)
.user
- A User name.item
- An Item name.void customizeUpdate(java.lang.String user, java.lang.String item, CustomizableItemEvent event)
ItemEventListener.clearSnapshot(java.lang.String)
request issued by the Data Adapter for an item in COMMAND mode, a special
event is associated, with "key" field null and "command" field valued
with "DELETEALL"; this event is equivalent to a DELETE event for each
active key and it is shown to allow for keeping the item state, but it
cannot be customized in any way.
notifyUser(String, String, Map)
. If the implementation
were slow, the whole update delivery process, even for different
sessions, would be slowed down.user
- A User name.item
- An Item name.event
- An update event for the Item, ready to be changed.double getMinSourceFrequency(java.lang.String item)
modeMayBeAllowed(String, Mode)
.item
- An Item Name.int getDistinctSnapshotLength(java.lang.String item)
modeMayBeAllowed(String, Mode)
.item
- An Item Name.void notifyUserMessage(java.lang.String user, java.lang.String sessionID, java.lang.String message) throws CreditsException, NotificationException
user
- A User name.sessionID
- The ID of a Session owned by the User.message
- A non-null string.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 ID.void notifyNewSession(java.lang.String user, java.lang.String sessionID, java.util.Map clientContext) throws CreditsException, NotificationException
notifyUser(String, String, Map)
. If the implementation
is slow because of complex data gathering operations, it might delay the
client session activation.
In that case, configuring a dedicated "SET" thread pool for this Adapter Set
is recommended, in order not to block operations for different Adapter Sets.user
- A User name.sessionID
- The ID of a new Session.clientContext
- A Map-type value object that contains information
about the request context. Unless specified, the values are supplied as strings.
Information related to a client connection refers to the HTTP request
that originated the call. Available keys are:
notifyUser(String, String, Map)
for the current client
request instance; note that any authorization information that was
supplied by the backend through the authentication request could be
added to the Map in notifyUser(String, String, Map)
and can
be got back here. This allows for using local authentication-related
details for the authorization task.CreditsException
- if the User is not enabled to open the new
Session.
ConflictingSessionException
can be
thrown, in which the ID of the other Session must be specified.
In this case, a second invocation of the method with the same
"HTTP_HEADERS" Map and a different Session ID will be received.NotificationException
- if something is wrong in the parameters,
such as the ID of a Session already open for this or a different User.void notifySessionClose(java.lang.String sessionID) throws NotificationException
sessionID
- A Session ID.NotificationException
- if something is wrong in the parameters,
such as the ID of a Session that is not currently open.boolean wantsTablesNotification(java.lang.String user)
notifyNewTables(java.lang.String, java.lang.String, com.lightstreamer.interfaces.metadata.TableInfo[])
and
notifyTablesClose(java.lang.String, com.lightstreamer.interfaces.metadata.TableInfo[])
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.
getAllowedMaxBandwidth(String)
.user
- A User name.void notifyNewTables(java.lang.String user, java.lang.String sessionID, TableInfo[] tables) throws CreditsException, NotificationException
wantsTablesNotification(java.lang.String)
.
getItems(String, String, String)
for details; but see
the <sequentialize_table_notifications> parameter available
in adapters.xml as well.user
- A User name.sessionID
- The ID of a Session owned by the User.tables
- An array 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 array represent Tables (i.e.: Subscriptions) whose
subscription is requested atomically by the client. A single element
should be expected in the array, unless clients based on a very old
version of a client library or text protocol may be in use.CreditsException
- if the User is not allowed to add the
specified Tables (i.e.: Subscriptions) to the Session.NotificationException
- if something is wrong in the parameters,
such as the ID of a Session that is not currently open or inconsistent
information about a Table (i.e.: Subscription).void notifyTablesClose(java.lang.String sessionID, TableInfo[] tables) throws NotificationException
wantsTablesNotification(java.lang.String)
.
sessionID
- A Session ID.tables
- An array of TableInfo instances, each of them containing
the details of a Table (i.e.: Subscription) that has been removed from the Session.
The supplied array is in 1:1 correspondance with the array supplied by
notifyNewTables(java.lang.String, java.lang.String, com.lightstreamer.interfaces.metadata.TableInfo[])
in a previous call;
the correspondance can be recognized by matching TableInfo.getWinIndex()
as returned by the included objects (if multiple objects are included,
it must be the same for all of them).NotificationException
- if 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.void notifyMpnDeviceAccess(java.lang.String user, MpnDeviceInfo device) throws CreditsException, NotificationException
notifyMpnSubscriptionActivation(java.lang.String, java.lang.String, com.lightstreamer.interfaces.metadata.TableInfo, com.lightstreamer.interfaces.metadata.MpnSubscriptionInfo)
and notifyMpnDeviceTokenChange(java.lang.String, com.lightstreamer.interfaces.metadata.MpnDeviceInfo, java.lang.String)
.
notifyUser(String, String, Map)
. If the implementation
is slow, it might delay the notification request management.
In that case, configuring a dedicated "MPN_REQUESTS" thread pool for
MPN-related requests on this Adapter Set is recommended, in order not
to block operations for different Adapter Sets or different operations
for this Adapter Set.user
- A User name.device
- specifies a MPN device.CreditsException
- if the User is not allowed to access the
specified MPN device in the Session.NotificationException
- if something is wrong in the parameters,
such as inconsistent information about the device.void notifyMpnSubscriptionActivation(java.lang.String user, java.lang.String sessionID, TableInfo table, MpnSubscriptionInfo mpnSubscription) throws CreditsException, NotificationException
MpnSubscriptionInfo.getTrigger()
, 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.
notifyMpnDeviceAccess(java.lang.String, com.lightstreamer.interfaces.metadata.MpnDeviceInfo)
for details.user
- A User name.sessionID
- The ID of a Session owned by the User. The session ID is
provided for a thorough validation of the Table informations, 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
- A TableInfo instance, containing the details of a Table
(i.e.: Subscription) for which Push Notification have to be activated.mpnSubscription
- An MpnSubscriptionInfo instance, containing the
details of a Push Notification to be activated. Platform specific
details may be accessed by casting the class to the platform's specific
subclass (i.e. MpnApnsSubscriptionInfo, etc.).CreditsException
- if the User is not allowed to activate the
specified Push Notification in the Session.NotificationException
- if something is wrong in the parameters,
such as inconsistent information about a Table (i.e.: Subscription) or
a Push Notification.void notifyMpnDeviceTokenChange(java.lang.String user, MpnDeviceInfo device, java.lang.String newDeviceToken) throws CreditsException, NotificationException
notifyMpnDeviceAccess(java.lang.String, com.lightstreamer.interfaces.metadata.MpnDeviceInfo)
for details.user
- A User name.device
- specifies a MPN device.newDeviceToken
- The new token being assigned to the device.CreditsException
- if the User is not allowed to change the
specified device token.NotificationException
- if something is wrong in the parameters,
such as inconsistent information about the device.