oracle.dms.instrument
Class State

java.lang.Object
oracle.dms.instrument.Sensor
oracle.dms.instrument.State

public class State

extends Sensor

A State Sensor can be used to monitor pre-computed metric values. A State can be used to monitor arbitrary values, including integers, doubles, longs, or Object references. Use a State Sensor to represent status or gauge values that may increase or decrease during JVM execution. For example, queue lengths, pool sizes, buffer sizes, configuration parameters, etc. Depending on the derived metrics specified, a State sensor may contain value and count metrics. Numeric States may also contain Sensor.maximum and Sensor.minimum derived metrics. The following code segment provides an example of how one would typically create and use a State sensor to monitor the length of a queue.

Assume the existence of parent Noun named "/queue":

State queueState = State.create(parent, "length", State.INTEGER,
<spacer type="horizontal" size="190"> "items", "length of queue");
queueState.deriveMetric(Sensor.maximum);
queueState.update(0); // set initial value to 0

Alternatively, this State Sensor could be created using the path name of the Sensor:

State.create("/queue/length", State.INTEGER,
<spacer type="horizontal" size="190"> "items", "length of queue");

The call to

queueState.deriveMetric(Sensor.maximum);

will cause the maximum items on the queue at any time to be tracked and reported if the State is properly updated when items are added to and removed from the queue. Later, in a method that adds an item to a queue, one should call

queueState.increment(1);

to account for it. When an item is later removed from the queue, it can be propertly tracked using:

queueState.increment(-1);

For a state containing a value that should be set directly, one of the update() calls would be used rather than increment().

Field Summary

static byte	DOUBLE Data type for State is the Java primitive double
static byte	INTEGER Data type for State is the Java primitive int
static byte	LONG Data type for State is the Java primitive long
static byte	OBJECT Data type for State is java.lang.Object

Fields inherited from class oracle.dms.instrument.Sensor

active, all, average, completed, count, exclTime, maxActive, maximum, minimum, sum, time, value

Method Summary

static State	create(Noun parent, java.lang.String name, byte valueType, java.lang.String units, java.lang.String desc) Creates an uninitialized State Sensor.
static State	create(Noun parent, java.lang.String name, java.lang.String units, java.lang.String desc, double init) Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)
static State	create(Noun parent, java.lang.String name, java.lang.String units, java.lang.String desc, int init) Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)
static State	create(Noun parent, java.lang.String name, java.lang.String units, java.lang.String desc, long init) Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)
static State	create(Noun parent, java.lang.String name, java.lang.String units, java.lang.String desc, java.lang.Object init) Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)
void	deriveMetric(int metric) Derives additional metrics for the State.
byte	getValueType() Get the type of data maintained in this object.
void	increment(double inc) Adds to the value of the State.
void	increment(int inc) Adds to the value of the State.
void	increment(long inc) Adds to the value of the State.
void	setCopy(boolean copy) Set the State to store a String copy of the maintained object.
void	update(double newval) Updates the value of the State.
void	update(int newval) Updates the value of the State.
void	update(long newval) Updates the value of the State.
void	update(java.lang.Object newval) Updates the value of the State.

Methods inherited from class oracle.dms.instrument.Sensor

destroy, get, getDescription, getName, getValue, reset

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DOUBLE

public static final byte DOUBLE

Data type for State is the Java primitive double

See Also:

Constant Field Values

LONG

public static final byte LONG

Data type for State is the Java primitive long

See Also:

Constant Field Values

INTEGER

public static final byte INTEGER

Data type for State is the Java primitive int

See Also:

Constant Field Values

OBJECT

public static final byte OBJECT

Data type for State is java.lang.Object

See Also:

Constant Field Values

Method Detail

create

public static State create(Noun parent,
                           java.lang.String name,
                           byte valueType,
                           java.lang.String units,
                           java.lang.String desc)

Creates an uninitialized State Sensor. The State can be initialized with a call to State.update(). The type of data to be maintained in the State is specified in the valueType parameter, and cannot be changed.

If State.OBJECT is specified, a reference to any Java object can be maintained in the State. If a call is made to setCopy(boolean), a String copy (using the object's toString() method) will be maintained, rather than a reference to the object.

Parameters:

parent - the noun the State should be created under

name - the name of the State

valueType - the type of data to be maintained in this State, which must be one of DOUBLE, LONG, INTEGER, or OBJECT.

units - the label for the units of the value.

desc - a description for the State.

Returns:

the new State or, if the State already exists, then this method returns a reference to it.

Throws:

InstrumentationException - if the parameters are invalid.

Since:

Oracle AS 10.1.2

create

public static State create(Noun parent,
                           java.lang.String name,
                           java.lang.String units,
                           java.lang.String desc,
                           int init)

Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)

Creates a new State Sensor. The value of the State will become an Integer.

Parameters:

parent - the State's parent Noun.

name - the name of the State.

units - the label for the units of the value.

desc - a description for the State.

init - initial State value

Returns:

the new State or, if the State already exists, then this method returns a reference to it.

create

public static State create(Noun parent,
                           java.lang.String name,
                           java.lang.String units,
                           java.lang.String desc,
                           long init)

Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)

Creates a new State Sensor. The value of the State will become a Long.

Parameters:

parent - the State's parent Noun.

name - the name of the State.

units - the label for the units of the value.

desc - a description for the State.

init - initial State value

Returns:

the new State or, if the State already exists, then this method returns a reference to it.

create

public static State create(Noun parent,
                           java.lang.String name,
                           java.lang.String units,
                           java.lang.String desc,
                           double init)

Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)

Creates a new State Sensor. The value of the State will become a Double.

Parameters:

parent - the State's parent Noun.

name - the name of the State.

units - the label for the units of the value.

desc - a description for the State.

init - initial State value

Returns:

the new State or, if the State already exists, then this method returns a reference to it.

create

public static State create(Noun parent,
                           java.lang.String name,
                           java.lang.String units,
                           java.lang.String desc,
                           java.lang.Object init)

Deprecated. As of Oracle AS 10.1.2, replaced by create(Noun, String, byte, String, String)

Creates a new State Sensor

Parameters:

parent - the State's parent Noun.

name - the name of the State.

units - the label for the units of the value.

desc - a description for the State.

init - initial State value

DMS stores a reference to the Object, not a copy of the Object. The metric value may change, if the Object is modified. When reporting the State's metric value, DMS will call toString() on the Object.

Returns:

the new State or, if the State already exists, then this method returns a reference to it.

deriveMetric

public void deriveMetric(int metric)

Derives additional metrics for the State. Once a metric has been derived, it cannot be turned off.

Overrides:

deriveMetric in class Sensor

Parameters:

metric - a bitmask indicating the metric(s) to derive.

Possible values are Sensor.minimum, Sensor.maximum, and Sensor.count. The values can be bitwise-ORed together, or multiple calls to deriveMetric can be made at the programmer's convenience. Sensor.minimum and Sensor.maximum are not applicable to non-numeric States.

Since:

Oracle iAS 1.0.2.2

update

public void update(int newval)

Updates the value of the State. The value of the State will become an Integer.

Parameters:

newval - the new value for the State.

Since:

Oracle iAS 1.0.2.2

update

public void update(long newval)

Updates the value of the State. The value of the State will become a Long.

Parameters:

newval - the new value for the State.

Since:

Oracle iAS 9.0.2

update

public void update(double newval)

Updates the value of the State. The value of the State will become a Double.

Parameters:

newval - the new value for the State.

Since:

Oracle iAS 1.0.2.2

update

public void update(java.lang.Object newval)

Updates the value of the State.

Parameters:

newval - the new value for the State.

DMS stores a reference to the input Object, not a copy. The metric value may change, if the Object is modified. When reporting the State's metric value, DMS will call toString() on the Object.

Since:

Oracle iAS 1.0.2.2

increment

public void increment(int inc)

Adds to the value of the State. The value of the State will become an Integer. To decrement, just pass in a negative value.

Parameters:

inc - the new value to add to the current value of the State.

Throws:

java.lang.ClassCastException - if the previous State value was not a Number.

Since:

Oracle iAS 9.0.2

increment

public void increment(long inc)

Adds to the value of the State. The value of the State will become a Long. To decrement, just pass in a negative value.

Parameters:

inc - the new value to add to the current value of the State.

Throws:

java.lang.ClassCastException - if the previous State value was not a Number.

Since:

Oracle iAS 9.0.2

increment

public void increment(double inc)

Adds to the value of the State. The value of the State will become a Double. To decrement, just pass in a negative value.

Parameters:

inc - the new value to add to the current value of the State.

Throws:

java.lang.ClassCastException - if the previous State value was not a Number.

Since:

Oracle iAS 9.0.2

getValueType

public byte getValueType()

Get the type of data maintained in this object. If not explicitely specified, the type is State.ANY.

Returns:

the type of data in the State Sensor.

Since:

Oracle AS 10.1.2

setCopy

public void setCopy(boolean copy)

Set the State to store a String copy of the maintained object. A State of type OBJECT normally maintains a reference to the object it has last been updated with. When the value is retrieved for reporting, it is converted to a String using toString() on the object reference. An input value of true will cause the State to maintain object.toString() rather than a reference object. Further changes to the object will not impact the contents of the state after setCopy() is called with true. This method has no impact unless the State type is OBJECT.

Parameters:

copy - whether to store a String copy or the object reference.

Since:

Oracle AS 10.1.2