Package com.lightstreamer.adapters.metadata

Class LiteralBasedProvider

java.lang.Object
com.lightstreamer.interfaces.metadata.MetadataProviderAdapter
com.lightstreamer.adapters.metadata.LiteralBasedProvider
All Implemented Interfaces:
MetadataProvider
public class LiteralBasedProvider extends MetadataProviderAdapter
Simple full implementation of a Metadata Adapter, made available in Lightstreamer SDK. The Adapter is not meant for production use, but it can be used as a starting point for real Adapters.
The class handles Item List specifications, a special case of Item Group name formed by simply concatenating the names of the Items contained in a List in a space separated way. Similarly, the class handles Field List specifications, a special case of Field Schema name formed by concatenating the names of the contained Fields. The handling of Item List and Field List specifications is required by some optional methods in the client APIs that take advantage of Item Lists and Field Lists.
The resource levels are assigned the same for all Items and Users, according with values that can be supplied together with adapter configuration, inside the "metadata_provider" element that defines the Adapter.
The return of the getAllowedMaxBandwidth method can be supplied in a "max_bandwidth" parameter; the return of the getAllowedMaxItemFrequency method can be supplied in a "max_frequency" parameter; the return of the getAllowedBufferSize method can be supplied in a "buffer_size" parameter; the return of the getDistinctSnapshotLength method can be supplied in a "distinct_snapshot_length" parameter; the return of the getMinSourceFrequency method can be supplied in a "prefilter_frequency" parameter. All resource limits not supplied are granted as unlimited, but for distinct_snapshot_length, which defaults as 10.
The return of the modeMayBeAllowed method (i.e. the association of the proper publishing Mode to each Item) can be configured by supplying a list of rules, which define Item families, where all Items in each family share the same set of allowed Modes (but remember that only one out of the MERGE, DISTINCT and COMMAND Modes is supported by the Server for each Item; only the RAW mode is supported without restrictions). Each family is specified by providing a pattern upon which all names of the Items in the family need to match and, optionally, the involved Data Adapter. The description of each family can be supplied with a group of parameters, named "item_family_<n>", "data_adapter_for_item_family_<n>", and "modes_for_item_family_<n>", where <n> is a progressive number, unique for each family. The first parameter specifies the pattern, in java.util.regex.Pattern format, while the second one is optional and specifies the Data Adapter (if missing, the rule applies regardless of the Data Adapter). The third parameter specifies the allowed modes for this family, as a list of names, with commas and spaces as allowed separators. In case more than one rule applies, the one with the smallest progressive is considered and the Item is assigned only to that family. Items that do not belong to any family are not allowed in any Mode; however, if no families are defined at all, then all Items are allowed in all Modes and the Clients should ensure that the same Item cannot be requested in two conflicting Modes.
There are no access restrictions, but an optional User name check is performed if a comma separated list of User names is supplied in an "allowed_users" parameter.
The following snippet shows an example of configuration of this Adapter in adapters.xml: 
 
<!-- Mandatory. Define the Metadata Provider. -->
<metadata_provider>

    <!-- Mandatory. Java class name of the adapter. -->
    <adapter_class>com.lightstreamer.adapters.metadata.LiteralBasedProvider</adapter_class>

    ......

    <!-- Optional. List of initialization parameters specific for LiteralBasedProvider. -->

    <!-- Optional.
         Define values to be returned in getAllowedMaxBandwidth(),
         getAllowedMaxItemFrequency(), getAllowedBufferSize() and
         getDistinctSnapshotLength() methods, for any User and Item
         supplied. -->
    <!--
    <param name="max_bandwidth">40</param>
    <param name="max_frequency">3</param>
    <param name="buffer_size">30</param>
    <param name="distinct_snapshot_length">10</param>
     -->

    <!-- Optional.
         Define comma-separated list of User names to be checked
         for allowance by the notifyUser() method. -->
    <!--
    <param name="allowed_users">user123,user456</param>
     -->

    <!-- Optional.
         Define how the modeMayBeAllowed method should behave, by
         associating to each item the modes in which it can be managed
         by the Server.
         Each triple of parameters of the form "item_family_<n>",
         "data_adapter_for_item_family_<n> (optional), and
         "modes_for_item_family_<n>" define respectively the item name
         pattern (in java.util.regex.Pattern format),
         the related Data Adapter, and the allowed
         modes (in comma separated format) for a family of items.
         Each item is assigned to the first family that matches its name
         and (if supplied) the related Data Adapter.
         If no families are specified at all, then modeMayBeAllowed
         always returns true, though this is not recommended, because
         the Server does not support more than one mode out of MERGE,
         DISTINCT, and COMMAND for the same item. In such a case, the
         Server would just manage each item in the mode specified by the
         first Client request it receives for the item and would be up to
         the Clients to ensure that the same item cannot be requested in
         two conflicting Modes. -->
    <param name="item_family_1">item.*</param>
    <param name="data_adapter_for_item_family_1">MyDataAdapter</param>
    <param name="modes_for_item_family_1">MERGE</param>
    <!--
    <param name="item_family_2">portfolio.*</param>
    <param name="modes_for_item_family_2">COMMAND</param>
     -->

</metadata_provider>
The class, together with the inherited MetadataProviderAdapter, also provides implementations for old signature versions of some methods (in the form of overloads of the current version) and it forwards the implementations for the current signature versions to the old ones, which involves discarding some arguments (with the exception of modeMayBeAllowed, which behaves in a slightly different way). As a consequence, a custom Metadata Adapter inheriting from this class is allowed to stick to old signature versions for its own implementations, although the use of the current versions is recommended. However, the restrictions related to the MetadataProvider interface still hold: the custom part of the Adapter is only allowed to implement at most one version for each interface method, otherwise the Adapter can be refused (the exception, here, is notifyUser, which has two current overloaded versions).

  • Constructor Details

    • LiteralBasedProvider

      public LiteralBasedProvider()
      Void constructor required by Lightstreamer Kernel.

  • Method Details

    • init

      public void init(Map params, File dir) throws MetadataProviderException
      Reads configuration settings for user and resource constraints. If some setting is missing, the corresponding constraint is not set.
      Specified by:
      init in interface MetadataProvider
      Overrides:
      init in class MetadataProviderAdapter
      Parameters:
      params - Can contain the configuration settings.
      dir - Not used.
      Throws:
      MetadataProviderException - in case of configuration errors.

    • getItems

      public String[] getItems(String user, String sessionID, String itemList, String dataAdapter) throws ItemsException
      Resolves an Item List specification supplied in a Request. The names of the Items in the List are returned. The operation is deferred to a reduced version of the method, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Parameters:
      user - A User name.
      sessionID - A Session ID.
      itemList - An Item List specification.
      dataAdapter - The name of the Data Adapter to which the Item List is targeted.
      Returns:
      An array with the names of the Items in the List, demanded to the 3-arguments overload.
      Throws:
      ItemsException - demanded to the 3-arguments overload.

    • getItems

      public String[] getItems(String user, String sessionID, String itemList) throws ItemsException
      Reduced, backward-compatibility version of the Item List determination method. The operation is deferred to an even more reduced version of the method, where the sessionID argument is discarded. This also ensures backward compatibility with very old adapter classes derived from this one.
      Parameters:
      user - A User name.
      sessionID - A Session ID.
      itemList - An Item List specification.
      Returns:
      An array with the names of the Items in the List, demanded to the 2-arguments overload.
      Throws:
      ItemsException - demanded to the 2-arguments overload.
      See Also:

    • getItems

      public String[] getItems(String user, String itemList) throws ItemsException
      Reduced, backward-compatibility version of the Item List determination method.
      Parameters:
      user - A User name. Not used.
      itemList - An Item List specification.
      Returns:
      An array with the names of the Items in the List.
      Throws:
      ItemsException - never thrown.
      See Also:

    • getSchema

      public String[] getSchema(String user, String sessionID, String itemList, String dataAdapter, String fieldList) throws SchemaException
      Resolves a Field List specification supplied in a Request. The names of the Fields in the List are returned. The operation is deferred to a reduced version of the method, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Parameters:
      user - A User name.
      sessionID - A Session ID.
      itemList - The specification of the Item List whose Items the Field List is to be applied to.
      dataAdapter - The name of the Data Adapter to which the Item List is targeted.
      fieldList - A Field List specification.
      Returns:
      An array with the names of the Fields in the List, demanded to the 4-arguments overload.
      Throws:
      SchemaException - demanded to the 4-arguments overload.

    • getSchema

      public String[] getSchema(String user, String sessionID, String itemList, String fieldList) throws SchemaException
      Reduced, backward-compatibility version of the Field List determination method. The operation is deferred to an even more reduced version of the method, where the sessionID argument is discarded. This also ensures backward compatibility with very old adapter classes derived from this one.
      Parameters:
      user - A User name.
      sessionID - A Session ID.
      itemList - The specification of the Item List whose Items the Field List is to be applied to.
      fieldList - A Field List specification.
      Returns:
      An array with the names of the Fields in the List, demanded to the 3-arguments overload.
      Throws:
      SchemaException - demanded to the 3-arguments overload.
      See Also:

    • getSchema

      public String[] getSchema(String user, String itemList, String fieldList) throws SchemaException
      Reduced, backward-compatibility version of the Field List determination method.
      Parameters:
      user - A User name. Not used.
      itemList - The specification of the Item List whose Items the Field List is to be applied to. Not used.
      fieldList - A Field List specification.
      Returns:
      An array with the names of the Fields in the List.
      Throws:
      SchemaException - never thrown.
      See Also:

    • notifyUser

      public CompletableFuture<Void> notifyUser(String user, String password, Map httpHeaders) throws AccessException, CreditsException
      Checks if a user is enabled to make Requests to the related Data Providers. Note that, for authentication purposes, only the user and password arguments should be consulted.
      In this very simple implementation, a configured set of user names is checked and no password check is done. Even though the processing is immediate, we return a CompletableFuture for demonstration purpose.
      Specified by:
      notifyUser in interface MetadataProvider
      Overrides:
      notifyUser in class MetadataProviderAdapter
      Parameters:
      user - A User name.
      password - An optional password.
      httpHeaders - A Map that contains a name-value pair for each header found in the HTTP request that originated the call. Not used.
      Returns:
      a CompletableFuture, that may also be completed exceptionally with an AccessException if a list of User names has been configured and the supplied name does not belong to the list.
      Throws:
      AccessException - never thrown
      CreditsException - never thrown.
      See Also:

    • notifyUser

      public CompletableFuture<Void> notifyUser(String user, String password, Map httpHeaders, String clientPrincipal) throws AccessException, CreditsException
      Extended version of the User authentication method, invoked by the Server instead of the standard 3-argument one in case it has been instructed (through the <use_client_auth> configuration flag) to acquire the client principal from the client TLS/SSL certificate, if available.
      The check is deferred to the standard version of the method, where the clientPrincipal argument is discarded.
      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).
      Specified by:
      notifyUser in interface MetadataProvider
      Overrides:
      notifyUser in class MetadataProviderAdapter
      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.
      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. Not used.
      Returns:
      a CompletableFuture or null, demanded to the 3-arguments overload.
      Throws:
      AccessException - demanded to the 3-arguments overload.
      CreditsException - demanded to the 3-arguments overload.

    • getAllowedMaxBandwidth

      public double getAllowedMaxBandwidth(String user)
      Returns the bandwidth level to be allowed to a User for a push Session.
      Specified by:
      getAllowedMaxBandwidth in interface MetadataProvider
      Overrides:
      getAllowedMaxBandwidth in class MetadataProviderAdapter
      Parameters:
      user - A User name. Not used.
      Returns:
      The bandwidth, in Kbit/sec, as supplied in the Metadata Adapter configuration.

    • getAllowedMaxItemFrequency

      public double getAllowedMaxItemFrequency(String user, String item, String dataAdapter)
      Returns the ItemUpdate frequency to be allowed to a User for a specific Item. The operation is deferred to a reduced version of the method, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      getAllowedMaxItemFrequency in interface MetadataProvider
      Overrides:
      getAllowedMaxItemFrequency in class MetadataProviderAdapter
      Parameters:
      user - A User name.
      item - An Item Name.
      dataAdapter - A Data Adapter name.
      Returns:
      A frequency limit, demanded to the 2-arguments overload.

    • getAllowedMaxItemFrequency

      public double getAllowedMaxItemFrequency(String user, String item)
      Reduced, backward-compatibility version of the ItemUpdate frequency authorization method.
      Overrides:
      getAllowedMaxItemFrequency in class MetadataProviderAdapter
      Parameters:
      user - A User name. Not used.
      item - An Item Name. Not used.
      Returns:
      The allowed Update frequency, in Updates/sec, as supplied in the Metadata Adapter configuration.
      See Also:

    • getAllowedBufferSize

      public int getAllowedBufferSize(String user, String item, String dataAdapter)
      Returns the size of the buffer internally used to enqueue subsequent ItemUpdates for the same Item. The operation is deferred to a reduced version of the method, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      getAllowedBufferSize in interface MetadataProvider
      Overrides:
      getAllowedBufferSize in class MetadataProviderAdapter
      Parameters:
      user - A User name.
      item - An Item Name.
      dataAdapter - A Data Adapter name.
      Returns:
      A buffer size, demanded to the 2-arguments overload.

    • getAllowedBufferSize

      public int getAllowedBufferSize(String user, String item)
      Reduced, backward-compatibility version of the buffer size authorization method.
      Overrides:
      getAllowedBufferSize in class MetadataProviderAdapter
      Parameters:
      user - A User name. Not used.
      item - An Item Name. Not used.
      Returns:
      The allowed buffer size, as supplied in the Metadata Adapter configuration.
      See Also:

    • getMinSourceFrequency

      public double getMinSourceFrequency(String item, String dataAdapter)
      Returns 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.
      The operation is deferred to a reduced version of the method, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      getMinSourceFrequency in interface MetadataProvider
      Overrides:
      getMinSourceFrequency in class MetadataProviderAdapter
      Parameters:
      item - An Item Name.
      dataAdapter - A Data Adapter name.
      Returns:
      A frequency limit, demanded to the 1-arguments overload.

    • getMinSourceFrequency

      public double getMinSourceFrequency(String item)
      Reduced, backward-compatibility version of the Prefilter frequency configuration method.
      Overrides:
      getMinSourceFrequency in class MetadataProviderAdapter
      Parameters:
      item - An Item Name. Not used.
      Returns:
      The maximum frequency to be allowed by the prefilter, as supplied in the Metadata Adapter configuration.
      See Also:

    • getDistinctSnapshotLength

      public int getDistinctSnapshotLength(String item, String dataAdapter)
      Returns the maximum allowed length for a Snapshot of any Item that has been requested with publishing Mode DISTINCT. The operation is deferred to a reduced version of the method, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      getDistinctSnapshotLength in interface MetadataProvider
      Overrides:
      getDistinctSnapshotLength in class MetadataProviderAdapter
      Parameters:
      item - An Item Name.
      dataAdapter - A Data Adapter name.
      Returns:
      A snapshot length, demanded to the 1-arguments overload.

    • getDistinctSnapshotLength

      public int getDistinctSnapshotLength(String item)
      Reduced, backward-compatibility version of the Snapshot length configuration method.
      Overrides:
      getDistinctSnapshotLength in class MetadataProviderAdapter
      Parameters:
      item - An Item Name. Not used.
      Returns:
      The maximum allowed length for the Snapshot, as supplied in the Metadata Adapter configuration. In case no value has been supplied, a default value of 10 events is returned, which is thought to be enough to satisfy typical Client requests.
      See Also:

    • modeMayBeAllowed

      public boolean modeMayBeAllowed(String item, String dataAdapter, Mode mode)
      Called by Lightstreamer Kernel to ask for the allowance of a publishing Mode for an Item. The operation is first deferred to a reduced version of the method, where the dataAdapter argument is discarded. This ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      modeMayBeAllowed in interface MetadataProvider
      Overrides:
      modeMayBeAllowed in class MetadataProviderAdapter
      Parameters:
      item - An Item name.
      dataAdapter - A Data Adapter name.
      mode - A publishing Mode.
      Returns:
      true or false, based on a sequence of rules of the general form <pattern,data_adapter,allowed_modes> supplied in the Adapter configuration. If no rule matches the Item name and the Data Adapter, then false is returned; otherwise, the first matching rule is considered and true is returned only if the related allowed_modes contain the specified Mode. However, if no rules are available at all, then true is always returned. In the latter case, as in any case of loose configuration, 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.

    • modeMayBeAllowed

      public boolean modeMayBeAllowed(String item, Mode mode)
      Reduced, backward-compatibility version of the publishing mode allowance method. This version is left to support overriding by old adapter classes derived from this one. If not overridden, the method delegates back to the standard version.
      Overrides:
      modeMayBeAllowed in class MetadataProviderAdapter
      Parameters:
      item - An Item name.
      mode - A publishing Mode.
      Returns:
      true or false only if overridden, otherwise throws.
      See Also: