com.gemstone.gemfire.Statistics Maven / Gradle / Ivy
Show all versions of gemfire-core Show documentation
/*
* Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you
* may not use this file except in compliance with the License. You
* may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
* implied. See the License for the specific language governing
* permissions and limitations under the License. See accompanying
* LICENSE file.
*/
package com.gemstone.gemfire;
//import com.gemstone.gemfire.distributed.DistributedSystem;
/**
* Instances of this interface maintain the values of various application-defined
* statistics. The statistics themselves are described by an instance
* of {@link StatisticsType}.
*
*
* To get an instance of this interface use an instance of
* {@link StatisticsFactory}.
*
*
* For improved performance, each statistic may be referred to by
* its {@link #nameToDescriptor descriptor}.
*
* For optimal performance, each statistic may be referred to by
* its {@link #nameToId id} in the statistics object. Note that
* ids can not be mapped back to their name and methods that take ids
* are unsafe. It is important to call the correct type of method
* for the given id. For example if your stat is a long then incLong
* must be called instead of incInt.
*
Note that as of the 5.1 release the incInt,
* incLong, and incDouble methods no longer
* return the new value of the statistic. They now return void.
* This incompatible change was made
* to allow for a more efficient concurrent increment implementation.
*
*
* @see Package introduction
*
* @author David Whitlock
* @author Darrel Schneider
*
* @since 3.0
*
*/
public interface Statistics {
/**
* Closes these statistics. After statistics have been closed, they
* are no longer archived.
* A value access on a closed statistics always results in zero.
* A value modification on a closed statistics is ignored.
*/
public void close();
//////////////////////// accessor Methods ///////////////////////
/**
* Returns the id of the statistic with the given name in this
* statistics instance.
*
* @throws IllegalArgumentException
* No statistic named name exists in this
* statistics instance.
*
* @see StatisticsType#nameToId
*/
public int nameToId(String name);
/**
* Returns the descriptor of the statistic with the given name in this
* statistics instance.
*
* @throws IllegalArgumentException
* No statistic named name exists in this
* statistics instance.
*
* @see StatisticsType#nameToDescriptor
*/
public StatisticDescriptor nameToDescriptor(String name);
/**
* Gets a value that uniquely identifies this statistics.
*/
public long getUniqueId();
/**
* Gets the {@link StatisticsType} of this instance.
*/
public StatisticsType getType();
/**
* Gets the text associated with this instance that helps identify it.
*/
public String getTextId();
/**
* Gets the number associated with this instance that helps identify it.
*/
public long getNumericId();
/**
* Returns true if modifications are atomic. This means that multiple threads,
* can safely modify this instance without extra synchronization.
*
* Returns false if modifications are not atomic. This means that modifications
* to this instance are cheaper but not thread safe.
*/
public boolean isAtomic();
/**
* Returns true if the instance has been {@link #close closed}.
*/
public boolean isClosed();
//////////////////////// set() Methods ///////////////////////
/**
* Sets the value of a statistic with the given id
* whose type is int.
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
*
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public void setInt(int id, int value);
/**
* Sets the value of a named statistic of type int
*
* @throws IllegalArgumentException
* If no statistic exists named name or
* if the statistic with name name is not of
* type int.
*/
public void setInt(String name, int value);
/**
* Sets the value of a described statistic of type int
*
* @throws IllegalArgumentException
* If no statistic exists for the given descriptor or
* if the described statistic is not of
* type int.
*/
public void setInt(StatisticDescriptor descriptor, int value);
/**
* Sets the value of a statistic with the given id
* whose type is long.
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
*
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public void setLong(int id, long value);
/**
* Sets the value of a described statistic of type long
*
* @throws IllegalArgumentException
* If no statistic exists for the given descriptor or
* if the described statistic is not of
* type long.
*/
public void setLong(StatisticDescriptor descriptor, long value);
/**
* Sets the value of a named statistic of type long.
*
* @throws IllegalArgumentException
* If no statistic exists named name or
* if the statistic with name name is not of
* type long.
*/
public void setLong(String name, long value);
/**
* Sets the value of a statistic with the given id
* whose type is double.
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
*
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public void setDouble(int id, double value);
/**
* Sets the value of a described statistic of type double
*
* @throws IllegalArgumentException
* If no statistic exists for the given descriptor or
* if the described statistic is not of
* type double.
*/
public void setDouble(StatisticDescriptor descriptor, double value);
/**
* Sets the value of a named statistic of type double.
*
* @throws IllegalArgumentException
* If no statistic exists named name or
* if the statistic with name name is not of
* type double.
*/
public void setDouble(String name, double value);
/////////////////////// get() Methods ///////////////////////
/**
* Returns the value of the identified statistic of type int.
*
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public int getInt(int id);
/**
* Returns the value of the described statistic of type int.
*
* @throws IllegalArgumentException
* If no statistic exists with the specified descriptor or
* if the described statistic is not of
* type int.
*/
public int getInt(StatisticDescriptor descriptor);
/**
* Returns the value of the statistic of type int at
* the given name.
*
* @throws IllegalArgumentException
* If no statistic exists with name name or
* if the statistic named name is not of
* type int.
*/
public int getInt(String name);
/**
* Returns the value of the identified statistic of type long.
*
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public long getLong(int id);
/**
* Returns the value of the described statistic of type long.
*
* @throws IllegalArgumentException
* If no statistic exists with the specified descriptor or
* if the described statistic is not of
* type long.
*/
public long getLong(StatisticDescriptor descriptor);
/**
* Returns the value of the statistic of type long at
* the given name.
*
* @throws IllegalArgumentException
* If no statistic exists with name name or
* if the statistic named name is not of
* type long.
*/
public long getLong(String name);
/**
* Returns the value of the identified statistic of type double.
*
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public double getDouble(int id);
/**
* Returns the value of the described statistic of type double.
*
* @throws IllegalArgumentException
* If no statistic exists with the specified descriptor or
* if the described statistic is not of
* type double.
*/
public double getDouble(StatisticDescriptor descriptor);
/**
* Returns the value of the statistic of type double at
* the given name.
*
* @throws IllegalArgumentException
* If no statistic exists with name name or
* if the statistic named name is not of
* type double.
*/
public double getDouble(String name);
/**
* Returns the value of the identified statistic.
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor}
* or {@link StatisticsType#nameToDescriptor}.
* @throws IllegalArgumentException
* If the described statistic does not exist
*/
public Number get(StatisticDescriptor descriptor);
/**
* Returns the value of the named statistic.
*
* @throws IllegalArgumentException
* If the named statistic does not exist
*/
public Number get(String name);
/**
* Returns the bits that represent the raw value of the described statistic.
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor}
* or {@link StatisticsType#nameToDescriptor}.
* @throws IllegalArgumentException
* If the described statistic does not exist
*/
public long getRawBits(StatisticDescriptor descriptor);
/**
* Returns the bits that represent the raw value of the named statistic.
*
* @throws IllegalArgumentException
* If the named statistic does not exist
*/
public long getRawBits(String name);
//////////////////////// inc() Methods ////////////////////////
/**
* Increments the value of the identified statistic of type int
* by the given amount.
*
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
*
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public void incInt(int id, int delta);
/**
* Increments the value of the described statistic of type int
* by the given amount.
*
* @throws IllegalArgumentException
* If no statistic exists with the given descriptor or
* if the described statistic is not of
* type int.
*/
public void incInt(StatisticDescriptor descriptor, int delta);
/**
* Increments the value of the statistic of type int with
* the given name by a given amount.
*
* @throws IllegalArgumentException
* If no statistic exists with name name or
* if the statistic named name is not of
* type int.
*/
public void incInt(String name, int delta);
/**
* Increments the value of the identified statistic of type long
* by the given amount.
*
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
*
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public void incLong(int id, long delta);
/**
* Increments the value of the described statistic of type long
* by the given amount.
*
* @throws IllegalArgumentException
* If no statistic exists with the given descriptor or
* if the described statistic is not of
* type long.
*/
public void incLong(StatisticDescriptor descriptor, long delta);
/**
* Increments the value of the statistic of type long with
* the given name by a given amount.
*
* @throws IllegalArgumentException
* If no statistic exists with name name or
* if the statistic named name is not of
* type long.
*/
public void incLong(String name, long delta);
/**
* Increments the value of the identified statistic of type double
* by the given amount.
*
* @param id a statistic id obtained with {@link #nameToId}
* or {@link StatisticsType#nameToId}.
*
* @throws ArrayIndexOutOfBoundsException
* If the id is invalid.
*/
public void incDouble(int id, double delta);
/**
* Increments the value of the described statistic of type double
* by the given amount.
*
* @throws IllegalArgumentException
* If no statistic exists with the given descriptor or
* if the described statistic is not of
* type double.
*/
public void incDouble(StatisticDescriptor descriptor, double delta);
/**
* Increments the value of the statistic of type double with
* the given name by a given amount.
*
* @throws IllegalArgumentException
* If no statistic exists with name name or
* if the statistic named name is not of
* type double.
*/
public void incDouble(String name, double delta);
}