StatisticsTypeFactory (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode, interface: StatisticsTypeFactory

Package 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.

The following code is an example of how to create a type using code. In this example the type has two counters:

        StatisticsTypeFactory f = ...;
        StatisticsType t = f.createType(
            "StatSampler",
            "Stats on the statistic sampler.",
            new StatisticDescriptor[] {
                f.createLongCounter("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="long" 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
  Description
  `static final int`
  `MAX_DESCRIPTORS_PER_TYPE`
  The maximum number of descriptors a single statistics type can have.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `StatisticDescriptor`
  `createDoubleCounter(String name, String description, String units)`
  Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
  `StatisticDescriptor`
  `createDoubleCounter(String name, String description, String units, boolean largerBetter)`
  Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
  `StatisticDescriptor`
  `createDoubleGauge(String name, String description, String units)`
  Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
  `StatisticDescriptor`
  `createDoubleGauge(String name, String description, String units, boolean largerBetter)`
  Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
  `StatisticDescriptor`
  `createIntCounter(String name, String description, String units)`
  Deprecated.
  as of Geode 1.10, use `createLongCounter(String, String, String)` instead
  `StatisticDescriptor`
  `createIntCounter(String name, String description, String units, boolean largerBetter)`
  Deprecated.
  as of Geode 1.10, use `createLongCounter(String, String, String, boolean)` instead
  `StatisticDescriptor`
  `createIntGauge(String name, String description, String units)`
  Deprecated.
  as of Geode 1.10, use `createLongGauge(String, String, String)` instead
  `StatisticDescriptor`
  `createIntGauge(String name, String description, String units, boolean largerBetter)`
  Deprecated.
  as of Geode 1.10, use `createLongGauge(String, String, String, boolean)` instead
  `StatisticDescriptor`
  `createLongCounter(String name, String description, String units)`
  Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
  `StatisticDescriptor`
  `createLongCounter(String name, String description, String units, boolean largerBetter)`
  Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
  `StatisticDescriptor`
  `createLongGauge(String name, String description, String units)`
  Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
  `StatisticDescriptor`
  `createLongGauge(String name, String description, String units, boolean largerBetter)`
  Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
  `StatisticsType`
  `createType(String name, String description, StatisticDescriptor[] stats)`
  Creates or finds and returns a `StatisticsType` with the given `name`, `description`, and `statistic descriptions`.
  `StatisticsType[]`
  `createTypesFromXml(Reader reader)`
  Creates one or more `StatisticsType` from the contents of the given `reader`.
  `StatisticsType`
  `findType(String name)`
  Finds and returns an already created `StatisticsType` with the given `name`.

- ## Field Details

  - ### 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 Details

  - ### createIntCounter

    @Deprecated StatisticDescriptor createIntCounter(String name, String description, String units)
    Deprecated.
    as of Geode 1.10, use `createLongCounter(String, String, String)` instead
    Creates and returns an int counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
    Parameters:
      `name` - the name of the int counter `StatisticDescriptor`
      `description` - the description of the int counter `StatisticDescriptor`
      `units` - the units of the int counter `StatisticDescriptor`
    Returns:
      a newly created int counter `StatisticDescriptor`

  - ### createLongCounter

    StatisticDescriptor createLongCounter(String name, String description, String units)
    Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
    Parameters:
      `name` - the name of the long counter `StatisticDescriptor`
      `description` - the description of the long counter `StatisticDescriptor`
      `units` - the units of the long counter `StatisticDescriptor`
    Returns:
      a newly created long counter `StatisticDescriptor`

  - ### createDoubleCounter

    StatisticDescriptor createDoubleCounter(String name, String description, String units)
    Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `units`, and with larger values indicating better performance.
    Parameters:
      `name` - the name of the double counter `StatisticDescriptor`
      `description` - the description of the double counter `StatisticDescriptor`
      `units` - the units of the double counter `StatisticDescriptor`
    Returns:
      a newly created double counter `StatisticDescriptor`

  - ### createIntGauge

    @Deprecated StatisticDescriptor createIntGauge(String name, String description, String units)
    Deprecated.
    as of Geode 1.10, use `createLongGauge(String, String, String)` instead
    Creates and returns an int gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
    Parameters:
      `name` - the name of the int gauge `StatisticDescriptor`
      `description` - the description of the int gauge `StatisticDescriptor`
      `units` - the units of the int gauge `StatisticDescriptor`
    Returns:
      a newly created int gauge `StatisticDescriptor`

  - ### createLongGauge

    StatisticDescriptor createLongGauge(String name, String description, String units)
    Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
    Parameters:
      `name` - the name of the long gauge `StatisticDescriptor`
      `description` - the description of the long gauge `StatisticDescriptor`
      `units` - the units of the long gauge `StatisticDescriptor`
    Returns:
      a newly created long gauge `StatisticDescriptor`

  - ### createDoubleGauge

    StatisticDescriptor createDoubleGauge(String name, String description, String units)
    Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `units`, and with smaller values indicating better performance.
    Parameters:
      `name` - the name of the double gauge `StatisticDescriptor`
      `description` - the description of the double gauge `StatisticDescriptor`
      `units` - the units of the double gauge `StatisticDescriptor`
    Returns:
      a newly created double gauge `StatisticDescriptor`

  - ### createIntCounter

    @Deprecated StatisticDescriptor createIntCounter(String name, String description, String units, boolean largerBetter)
    Deprecated.
    as of Geode 1.10, use `createLongCounter(String, String, String, boolean)` instead
    Creates and returns an int counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    Parameters:
      `name` - the name of the int counter `StatisticDescriptor`
      `description` - the description of the int counter `StatisticDescriptor`
      `units` - the units of the int counter `StatisticDescriptor`
      `largerBetter` - whether larger values indicate better performance
    Returns:
      a newly created int counter `StatisticDescriptor`

  - ### createLongCounter

    StatisticDescriptor createLongCounter(String name, String description, String units, boolean largerBetter)
    Creates and returns a long counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    Parameters:
      `name` - the name of the long counter `StatisticDescriptor`
      `description` - the description of the long counter `StatisticDescriptor`
      `units` - the units of the long counter `StatisticDescriptor`
      `largerBetter` - whether larger values indicate better performance
    Returns:
      a newly created long counter `StatisticDescriptor`

  - ### createDoubleCounter

    StatisticDescriptor createDoubleCounter(String name, String description, String units, boolean largerBetter)
    Creates and returns a double counter `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    Parameters:
      `name` - the name of the double counter `StatisticDescriptor`
      `description` - the description of the double counter `StatisticDescriptor`
      `units` - the units of the double counter `StatisticDescriptor`
      `largerBetter` - whether larger values indicate better performance
    Returns:
      a newly created double counter `StatisticDescriptor`

  - ### createIntGauge

    @Deprecated StatisticDescriptor createIntGauge(String name, String description, String units, boolean largerBetter)
    Deprecated.
    as of Geode 1.10, use `createLongGauge(String, String, String, boolean)` instead
    Creates and returns an int gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    Parameters:
      `name` - the name of the int gauge `StatisticDescriptor`
      `description` - the description of the int gauge `StatisticDescriptor`
      `units` - the units of the int gauge `StatisticDescriptor`
      `largerBetter` - whether larger values indicate better performance
    Returns:
      a newly created int gauge `StatisticDescriptor`

  - ### createLongGauge

    StatisticDescriptor createLongGauge(String name, String description, String units, boolean largerBetter)
    Creates and returns a long gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    Parameters:
      `name` - the name of the long gauge `StatisticDescriptor`
      `description` - the description of the long gauge `StatisticDescriptor`
      `units` - the units of the long gauge `StatisticDescriptor`
      `largerBetter` - whether larger values indicate better performance
    Returns:
      a newly created long gauge `StatisticDescriptor`

  - ### createDoubleGauge

    StatisticDescriptor createDoubleGauge(String name, String description, String units, boolean largerBetter)
    Creates and returns a double gauge `StatisticDescriptor` with the given `name`, `description`, `largerBetter`, and `units`.
    Parameters:
      `name` - the name of the double gauge `StatisticDescriptor`
      `description` - the description of the double gauge `StatisticDescriptor`
      `units` - the units of the double gauge `StatisticDescriptor`
      `largerBetter` - whether larger values indicate better performance
    Returns:
      a newly created double gauge `StatisticDescriptor`

  - ### createType

    StatisticsType createType(String name, String description, StatisticDescriptor[] stats)
    Creates or finds and returns a `StatisticsType` with the given `name`, `description`, and `statistic descriptions`.
    Parameters:
      `name` - the name of the `StatisticsType` to create or find
      `description` - the description of the `StatisticsType` to create or find
      `stats` - the statistic descriptions of the `StatisticsType` to create or find
    Returns:
      a `StatisticsType` with the given `name`, `description`, and `statistic descriptions`
    Throws:
      `IllegalArgumentException` - if a type with the given `name` already exists and it differs from the given parameters.

  - ### findType

    StatisticsType findType(String name)
    Finds and returns an already created `StatisticsType` with the given `name`. Returns `null` if the type does not exist.
    Parameters:
      `name` - the name of the `StatisticsType` to find
    Returns:
      an already created `StatisticsType` with the given `name`

  - ### createTypesFromXml

    StatisticsType[] createTypesFromXml(Reader reader) throws 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`.
    Returns:
      an array of newly created `StatisticsType`s
    Throws:
      `IllegalArgumentException` - if a type defined in the reader already exists
      `IOException` - Something went wrong while reading from `reader`