StatusVariable
Date: 2016-06-25

org.osgi.service.monitor

## Class StatusVariable

- java.lang.Object
- - org.osgi.service.monitor.StatusVariable

-     public final class StatusVariable
      extends java.lang.Object

  A `StatusVariable` object represents the value of a status variable taken with a certain collection method at a certain point of time. The type of the `StatusVariable` can be `int`, `float`, `boolean` or `String`.

  A `StatusVariable` is identified by an ID string that is unique within the scope of a `Monitorable`. The ID must be a non- `null`, non-empty string that conforms to the "symbolic-name" definition in the OSGi core specification. This means that only the characters [-_.a-zA-Z0-9] may be used. The length of the ID must not exceed 32 bytes when UTF-8 encoded.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CM_CC` Constant for identifying 'Cumulative Counter' data collection method.
    `static int` | `CM_DER` Constant for identifying 'Discrete Event Registration' data collection method.
    `static int` | `CM_GAUGE` Constant for identifying 'Gauge' data collection method.
    `static int` | `CM_SI` Constant for identifying 'Status Inspection' data collection method.
    `static int` | `TYPE_BOOLEAN` Constant for identifying `boolean` data type.
    `static int` | `TYPE_FLOAT` Constant for identifying `float` data type.
    `static int` | `TYPE_INTEGER` Constant for identifying `int` data type.
    `static int` | `TYPE_STRING` Constant for identifying `String` data type.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StatusVariable(java.lang.String id, int cm, boolean data)` Constructor for a `StatusVariable` of `boolean` type.
    `StatusVariable(java.lang.String id, int cm, float data)` Constructor for a `StatusVariable` of `float` type.
    `StatusVariable(java.lang.String id, int cm, int data)` Constructor for a `StatusVariable` of `int` type.
    `StatusVariable(java.lang.String id, int cm, java.lang.String data)` Constructor for a `StatusVariable` of `String` type.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Compares the specified object with this `StatusVariable`.
    `boolean` | `getBoolean()` Returns the `StatusVariable` value if its type is `boolean`.
    `int` | `getCollectionMethod()` Returns the collection method of this `StatusVariable`.
    `float` | `getFloat()` Returns the `StatusVariable` value if its type is `float`.
    `java.lang.String` | `getID()` Returns the ID of this `StatusVariable`.
    `int` | `getInteger()` Returns the `StatusVariable` value if its type is `int`.
    `java.lang.String` | `getString()` Returns the `StatusVariable` value if its type is `String`.
    `java.util.Date` | `getTimeStamp()` Returns the timestamp associated with the `StatusVariable`.
    `int` | `getType()` Returns information on the data type of this `StatusVariable`.
    `int` | `hashCode()` Returns the hash code value for this `StatusVariable`.
    `java.lang.String` | `toString()` Returns a `String` representation of this `StatusVariable`.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### TYPE_INTEGER

          public static final int TYPE_INTEGER

      Constant for identifying `int` data type.
      See Also:
        Constant Field Values

    - #### TYPE_FLOAT

          public static final int TYPE_FLOAT

      Constant for identifying `float` data type.
      See Also:
        Constant Field Values

    - #### TYPE_STRING

          public static final int TYPE_STRING

      Constant for identifying `String` data type.
      See Also:
        Constant Field Values

    - #### TYPE_BOOLEAN

          public static final int TYPE_BOOLEAN

      Constant for identifying `boolean` data type.
      See Also:
        Constant Field Values

    - #### CM_CC

          public static final int CM_CC

      Constant for identifying 'Cumulative Counter' data collection method.
      See Also:
        Constant Field Values

    - #### CM_DER

          public static final int CM_DER

      Constant for identifying 'Discrete Event Registration' data collection method.
      See Also:
        Constant Field Values

    - #### CM_GAUGE

          public static final int CM_GAUGE

      Constant for identifying 'Gauge' data collection method.
      See Also:
        Constant Field Values

    - #### CM_SI

          public static final int CM_SI

      Constant for identifying 'Status Inspection' data collection method.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### StatusVariable

          public StatusVariable(java.lang.String id,
                        int cm,
                        int data)

      Constructor for a `StatusVariable` of `int` type.
      Parameters:
        `id` - the identifier of the `StatusVariable`
        `cm` - the collection method, one of the `CM_` constants
        `data` - the `int` value of the `StatusVariable`
      Throws:
        `java.lang.IllegalArgumentException` - if the given `id` is not a valid `StatusVariable` name, or if `cm` is not one of the collection method constants
        `java.lang.NullPointerException` - if the `id` parameter is `null`

    - #### StatusVariable

          public StatusVariable(java.lang.String id,
                        int cm,
                        float data)

      Constructor for a `StatusVariable` of `float` type.
      Parameters:
        `id` - the identifier of the `StatusVariable`
        `cm` - the collection method, one of the `CM_` constants
        `data` - the `float` value of the `StatusVariable`
      Throws:
        `java.lang.IllegalArgumentException` - if the given `id` is not a valid `StatusVariable` name, or if `cm` is not one of the collection method constants
        `java.lang.NullPointerException` - if the `id` parameter is `null`

    - #### StatusVariable

          public StatusVariable(java.lang.String id,
                        int cm,
                        boolean data)

      Constructor for a `StatusVariable` of `boolean` type.
      Parameters:
        `id` - the identifier of the `StatusVariable`
        `cm` - the collection method, one of the `CM_` constants
        `data` - the `boolean` value of the `StatusVariable`
      Throws:
        `java.lang.IllegalArgumentException` - if the given `id` is not a valid `StatusVariable` name, or if `cm` is not one of the collection method constants
        `java.lang.NullPointerException` - if the `id` parameter is `null`

    - #### StatusVariable

          public StatusVariable(java.lang.String id,
                        int cm,
                        java.lang.String data)

      Constructor for a `StatusVariable` of `String` type.
      Parameters:
        `id` - the identifier of the `StatusVariable`
        `cm` - the collection method, one of the `CM_` constants
        `data` - the `String` value of the `StatusVariable`, can be `null`
      Throws:
        `java.lang.IllegalArgumentException` - if the given `id` is not a valid `StatusVariable` name, or if `cm` is not one of the collection method constants
        `java.lang.NullPointerException` - if the `id` parameter is `null`

  - ### Method Detail

    - #### getID

          public java.lang.String getID()

      Returns the ID of this `StatusVariable`. The ID is unique within the scope of a `Monitorable`.
      Returns:
        the ID of this `StatusVariable`

    - #### getType

          public int getType()

      Returns information on the data type of this `StatusVariable`.
      Returns:
        one of the `TYPE_` constants indicating the type of this `StatusVariable`

    - #### getTimeStamp

          public java.util.Date getTimeStamp()

      Returns the timestamp associated with the `StatusVariable`. The timestamp is stored when the `StatusVariable` instance is created, generally during the `Monitorable.getStatusVariable(String)` method call.
      Returns:
        the time when the `StatusVariable` value was queried, cannot be `null`

    - #### getString

          public java.lang.String getString()
                                     throws java.lang.IllegalStateException

      Returns the `StatusVariable` value if its type is `String`.
      Returns:
        the `StatusVariable` value as a `String`
      Throws:
        `java.lang.IllegalStateException` - if the type of the `StatusVariable` is not `String`

    - #### getInteger

          public int getInteger()
                         throws java.lang.IllegalStateException

      Returns the `StatusVariable` value if its type is `int`.
      Returns:
        the `StatusVariable` value as an `int`
      Throws:
        `java.lang.IllegalStateException` - if the type of this `StatusVariable` is not `int`

    - #### getFloat

          public float getFloat()
                         throws java.lang.IllegalStateException

      Returns the `StatusVariable` value if its type is `float`.
      Returns:
        the `StatusVariable` value as a `float`
      Throws:
        `java.lang.IllegalStateException` - if the type of this `StatusVariable` is not `float`

    - #### getBoolean

          public boolean getBoolean()
                             throws java.lang.IllegalStateException

      Returns the `StatusVariable` value if its type is `boolean`.
      Returns:
        the `StatusVariable` value as a `boolean`
      Throws:
        `java.lang.IllegalStateException` - if the type of this `StatusVariable` is not `boolean`

    - #### getCollectionMethod

          public int getCollectionMethod()

      Returns the collection method of this `StatusVariable`. See section 3.3 b) in [ETSI TS 132 403]
      Returns:
        one of the `CM_` constants

    - #### equals

          public boolean equals(java.lang.Object obj)

      Compares the specified object with this `StatusVariable`. Two `StatusVariable` objects are considered equal if their full path, collection method and type are identical, and the data (selected by their type) is equal.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object to compare with this `StatusVariable`
      Returns:
        `true` if the argument represents the same `StatusVariable` as this object

    - #### hashCode

          public int hashCode()

      Returns the hash code value for this `StatusVariable`. The hash code is calculated based on the full path, collection method and value of the `StatusVariable`.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code of this object

    - #### toString

          public java.lang.String toString()

      Returns a `String` representation of this `StatusVariable`. The returned `String` contains the full path, collection method, timestamp, type and value parameters of the `StatusVariable` in the following format:

           StatusVariable(<path>, <cm>, <timestamp>, <type>, <value>)

      The collection method identifiers used in the string representation are "CC", "DER", "GAUGE" and "SI" (without the quotes). The format of the timestamp is defined by the `Date.toString` method, while the type is identified by one of the strings "INTEGER", "FLOAT", "STRING" and "BOOLEAN". The final field contains the string representation of the value of the status variable.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the `String` representation of this `StatusVariable`