com.h3c.sdn.adm.metric

## Interface MetricService

-     public interface MetricService

  Interface for interacting with the Metering service within the controller.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `WILDCARD` Constant the represents a wildcard parameter during communication between metering REST and business logic layers.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `configureAgingDays(int days)` Method that can be called to change the metering configuration for how long persisted data is retained.
    `TimeStampedCounter` | `createCounter(CounterDescriptor descriptor)` Returns a new `TimeStampedCounter` object based upon the provided `CounterDescriptor`.
    `TimeStampedGauge` | `createGauge(GaugeDescriptor descriptor)` Returns a new `TimeStampedGauge` object based upon the provided `GaugeDescriptor`.
    `TimeStampedHistogram` | `createHistogram(HistogramDescriptor descriptor)` Returns a new `TimeStampedHistogram` object based upon the provided `HistogramDescriptor`.
    `TimeStampedMeter` | `createMeter(MeterDescriptor descriptor)` Returns a new `TimeStampedMeter` object based upon the provided `MeterDescriptor`.
    `TimeStampedRatioGauge` | `createRatioGauge(RatioGaugeDescriptor descriptor)` Returns a new `TimeStampedRatioGauge` object based upon the provided `RatioGaugeDescriptor`.
    `TimeStampedRollingCounter` | `createRollingCounter(RollingCounterDescriptor descriptor)` Returns a new `TimeStampedRollingCounter` object based upon the provided `RollingCounterDescriptor`.
    `TimeStampedTimer` | `createTimer(TimerDescriptor descriptor)` Returns a new `TimeStampedTimer` object based upon the provided `TimerDescriptor`.
    `Map<String,String>` | `getApplications()` Returns application IDs and names for applications that have metrics persisted for them.
    `MetricDescriptor` | `getMetric(String uid)` Returns the descriptor details of an existing metric if found
    `Set<String>` | `getMetricNames(String appId, String primaryTag, String secondaryTag)` Returns metric names associated with the application ID, primary tag, and secondary tag.
    `Map<MetricDescriptor,String>` | `getPersistedMetrics(String appId, String primaryTag, String secondaryTag, String name)` Returns all persisted metrics registered and available from the specified application, primaryTag, secondaryTag and metric name.
    `Set<String>` | `getPrimaryTags(String appId, String name)` Returns primary tags associated with the application ID and metric name.
    `Set<String>` | `getSecondaryTags(String appId, String name, String primaryTag)` Returns secondary tags associated with the application ID, primary tag, and metric name.
    `String` | `getUid(String appId, String name, String primaryTag, String secondaryTag)` Returns the `UID` of the specific metric identified by an application ID, metric name, primary tag, and secondary tag.
    `Set<String>` | `getUids(String appId)` Returns metric `UIDs` associated with an application ID.
    `Set<String>` | `getUids(String appId, String name)` Returns metric `UIDs` associated with the application ID and metric name.
    `Set<String>` | `getUids(String appId, String name, String primaryTag)` Returns metric `UIDs` associated with the application ID, primary tag, and metric name.
    `MetricValue` | `getValue(String uid)` Returns the latest `MetricValue` based on the specified metric `UID`.
    `List<MetricValue>` | `getValues(String uid, Date beginDate, Date endDate, long interval)` Returns `MetricValue`s based on the specified metric `UID`, the time range, and the summary interval.
    `TimeStampedMetric` | `recreateMetric(String uid)` Recreates a previously existing `TimeStampedMetric` with the specified `UID`.
    `void` | `registerMetric(TimeStampedMetric toRegister)` Registers an existing `TimeStampedMetric` with the metering framework.
    `void` | `removeMetric(TimeStampedMetric toRemove)` Removes an existing `TimeStampedMetric` object from the metering framework, essentially unregistering it so that the framework no longer processes its values.

- - ### Field Detail

    - #### WILDCARD

          static final String WILDCARD

      Constant the represents a wildcard parameter during communication between metering REST and business logic layers.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### configureAgingDays

          void configureAgingDays(int days)

      Method that can be called to change the metering configuration for how long persisted data is retained.
      Parameters:
        `days` - the number of days to age the data

    - #### createCounter

          TimeStampedCounter createCounter(CounterDescriptor descriptor)

      Returns a new `TimeStampedCounter` object based upon the provided `CounterDescriptor`.
      Parameters:
        `descriptor` - `CounterDescriptor` initialized to embody the desired properties of the `TimeStampedCounter` to be created
      Returns:
        resultant `TimeStampedCounter` object

    - #### createGauge

          TimeStampedGauge createGauge(GaugeDescriptor descriptor)

      Returns a new `TimeStampedGauge` object based upon the provided `GaugeDescriptor`.
      Parameters:
        `descriptor` - `GaugeDescriptor` initialized to embody the desired properties of the `TimeStampedGauge` to be created
      Returns:
        resultant `TimeStampedGauge` object

    - #### createHistogram

          TimeStampedHistogram createHistogram(HistogramDescriptor descriptor)

      Returns a new `TimeStampedHistogram` object based upon the provided `HistogramDescriptor`.
      Parameters:
        `descriptor` - `HistogramDescriptor` initialized to embody the desired properties of the `TimeStampedHistogram` to be created
      Returns:
        resultant `TimeStampedHistogram` object

    - #### createMeter

          TimeStampedMeter createMeter(MeterDescriptor descriptor)

      Returns a new `TimeStampedMeter` object based upon the provided `MeterDescriptor`.
      Parameters:
        `descriptor` - `MeterDescriptor` initialized to embody the desired properties of the `TimeStampedMeter` to be created
      Returns:
        resultant `TimeStampedMeter` object

    - #### createRatioGauge

          TimeStampedRatioGauge createRatioGauge(RatioGaugeDescriptor descriptor)

      Returns a new `TimeStampedRatioGauge` object based upon the provided `RatioGaugeDescriptor`.
      Parameters:
        `descriptor` - `RatioGaugeDescriptor` initialized to embody the desired properties of the `TimeStampedRatioGauge` to be created
      Returns:
        resultant `TimeStampedRatioGauge` object

    - #### createRollingCounter

          TimeStampedRollingCounter createRollingCounter(RollingCounterDescriptor descriptor)

      Returns a new `TimeStampedRollingCounter` object based upon the provided `RollingCounterDescriptor`.
      Parameters:
        `descriptor` - `RollingCounterDescriptor` initialized to embody the desired properties of the `TimeStampedRollingCounter` to be created
      Returns:
        resultant `TimeStampedRollingCounter` object

    - #### createTimer

          TimeStampedTimer createTimer(TimerDescriptor descriptor)

      Returns a new `TimeStampedTimer` object based upon the provided `TimerDescriptor`.
      Parameters:
        `descriptor` - `TimerDescriptor` initialized to embody the desired properties of the `TimeStampedTimer` to be created
      Returns:
        resultant `TimeStampedTimer` object

    - #### getPersistedMetrics

          Map<MetricDescriptor,String> getPersistedMetrics(String appId,
                                                         String primaryTag,
                                                         String secondaryTag,
                                                         String name)

      Returns all persisted metrics registered and available from the specified application, primaryTag, secondaryTag and metric name.
      Parameters:
        `appId` - application ID to filter the results with; if no value is specified the ID corresponding to the base controller will be used
        `primaryTag` - primary tag to filter the results with; if no value is specified a default value will be used
        `secondaryTag` - secondary tag to filter the results with; if no value is specified a default value will be used
        `name` - metric name to filter the results with; if no value is specified this field will be ignored
      Returns:
        `Map` of `MetricDescriptor`s

    - #### getMetric

          MetricDescriptor getMetric(String uid)

      Returns the descriptor details of an existing metric if found
      Parameters:
        `uid` - The unique metric identifier
      Returns:
        `MetricDescriptor`

    - #### getApplications

          Map<String,String> getApplications()

      Returns application IDs and names for applications that have metrics persisted for them. Includes applications with metrics that have readable values which have not been aged (i.e. metrics that still have data on disk but may or may not be actively updated).
      Returns:
        `Map` of application IDs to application names

    - #### getMetricNames

          Set<String> getMetricNames(String appId,
                                   String primaryTag,
                                   String secondaryTag)

      Returns metric names associated with the application ID, primary tag, and secondary tag.
      Parameters:
        `appId` - application ID
        `primaryTag` - primary tag associated with the metric; may be the reserved `WILDCARD` value or may be null
        `secondaryTag` - secondary tag associated with the metric; may be the reserved `WILDCARD` value or may be null
      Returns:
        `Set` of metric names associated with the application ID, primary tag, and secondary tag

    - #### getPrimaryTags

          Set<String> getPrimaryTags(String appId,
                                   String name)

      Returns primary tags associated with the application ID and metric name.
      Parameters:
        `appId` - application ID
        `name` - metric name; may be the reserved `WILDCARD` value
      Returns:
        `Set` of primary tags associated with the specific application and name

    - #### getSecondaryTags

          Set<String> getSecondaryTags(String appId,
                                     String name,
                                     String primaryTag)

      Returns secondary tags associated with the application ID, primary tag, and metric name.
      Parameters:
        `appId` - application ID
        `name` - metric name; may be the reserved `WILDCARD` value
        `primaryTag` - primary tag associated with the metric; may be the reserved `WILDCARD` value or may be null
      Returns:
        `Set` of secondary tags associated with the application ID, metric name, and primary tag

    - #### getUid

          String getUid(String appId,
                      String name,
                      String primaryTag,
                      String secondaryTag)

      Returns the `UID` of the specific metric identified by an application ID, metric name, primary tag, and secondary tag.
      Parameters:
        `appId` - application ID
        `name` - metric name
        `primaryTag` - primary tag
        `secondaryTag` - secondary tag
      Returns:
        metric `UID`

    - #### getUids

          Set<String> getUids(String appId)

      Returns metric `UIDs` associated with an application ID.
      Parameters:
        `appId` - application ID
      Returns:
        `Set` of metric `UIDs`

    - #### getUids

          Set<String> getUids(String appId,
                            String name)

      Returns metric `UIDs` associated with the application ID and metric name.
      Parameters:
        `appId` - application ID
        `name` - metric name
      Returns:
        `Set` of metric `UIDs`

    - #### getUids

          Set<String> getUids(String appId,
                            String name,
                            String primaryTag)

      Returns metric `UIDs` associated with the application ID, primary tag, and metric name.
      Parameters:
        `appId` - application ID
        `name` - metric name
        `primaryTag` - primary tag
      Returns:
        `Set` of metric `UIDs`

    - #### getValue

          MetricValue getValue(String uid)
                               throws DataFormatException,
                                      IOException

      Returns the latest `MetricValue` based on the specified metric `UID`.
      Parameters:
        `uid` - metric `UID`
      Returns:
        latest `MetricValue` for the specified metric
      Throws:
        `InvalidParameterException` - if the corresponding metric identifier does not exist
        `DataFormatException` - if the expected file content cannot be read
        `IOException` - if the expected file cannot be accessed

    - #### getValues

          List<MetricValue> getValues(String uid,
                                    Date beginDate,
                                    Date endDate,
                                    long interval)
                                      throws DataFormatException,
                                             IOException

      Returns `MetricValue`s based on the specified metric `UID`, the time range, and the summary interval.
      Parameters:
        `uid` - metric `UID`
        `beginDate` - first date to include values from
        `endDate` - last date to include values from
        `interval` - summary interval in minute(s)
      Returns:
        `List` of `MetricValue`s
      Throws:
        `InvalidParameterException` - if the corresponding metric identifier does not exist
        `DataFormatException` - if the expected file content cannot be read
        `IOException` - if the expected file cannot be accessed

    - #### recreateMetric

          TimeStampedMetric recreateMetric(String uid)

      Recreates a previously existing `TimeStampedMetric` with the specified `UID`. Should the metering framework bounce while other controller components stay up, those components will still have references to `UIDs` of `TimeStampedMetric` objects allocated before the framework went down. To ensure that the metering framework processes such `TimeStampedMetric`s properly for persistence, JMX exposure, etc. after the framework comes back up they should be re-created within the metering framework after it comes back up.
      Parameters:
        `uid` - `UID` of a previously existing `TimeStampedMetric`
      Returns:
        a new `TimeStampedMetric` created with the specified `UID`

    - #### registerMetric

          void registerMetric(TimeStampedMetric toRegister)

      Registers an existing `TimeStampedMetric` with the metering framework. Should the metering framework bounce while other controller components stay up, those components will still have references to `TimeStampedMetric` objects allocated before the framework went down. To ensure that the metering framework processes such `TimeStampedMetric`s properly for persistence, JMX exposure, etc. after the framework comes back up they should be re-registered with the metering framework after it comes back up.
      Parameters:
        `toRegister` - `TimeStampedMetric` to re-register

    - #### removeMetric

          void removeMetric(TimeStampedMetric toRemove)

      Removes an existing `TimeStampedMetric` object from the metering framework, essentially unregistering it so that the framework no longer processes its values. If the `TimeStampedMetric` was exposed via JMX it will be removed from the JMX server. Values already persisted for the `TimeStampedMetric` will not be altered, but will be allowed to eventually age out if the `TimeStampedMetric` is not eventually re-registered to provide new values.
      Parameters:
        `toRemove` - `TimeStampedMetric` to remove from the metering framework

Copyright © 2014. All Rights Reserved.