com.ibm.wsspi.usage.metering

Interface ProductExtension



  • public interface ProductExtension
    Provides product specific extensions and metrics for products that have been identified from the installed product version and tag files.

    Stack/embedding products that will be registered by the WebSphere application server usageMetering feature may need to provide additional product information and/or metrics that aren't available to WebSphere application server in the product version (and tag) files. Products accomplish this by providing an implementation of this interface and registering it in the server registry. Some examples of additional information include APARs, product specific data, and usage metrics.

    Implementors of this interface should register this service in the service registry early during server startup. The service must be registered with the following service property:

    • com.ibm.websphere.productId which is set to the value fetched from the product extension location info file.
    One area to note for Liberty is a stack product that is installed, but no stack features are enabled for the runtime, will not have an opportunity to add this specific information, thus the lack of this information if expected should not be interpreted as a lack of APARs, or data, but a lack of usage of the product in question.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void enableUsageDataCollection(boolean enable)
      Enables usage data collection for the product.
      java.util.Set<java.lang.String> getApars()
      The list of APARs installed for this product.
      Usage getCurrentUsage()
      Provides the product specific usage data for the current collection interval ending with the current system time.
      java.util.List<Group> getGroups(java.util.List<Group> combinedGroups)
      Returns the product groups for software registration.
      java.util.Set<MetricDescriptor> getMetricDescriptors(java.util.List<Group> groups)
      Returns a set of metric descriptors for the metrics that will be provided by this product.
      java.lang.String getPatchVersion(java.lang.String baseVersion)
      Returns the patch version of the installed product.
      java.util.Map<java.lang.String,java.lang.Object> getProductSpecificData()
      Returns the product specific data for software registration.
      int getProductWeight()
      Returns the priority of this product relative to other installed products.
      void resetUsageDataCollection()
      Resets the start time for usage data collection to the current system time.
      void setRegistrationListener(RegistrationListener listener)
      Provides a registration listener that may be used by a product extension implementation to notify the usageMetering feature that product extension data has changed since registration and the new information should be re-submitted.
    • Method Detail

      • getProductWeight

        int getProductWeight()
        Returns the priority of this product relative to other installed products. A larger value represents a higher priority product. Products will be registered in weight order. Products with the same weight will be ordered using the product persistent id.

        The weight of the JDK will be 0; the JDK will always be last in the list of products.

        The weight of the WebSphere application server product will be 500. Any other product that should be listed as the primary product would enhance the product to return a value greater than 500. The default weight is 300. Any installed product that does not provide an implementation of the ProductExtension interface will have a weight of 300 and will not be considered the primary product.

      • getPatchVersion

        java.lang.String getPatchVersion(java.lang.String baseVersion)
        Returns the patch version of the installed product. Null should be returned if a patch version has not been installed.

        This method is only called When a patch version .swidtag file is not present, to allow products that provide patch versions without additional .swidtag files. The base version from the existing .swidtag file is provided for reference.

        Parameters:
        baseVersion - the base version of the installed product from the .swidtag file.
        Returns:
        the patch version of the installed product, or null.
      • getApars

        java.util.Set<java.lang.String> getApars()
        The list of APARs installed for this product.
      • getGroups

        java.util.List<Group> getGroups(java.util.List<Group> combinedGroups)
        Returns the product groups for software registration. The returned list must order the groups such that sub-groups appear after the corresponding parent group.

        This method is called on each product extension, in revere order of priority so that the primary product is called last. The configured groups are provided on the call to the first product extension, and the combined list is provided on each subsequent call. Each product extension may either add new groups to the list, return the same list, or remove groups (though removing groups should be done with caution). Returning null is the equivalent of returning the combined groups parameter.

        Parameters:
        combinedGroups - configured groups and groups from other products.
        Returns:
        the new list of combined groups, or empty list if no groups are to be sent on registration; null will result in combinedGroups being reported.
      • getMetricDescriptors

        java.util.Set<MetricDescriptor> getMetricDescriptors(java.util.List<Group> groups)
        Returns a set of metric descriptors for the metrics that will be provided by this product. The metric descriptor information will be reported during software registration and is used to control how the metrics will be displayed.
        Parameters:
        groups - - a set of all groups any metric should belong to
        Returns:
        the metric descriptors
      • getProductSpecificData

        java.util.Map<java.lang.String,java.lang.Object> getProductSpecificData()
        Returns the product specific data for software registration.

        The values included in the returned map must be one of the following four types: String, Number, Collection, Map; where Collection and Map must also contain one of the same four types.

        The returned value will be combined with product specific data for all installed products, included in priority order; see getProductWeight().

        Returns:
        the product specific data.
      • setRegistrationListener

        void setRegistrationListener(RegistrationListener listener)
        Provides a registration listener that may be used by a product extension implementation to notify the usageMetering feature that product extension data has changed since registration and the new information should be re-submitted.

        An instance of RegistrationListener will be provided to a registered ProductExtension prior to the first access of product extension data.

        Parameters:
        listener - the usageMetering feature registration listener
      • enableUsageDataCollection

        void enableUsageDataCollection(boolean enable)
        Enables usage data collection for the product.

        The usageMetering feature will call this method passing true to inform a product to begin the collection of usage metrics. The next collection of metrics returned by getCurrentUsage() should cover an interval beginning with the current system time of this method call.

        This method will be called with false when either the usageMetering feature has been disabled or the server process is being stopped.

        Parameters:
        enable - true indicates the start of usage metric collection; false indicates usage metric collection has stopped.
      • resetUsageDataCollection

        void resetUsageDataCollection()
        Resets the start time for usage data collection to the current system time.

        This method is called in the event an unexpected situation has occurred during usage data collection and usage information prior to the current time should be discarded. An example of such a scenario is when getCurrentUsage() has been called but does not return within a reasonable time. Usage data collection for the prior time interval is aborted and this method is used to inform the product that the start time for the next interval to be collected is the current system time.

      • getCurrentUsage

        Usage getCurrentUsage()
        Provides the product specific usage data for the current collection interval ending with the current system time.

        The start time is the time of the most recent call to one of the following :

        The returned instance of Usage provides the product specific metrics, environment, grouping data, and any other product specific data associated with the collection interval.

        A product should return null if no product specific metrics will be provided, or if usage data collection has not been enabled.

        Returns:
        the product specific usage data for the current time interval; or null if the product will not provide metrics or data collection is not currently enabled.