Package com.opencloud.rhino.facilities.usage

Interface UsageParametersInterface

  • public interface UsageParametersInterface

    Base interface for a usage parameters interface. A usage parameters interface must be public and defined in a named package, and may extend this interface to obtain common functionality. While it is generally recommended that a usage parameters interface extend this interface, there may be legitimate reasons why this might not be desirable, for example the application doesn’t want to expose these API methods to third-party code plugins that just need to define their own usage parameters.

    A usage parameters interface may be annotated with the @UsageParameters annotation in order to provide additional information to the SLEE about the usage parameter set.

    The usage parameters interface defines usage parameters as follows:

    Counter-type usage parameters

    Counter-type usage parameters are defined using either or both an increment method:

    public void increment<usage-parameter-name>(long value);

    or set method:

    public void set<usage-parameter-name>(long value);

    Usage counter methods may be annotated with the @UsageCounter annotation in order to provide additional information to the SLEE about the parameter. In the case where both an increment and set method has been defined for a given parameter, only one of the methods need be annotated. If both methods are annotated the annotation used is chosen arbitrarily.

    An accessor method may also be defined for a counter-type usage parameter with the signature:

    public long get<usage-parameter-name>();

    Sample-type usage parameters

    Sample-type usage parameters are defined using a sample method:

    public void sample<usage-parameter-name>(long value);

    An accessor method may also be defined for a sample-type usage parameter with the signature:

    public SampleStatistics get<usage-parameter-name>();

    SampleStatistics is a JSLEE-defined class.

    In the above method declarations, usage-parameter-name is the name of the usage parameter, where the first letter has been uppercased. Usage methods must not have a throws clause. Usage methods, and all methods defined in this interface, run in an unspecified transaction context. Updates to usage parameters occur regardless of the outcome of any transaction active at the time of the update.

    Since:
    Rhino 2.4.0

    • Method Detail

      • name

        String name()

        Get the name of this parameter set. This is the name that the parameter set was created with. The root usage parameter set has no name, so this method will return null for that usage parameter set.

        This method is a non-transactional method.

        Returns:
        the name of the usage parameter set, or null if this is the root usage parameter set.
        Since:
        Rhino 2.4.0

      • type

        String type()

        Get the type of this usage parameter set.

        This method is a non-transactional method.

        Returns:
        the type of the usage parameter set, or null if this usage parameter set has no type.
        Since:
        Rhino 2.4.0

      • key

        String key()

        Get the key that identifies this usage parameter set. This key can be used to recover the same usage parameter set at a later time using the Usage Facility.

        The key for the root usage parameter set is the empty string.

        This method is a non-transactional method.

        Returns:
        the key for this usage parameter set.
        Since:
        Rhino 2.4.0

      • getOrCreateChild

        <T> T getOrCreateChild​(String name)
                throws NullPointerException,
                       IllegalArgumentException,
                       SLEEException

        Get the child usage parameter set with the given name. If the child doesn’t currently exist it will be created with the same type as this usage parameter set.

        This method is a non-transactional method.

        Parameters:
        name - the name of the child usage parameter set.
        Returns:
        the child usage parameter set.
        Throws:
        NullPointerException - if name is null.
        IllegalArgumentException - if name is zero-length.
        SLEEException - if a system-level failure occurs.
        Since:
        Rhino 2.4.0

      • hasChild

        boolean hasChild​(String name)
          throws NullPointerException,
                 SLEEException

        Determine if a child usage parameter set with the given name currently exists.

        This method is a non-transactional method.

        Parameters:
        name - the name of the child usage parameter set.
        Returns:
        true if a child usage parameter set with the given name currently exists, false otherwise.
        Throws:
        NullPointerException - if name is null.
        SLEEException - if a system-level failure occurs.
        Since:
        Rhino 2.4.0

      • children

        Collection<? extends UsageParametersInterface> children()
                                                 throws SLEEException

        Get all child usage parameter sets of this usage parameter set.

        This method is a non-transactional method.

        Returns:
        a collection of all child usage parameter sets.
        Throws:
        SLEEException - if a system-level failure occurs.
        Since:
        Rhino 2.4.0

      • parent

        <T> T parent()
      throws SLEEException

        Get the parent usage parameter set of this usage parameter set.

        This method is a non-transactional method.

        Returns:
        the parent usage parameter set, or null if this is the root usage parameter set.
        Throws:
        SLEEException - if a system-level failure occurs.
        Since:
        Rhino 2.4.0

      • remove

        void remove()
     throws SLEEException

        Remove this usage parameter set. All child usage parameter sets are also removed.

        While it is not possible to remove the root usage parameter set, this method may be invoked on the root usage parameter set in order to easily remove all its child usage parameter sets. Invoking this method on the root usage parameter set will also reset all usage statistics as if the parameter set had been removed and immediately recreated.

        This method is a non-transactional method.

        Throws:
        SLEEException - if a system-level failure occurs.
        Since:
        Rhino 2.4.0