org.apache.geode

## Interface StatisticsTypeFactory

- All Known Subinterfaces:
    StatisticsFactory
  All Known Implementing Classes:
    DistributedSystem

      public interface StatisticsTypeFactory

  Instances of this interface provide methods that create instances of `StatisticDescriptor` and `StatisticsType`. Every `StatisticsFactory` is also a type factory.

  A `StatisticsTypeFactory` can create a `statistic` of three numeric types: `int`, `long`, and `double`. A statistic (`StatisticDescriptor`) can either be a gauge meaning that its value can increase and decrease or a counter meaning that its value is strictly increasing. Marking a statistic as a counter allows statistic display tools to properly display a statistics whose value "wraps around" (that is, exceeds its maximum value).

  The following code is an example of how to create a type using XML. In this example the type has two stats whose values always increase:

          StatisticsTypeFactory f = ...;
          StatisticsType t = f.createType(
              "StatSampler",
              "Stats on the statistic sampler.",
              new StatisticDescriptor[] {
                  f.createIntCounter("sampleCount",
                                     "Total number of samples taken by this sampler.",
                                     "samples"),
                  f.createLongCounter("sampleTime",
                                      "Total amount of time spent taking samples.",
                                      "milliseconds"),
              }
          );

  The following is an example of how to create the same type using XML. The XML data:

          <?xml version="1.0" encoding="UTF-8"?>
          <!DOCTYPE statistics PUBLIC
            "-//GemStone Systems, Inc.//GemFire Statistics Type//EN"
            "http://www.gemstone.com/dtd/statisticsType.dtd">
          <statistics>
            <type name="StatSampler">
              <description>Stats on the statistic sampler.</description>
              <stat name="sampleCount" storage="int" counter="true">
                <description>Total number of samples taken by this sampler.</description>
                <unit>samples</unit>
              </stat>
              <stat name="sampleTime" storage="long" counter="true">
                <description>Total amount of time spent taking samples.</description>
                <unit>milliseconds</unit>
              </stat>
            </type>
          </statistics>

  The code to create the type:

            StatisticsTypeFactory f = ...;
            Reader r = new InputStreamReader("fileContainingXmlData"));
            StatisticsType type = f.createTypesFromXml(r)[0];

  Since:
    GemFire 3.0
  See Also:
    Package introduction

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MAX_DESCRIPTORS_PER_TYPE` The maximum number of descriptors a single statistics type can have.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `StatisticDescriptor` | `createDoubleCounter(java.lang.String name, java.lang.String description, java.lang.String units)` Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
    `StatisticDescriptor` | `createDoubleCounter(java.lang.String name, java.lang.String description, java.lang.String units, boolean largerBetter)` Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    `StatisticDescriptor` | `createDoubleGauge(java.lang.String name, java.lang.String description, java.lang.String units)` Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
    `StatisticDescriptor` | `createDoubleGauge(java.lang.String name, java.lang.String description, java.lang.String units, boolean largerBetter)` Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    `StatisticDescriptor` | `createIntCounter(java.lang.String name, java.lang.String description, java.lang.String units)` Creates and returns an int counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
    `StatisticDescriptor` | `createIntCounter(java.lang.String name, java.lang.String description, java.lang.String units, boolean largerBetter)` Creates and returns an int counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    `StatisticDescriptor` | `createIntGauge(java.lang.String name, java.lang.String description, java.lang.String units)` Creates and returns an int gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
    `StatisticDescriptor` | `createIntGauge(java.lang.String name, java.lang.String description, java.lang.String units, boolean largerBetter)` Creates and returns an int gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    `StatisticDescriptor` | `createLongCounter(java.lang.String name, java.lang.String description, java.lang.String units)` Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
    `StatisticDescriptor` | `createLongCounter(java.lang.String name, java.lang.String description, java.lang.String units, boolean largerBetter)` Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    `StatisticDescriptor` | `createLongGauge(java.lang.String name, java.lang.String description, java.lang.String units)` Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
    `StatisticDescriptor` | `createLongGauge(java.lang.String name, java.lang.String description, java.lang.String units, boolean largerBetter)` Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    `StatisticsType` | `createType(java.lang.String name, java.lang.String description, StatisticDescriptor[] stats)` Creates or finds and returns a `StatisticsType` with the given `name`, `description`, and `statistic descriptions`.
    `StatisticsType[]` | `createTypesFromXml(java.io.Reader reader)` Creates one or more `StatisticsType` from the contents of the given `reader`.
    `StatisticsType` | `findType(java.lang.String name)` Finds and returns an already created `StatisticsType` with the given `name`.

- - ### Field Detail

    - #### MAX_DESCRIPTORS_PER_TYPE

          static final int MAX_DESCRIPTORS_PER_TYPE

      The maximum number of descriptors a single statistics type can have.

      Current value is: `254`

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### createIntCounter

          StatisticDescriptor createIntCounter(java.lang.String name,
                                               java.lang.String description,
                                               java.lang.String units)

      Creates and returns an int counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.

    - #### createLongCounter

          StatisticDescriptor createLongCounter(java.lang.String name,
                                                java.lang.String description,
                                                java.lang.String units)

      Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.

    - #### createDoubleCounter

          StatisticDescriptor createDoubleCounter(java.lang.String name,
                                                  java.lang.String description,
                                                  java.lang.String units)

      Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.

    - #### createIntGauge

          StatisticDescriptor createIntGauge(java.lang.String name,
                                             java.lang.String description,
                                             java.lang.String units)

      Creates and returns an int gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.

    - #### createLongGauge

          StatisticDescriptor createLongGauge(java.lang.String name,
                                              java.lang.String description,
                                              java.lang.String units)

      Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.

    - #### createDoubleGauge

          StatisticDescriptor createDoubleGauge(java.lang.String name,
                                                java.lang.String description,
                                                java.lang.String units)

      Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.

    - #### createIntCounter

          StatisticDescriptor createIntCounter(java.lang.String name,
                                               java.lang.String description,
                                               java.lang.String units,
                                               boolean largerBetter)

      Creates and returns an int counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.

    - #### createLongCounter

          StatisticDescriptor createLongCounter(java.lang.String name,
                                                java.lang.String description,
                                                java.lang.String units,
                                                boolean largerBetter)

      Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.

    - #### createDoubleCounter

          StatisticDescriptor createDoubleCounter(java.lang.String name,
                                                  java.lang.String description,
                                                  java.lang.String units,
                                                  boolean largerBetter)

      Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.

    - #### createIntGauge

          StatisticDescriptor createIntGauge(java.lang.String name,
                                             java.lang.String description,
                                             java.lang.String units,
                                             boolean largerBetter)

      Creates and returns an int gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.

    - #### createLongGauge

          StatisticDescriptor createLongGauge(java.lang.String name,
                                              java.lang.String description,
                                              java.lang.String units,
                                              boolean largerBetter)

      Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.

    - #### createDoubleGauge

          StatisticDescriptor createDoubleGauge(java.lang.String name,
                                                java.lang.String description,
                                                java.lang.String units,
                                                boolean largerBetter)

      Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.

    - #### createType

          StatisticsType createType(java.lang.String name,
                                    java.lang.String description,
                                    StatisticDescriptor[] stats)

      Creates or finds and returns a `StatisticsType` with the given `name`, `description`, and `statistic descriptions`.
      Throws:
        `java.lang.IllegalArgumentException` - if a type with the given `name` already exists and it differs from the given parameters.

    - #### findType

          StatisticsType findType(java.lang.String name)

      Finds and returns an already created `StatisticsType` with the given `name`. Returns `null` if the type does not exist.

    - #### createTypesFromXml

          StatisticsType[] createTypesFromXml(java.io.Reader reader)
                                       throws java.io.IOException

      Creates one or more `StatisticsType` from the contents of the given `reader`. The created types can be found by calling `findType(java.lang.String)`.
      Parameters:
        `reader` - The source of the XML data which must comply with the `statisticsType.dtd`.
      Throws:
        `java.lang.IllegalArgumentException` - if a type defined in the reader already exists
        `java.io.IOException` - Something went wrong while reading from `reader`