Package com.lightstreamer.interfaces.metadata

Class MetadataProviderAdapter

java.lang.Object
com.lightstreamer.interfaces.metadata.MetadataProviderAdapter
All Implemented Interfaces:
MetadataProvider
Direct Known Subclasses:
LiteralBasedProvider
public abstract class MetadataProviderAdapter extends Object implements MetadataProvider
Provides a default implementation of all the MetadataProvider interface methods, except for getItems and getSchema. Overriding this class ° may facilitate the coding of simple Metadata Adapters.
The class also provides implementations for old signature versions of some methods (in the form of overloads of the current version) and, by default, it forwards the implementations for the current signature versions to the old ones, which involves discarding some arguments. 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 (with the exception of notifyUser, which has two current overloaded versions).

  • Constructor Details

    • MetadataProviderAdapter

      public MetadataProviderAdapter()

  • Method Details

    • init

      public void init(@Nonnull Map params, @Nonnull File configDir) throws MetadataProviderException
      No-op initialization.
      Specified by:
      init in interface MetadataProvider
      Parameters:
      params - not used.
      configDir - not used.
      Throws:
      MetadataProviderException - never thrown.

    • notifyUser

      public CompletableFuture<Void> notifyUser(@Nullable String user, @Nullable String password, @Nonnull Map httpHeaders) throws AccessException, CreditsException
      Called by Lightstreamer Kernel as a preliminary check that 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 default implementation, the Metadata Adapter poses no restriction. As the processing is successful and immediate, we don't need to return a CompletableFuture, but can just return null.
      Specified by:
      notifyUser in interface MetadataProvider
      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. Not used.
      Returns:
      null, to notify an immediate success.
      Throws:
      AccessException - never thrown
      CreditsException - never thrown
      See Also:

    • notifyUser

      public CompletableFuture<Void> notifyUser(@Nullable String user, @Nullable String password, @Nonnull Map httpHeaders, @Nonnull 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.
      In this default implementation, the standard version of the method is invoked, 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
      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(@Nullable String user)
      Called by Lightstreamer Kernel to ask for the bandwidth amount to be allowed to a User for a push Session. In this default implementation, the Metadata Adapter poses no restriction.
      Specified by:
      getAllowedMaxBandwidth in interface MetadataProvider
      Parameters:
      user - not used.
      Returns:
      always zero, to mean no bandwidth limit.

    • getAllowedMaxItemFrequency

      public double getAllowedMaxItemFrequency(@Nullable String user, @Nonnull String item, @Nonnull String dataAdapter)
      Called by Lightstreamer Kernel to ask for the ItemUpdate frequency to be allowed to a User for a specific Item. In this default implementation, a reduced version of the method is invoked, 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
      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(@Nullable String user, @Nonnull String item)
      Reduced, backward-compatibility version of the ItemUpdate frequency authorization method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, the Metadata Adapter poses no restriction; this also enables unfiltered dispatching for Items that support it.
      Parameters:
      user - not used.
      item - not used.
      Returns:
      always zero, to mean no frequency limit.
      See Also:

    • getAllowedBufferSize

      public int getAllowedBufferSize(@Nullable String user, @Nonnull String item, @Nonnull String dataAdapter)
      Called by Lightstreamer Kernel to ask for the maximum allowed size of the buffer internally used to enqueue subsequent ItemUpdates for the same Item. In this default implementation, a reduced version of the method is invoked, 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
      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(@Nullable String user, @Nonnull String item)
      Reduced, backward-compatibility version of the buffer size authorization method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, the Metadata Adapter poses no restriction.
      Parameters:
      user - not used.
      item - not used.
      Returns:
      always zero, to mean no size limit.
      See Also:

    • isModeAllowed

      public boolean isModeAllowed(@Nullable String user, @Nonnull String item, @Nonnull String dataAdapter, @Nonnull 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. In this default implementation, a reduced version of the method is invoked, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      isModeAllowed in interface MetadataProvider
      Parameters:
      user - a user name.
      item - an item name.
      dataAdapter - a Data Adapter name.
      mode - a subscription mode.
      Returns:
      true or false, demanded to the 3-arguments overload.

    • isModeAllowed

      public boolean isModeAllowed(@Nullable String user, @Nonnull String item, @Nonnull Mode mode)
      Reduced, backward-compatibility version of the publishing Mode authorization method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, the Metadata Adapter poses no restriction. 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.
      Parameters:
      user - not used.
      item - not used.
      mode - not used.
      Returns:
      always true.
      See Also:

    • modeMayBeAllowed

      public boolean modeMayBeAllowed(@Nonnull String item, @Nonnull String dataAdapter, @Nonnull Mode mode)
      Called by Lightstreamer Kernel to ask for the allowance of a publishing Mode for an Item (for at least one User). In this default implementation, a reduced version of the method is invoked, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      modeMayBeAllowed in interface MetadataProvider
      Parameters:
      item - an item name.
      dataAdapter - a Data Adapter name.
      mode - a subscription mode.
      Returns:
      true or false, demanded to the 2-arguments overload.

    • modeMayBeAllowed

      public boolean modeMayBeAllowed(@Nonnull String item, @Nonnull Mode mode)
      Reduced, backward-compatibility version of the publishing Mode allowance method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, the Metadata Adapter poses no restriction. 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 final implementation of the method MUST be different, to ensure that conflicting modes (i.e. MERGE, DISTINCT and COMMAND) are not both allowed for the same Item.
      Parameters:
      item - not used.
      mode - not used.
      Returns:
      always true.
      See Also:

    • isSelectorAllowed

      public boolean isSelectorAllowed(@Nullable String user, @Nonnull String item, @Nonnull String dataAdapter, @Nonnull 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. In this default implementation, a reduced version of the method is invoked, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      isSelectorAllowed in interface MetadataProvider
      Parameters:
      user - a user name.
      item - an item name.
      dataAdapter - a Data Adapter name.
      selector - a selector name.
      Returns:
      true or false, demanded to the 3-arguments overload.

    • isSelectorAllowed

      public boolean isSelectorAllowed(@Nullable String user, @Nonnull String item, @Nonnull String selector)
      Reduced, backward-compatibility version of the Selector authorization method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, selectors are always allowed.
      Parameters:
      user - not used.
      item - not used.
      selector - not used.
      Returns:
      always true, to mean that the Selector is allowed.
      See Also:

    • isSelected

      public boolean isSelected(@Nullable String user, @Nonnull String item, @Nonnull String dataAdapter, @Nonnull String selector, @Nonnull 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. If the return value is true, the event is dispatched to the ItemEventBuffer; otherwise, it is filtered out. In this default implementation, a reduced version of the method is invoked, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      isSelected in interface MetadataProvider
      Parameters:
      user - a user name.
      item - an item name.
      dataAdapter - a Data Adapter name.
      selector - a selector name.
      event - an update event.
      Returns:
      true or false, demanded to the 4-arguments overload.

    • isSelected

      public boolean isSelected(@Nullable String user, @Nonnull String item, @Nonnull String selector, @Nonnull ItemEvent event)
      Reduced, backward-compatibility version of the Selector implementation method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, no event is filtered out, regardless of the Selector.
      Parameters:
      user - not used.
      item - not used.
      selector - not used.
      event - not used.
      Returns:
      always true, to mean that the event is to be processed by the ItemEventBuffer.
      See Also:

    • enableUpdateCustomization

      public boolean enableUpdateCustomization(@Nullable String user, @Nonnull String item, @Nonnull String dataAdapter)
      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. In this default implementation, a reduced version of the method is invoked, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      enableUpdateCustomization in interface MetadataProvider
      Parameters:
      user - a user name.
      item - an item name.
      dataAdapter - a Data Adapter name.
      Returns:
      true or false, demanded to the 2-arguments overload.

    • enableUpdateCustomization

      public boolean enableUpdateCustomization(@Nullable String user, @Nonnull String item)
      Reduced, backward-compatibility version of the Customizer authorization method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, updates are never to be modified.
      Parameters:
      user - not used.
      item - not used.
      Returns:
      always false, to mean that the Kernel should never ask for update values modifications.
      See Also:

    • customizeUpdate

      public void customizeUpdate(@Nullable String user, @Nonnull String item, @Nonnull String dataAdapter, @Nonnull 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. In this default implementation, a reduced version of the method is invoked, where the dataAdapter argument is discarded. This also ensures backward compatibility with old adapter classes derived from this one.
      Specified by:
      customizeUpdate in interface MetadataProvider
      Parameters:
      user - a user name.
      item - an item name.
      dataAdapter - a Data Adapter name.
      event - an update event.

    • customizeUpdate

      public void customizeUpdate(@Nullable String user, @Nonnull String item, @Nonnull CustomizableItemEvent event)
      Reduced, backward-compatibility version of the Customizer implementation method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, updates are never modified.
      Parameters:
      user - not used.
      item - not used.
      event - not used.
      See Also:

    • getMinSourceFrequency

      public double getMinSourceFrequency(@Nonnull String item, @Nonnull String dataAdapter)
      Called by Lightstreamer Kernel to ask for the minimum ItemEvent frequency that ensures that all subscribers of an Item can be fed with an adequate amount of information. In practice, in case of an incoming ItemEvent frequency from the Data Adapter that is greater than the specified value, Lightstreamer Kernel may prefilter the events flow, by resampling it down to the specified frequency, before feeding the ItemEventBuffers. Such prefiltering applies only for Items requested with publishing Mode MERGE or DISTINCT.
      In this default implementation, a reduced version of the method is invoked, 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
      Parameters:
      item - an item name.
      dataAdapter - a Data Adapter name.
      Returns:
      a frequency limit, demanded to the 1-arguments overload.

    • getMinSourceFrequency

      public double getMinSourceFrequency(@Nonnull String item)
      Reduced, backward-compatibility version of the Prefilter frequency configuration method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, the Metadata Adapter can't set any minimum frequency; this also enables unfiltered dispatching for Items that support it.
      Parameters:
      item - not used.
      Returns:
      always zero, to mean that incoming ItemEvents must not be prefiltered.
      See Also:

    • getDistinctSnapshotLength

      public int getDistinctSnapshotLength(@Nonnull String item, @Nonnull String dataAdapter)
      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 this default implementation, a reduced version of the method is invoked, 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
      Parameters:
      item - an item name.
      dataAdapter - a Data Adapter name.
      Returns:
      a snapshot length, demanded to the 1-arguments overload.

    • getDistinctSnapshotLength

      public int getDistinctSnapshotLength(@Nonnull String item)
      Reduced, backward-compatibility version of the Snapshot length configuration method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, 0 events are specified, so snapshot will not be managed.
      Parameters:
      item - not used.
      Returns:
      a value of 0, to mean that no events will be kept in order to satisfy snapshot requests.
      See Also:

    • notifyUserMessage

      public CompletableFuture<String> notifyUserMessage(@Nullable String user, @Nonnull String sessionID, @Nonnull String message) throws CreditsException, NotificationException
      Called by Lightstreamer Kernel to forward a message received by a User. In this default implementation, the Metadata Adapter does never accept the message. As the processing is immediate, we don't need to return a CompletableFuture, but can just throw an exception.
      Specified by:
      notifyUserMessage in interface MetadataProvider
      Parameters:
      user - not used.
      sessionID - not used.
      message - not used.
      Returns:
      never done.
      Throws:
      CreditsException - always thrown.
      NotificationException - never thrown.

    • notifyNewSession

      public void notifyNewSession(@Nullable String user, @Nonnull String sessionID, @Nonnull Map clientContext) throws CreditsException, NotificationException
      Called by Lightstreamer Kernel to check that a User is enabled to open a new push Session. In this default implementation, a reduced version of the method is invoked, where the clientContext argument is discarded. This also ensures backward compatibility with very old adapter classes derived from this one.
      Specified by:
      notifyNewSession in interface MetadataProvider
      Parameters:
      user - A User name.
      sessionID - The ID of a new Session.
      clientContext - a Map of key-value pairs with client context information.
      Throws:
      CreditsException - demanded to the 2-arguments overload.
      NotificationException - demanded to the 2-arguments overload.

    • notifyNewSession

      public void notifyNewSession(@Nullable String user, @Nonnull String sessionID) throws CreditsException, NotificationException
      Reduced, backward-compatibility version of the Session authorization method. In case the standard version of the method is not overridden, this version of the method is invoked. In this default implementation, the Metadata Adapter poses no restriction.
      Parameters:
      user - not used.
      sessionID - not used.
      Throws:
      CreditsException - never thrown.
      NotificationException - never thrown.
      See Also:

    • notifySessionClose

      public void notifySessionClose(@Nonnull String sessionID) throws NotificationException
      Called by Lightstreamer Kernel to notify the Metadata Adapter that a push Session has been closed. In this default implementation, the Metadata Adapter does nothing, because it doesn't need to remember the open Sessions.
      Specified by:
      notifySessionClose in interface MetadataProvider
      Parameters:
      sessionID - not used.
      Throws:
      NotificationException - never thrown.

    • wantsTablesNotification

      public boolean wantsTablesNotification(@Nullable 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. In this default implementation, the Metadata Adapter doesn't require such notifications.
      Specified by:
      wantsTablesNotification in interface MetadataProvider
      Parameters:
      user - not used.
      Returns:
      always false, to prevent being notified with notifyNewTables and notifyTablesClose.

    • notifyNewTables

      public void notifyNewTables(@Nullable String user, @Nonnull String sessionID, @Nonnull TableInfo[] tables) throws CreditsException, NotificationException
      Called by Lightstreamer Kernel 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. In this default implementation, the Metadata Adapter poses no restriction. Unless the wantsTablesNotification(java.lang.String) method is overridden, this method will never be called by Lightstreamer Kernel.
      Specified by:
      notifyNewTables in interface MetadataProvider
      Parameters:
      user - not used.
      sessionID - not used.
      tables - not used.
      Throws:
      CreditsException - never thrown.
      NotificationException - never thrown.

    • notifyTablesClose

      public void notifyTablesClose(@Nonnull String sessionID, @Nonnull TableInfo[] tables) throws NotificationException
      Called by Lightstreamer Kernel to notify the Metadata Adapter that some Tables (i.e.: Subscriptions) have been removed from a push Session. In this default implementation, the Metadata Adapter does nothing, because it doesn't need to remember the Tables used. Unless the wantsTablesNotification(java.lang.String) method is overridden, this method will never be called by Lightstreamer Kernel.
      Specified by:
      notifyTablesClose in interface MetadataProvider
      Parameters:
      sessionID - not used.
      tables - not used.
      Throws:
      NotificationException - never thrown.

    • notifyMpnDeviceAccess

      public void notifyMpnDeviceAccess(@Nullable String user, @Nonnull String sessionID, @Nonnull MpnDeviceInfo device) throws CreditsException, NotificationException
      Called by Lightstreamer Kernel to check that a User is enabled to access the specified MPN device. In this default implementation, the Metadata Adapter poses no restriction.
      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).
      Specified by:
      notifyMpnDeviceAccess in interface MetadataProvider
      Parameters:
      user - not used.
      sessionID - not used.
      device - not used.
      Throws:
      CreditsException - never thrown.
      NotificationException - never thrown.

    • notifyMpnSubscriptionActivation

      public void notifyMpnSubscriptionActivation(@Nullable String user, @Nonnull String sessionID, @Nonnull TableInfo table, @Nonnull MpnSubscriptionInfo mpnSubscription) throws CreditsException, NotificationException
      Called by Lightstreamer Kernel to check that a User is enabled to activate a Push Notification subscription. In this default implementation, the Metadata Adapter poses no restriction.
      Edition Note:
      Push Notifications is an optional feature, available depending on Edition and License Type.
      Specified by:
      notifyMpnSubscriptionActivation in interface MetadataProvider
      Parameters:
      user - not used.
      sessionID - not used.
      table - not used.
      mpnSubscription - not used.
      Throws:
      CreditsException - never thrown.
      NotificationException - never thrown.

    • notifyMpnDeviceTokenChange

      public void notifyMpnDeviceTokenChange(@Nullable String user, @Nonnull String sessionID, @Nonnull MpnDeviceInfo device, @Nonnull String newDeviceToken) throws CreditsException, NotificationException
      Called by Lightstreamer Kernel to check that a User is enabled to change the token of a MPN device. In this default implementation, the Metadata Adapter poses no restriction.
      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).
      Specified by:
      notifyMpnDeviceTokenChange in interface MetadataProvider
      Parameters:
      user - not used.
      sessionID - not used.
      device - not used.
      newDeviceToken - not used.
      Throws:
      CreditsException - never thrown.
      NotificationException - never thrown.