org.osgi.service.monitor.StatusVariable Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2004, 2011). 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.
*/
package org.osgi.service.monitor;
import java.io.UnsupportedEncodingException;
import java.util.Date;
/**
* A {@code StatusVariable} object represents the value of a status
* variable taken with a certain collection method at a certain point of time.
* The type of the {@code StatusVariable} can be {@code int},
* {@code float}, {@code boolean} or {@code String}.
*
* A {@code StatusVariable} is identified by an ID string that is unique
* within the scope of a {@code Monitorable}. The ID must be a non-
* {@code null}, non-empty string that conforms to the "symbolic-name"
* definition in the OSGi core specification. This means that only the
* characters [-_.a-zA-Z0-9] may be used. The length of the ID must not exceed
* 32 bytes when UTF-8 encoded.
*
* @version $Id: 637f5f827f34da9c9743385701f517dc2f5e763d $
*/
public final class StatusVariable {
//----- Public constants -----//
/**
* Constant for identifying {@code int} data type.
*/
public static final int TYPE_INTEGER = 0;
/**
* Constant for identifying {@code float} data type.
*/
public static final int TYPE_FLOAT = 1;
/**
* Constant for identifying {@code String} data type.
*/
public static final int TYPE_STRING = 2;
/**
* Constant for identifying {@code boolean} data type.
*/
public static final int TYPE_BOOLEAN = 3;
/**
* Constant for identifying 'Cumulative Counter' data collection method.
*/
public static final int CM_CC = 0;
/**
* Constant for identifying 'Discrete Event Registration' data collection
* method.
*/
public static final int CM_DER = 1;
/**
* Constant for identifying 'Gauge' data collection method.
*/
public static final int CM_GAUGE = 2;
/**
* Constant for identifying 'Status Inspection' data collection method.
*/
public static final int CM_SI = 3;
//----- Package private constants -----//
static final String SYMBOLIC_NAME_CHARACTERS =
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" + "0123456789" +
"-_."; // a subset of the characters allowed in DMT URIs
static final int MAX_ID_LENGTH = 32;
//----- Private fields -----//
private String id;
private Date timeStamp;
private int cm;
private int type;
private int intData;
private float floatData;
private String stringData;
private boolean booleanData;
//----- Constructors -----//
/**
* Constructor for a {@code StatusVariable} of {@code int}
* type.
*
* @param id the identifier of the {@code StatusVariable}
* @param cm the collection method, one of the {@code CM_} constants
* @param data the {@code int} value of the
* {@code StatusVariable}
* @throws java.lang.IllegalArgumentException if the given {@code id}
* is not a valid {@code StatusVariable} name, or if
* {@code cm} is not one of the collection method constants
* @throws java.lang.NullPointerException if the {@code id}
* parameter is {@code null}
*/
public StatusVariable(String id, int cm, int data) {
setCommon(id, cm);
type = TYPE_INTEGER;
intData = data;
}
/**
* Constructor for a {@code StatusVariable} of {@code float}
* type.
*
* @param id the identifier of the {@code StatusVariable}
* @param cm the collection method, one of the {@code CM_} constants
* @param data the {@code float} value of the
* {@code StatusVariable}
* @throws java.lang.IllegalArgumentException if the given {@code id}
* is not a valid {@code StatusVariable} name, or if
* {@code cm} is not one of the collection method constants
* @throws java.lang.NullPointerException if the {@code id} parameter
* is {@code null}
*/
public StatusVariable(String id, int cm, float data) {
setCommon(id, cm);
type = TYPE_FLOAT;
floatData = data;
}
/**
* Constructor for a {@code StatusVariable} of {@code boolean}
* type.
*
* @param id the identifier of the {@code StatusVariable}
* @param cm the collection method, one of the {@code CM_} constants
* @param data the {@code boolean} value of the
* {@code StatusVariable}
* @throws java.lang.IllegalArgumentException if the given {@code id}
* is not a valid {@code StatusVariable} name, or if
* {@code cm} is not one of the collection method constants
* @throws java.lang.NullPointerException if the {@code id} parameter
* is {@code null}
*/
public StatusVariable(String id, int cm, boolean data) {
setCommon(id, cm);
type = TYPE_BOOLEAN;
booleanData = data;
}
/**
* Constructor for a {@code StatusVariable} of {@code String}
* type.
*
* @param id the identifier of the {@code StatusVariable}
* @param cm the collection method, one of the {@code CM_} constants
* @param data the {@code String} value of the
* {@code StatusVariable}, can be {@code null}
* @throws java.lang.IllegalArgumentException if the given {@code id}
* is not a valid {@code StatusVariable} name, or if
* {@code cm} is not one of the collection method constants
* @throws java.lang.NullPointerException if the {@code id} parameter
* is {@code null}
*/
public StatusVariable(String id, int cm, String data) {
setCommon(id, cm);
type = TYPE_STRING;
stringData = data;
}
// ----- Public methods -----//
/**
* Returns the ID of this {@code StatusVariable}. The ID is unique
* within the scope of a {@code Monitorable}.
*
* @return the ID of this {@code StatusVariable}
*/
public String getID() {
return id;
}
/**
* Returns information on the data type of this {@code StatusVariable}.
*
* @return one of the {@code TYPE_} constants indicating the type of
* this {@code StatusVariable}
*/
public int getType() {
return type;
}
/**
* Returns the timestamp associated with the {@code StatusVariable}. The
* timestamp is stored when the {@code StatusVariable} instance is created,
* generally during the {@link Monitorable#getStatusVariable(String)} method
* call.
*
* @return the time when the {@code StatusVariable} value was queried,
* cannot be {@code null}
*
*/
public Date getTimeStamp() {
return timeStamp;
}
/**
* Returns the {@code StatusVariable} value if its type is
* {@code String}.
*
* @return the {@code StatusVariable} value as a {@code String}
* @throws java.lang.IllegalStateException if the type of the
* {@code StatusVariable} is not {@code String}
*/
public String getString() throws IllegalStateException {
if (type != TYPE_STRING)
throw new IllegalStateException(
"This StatusVariable does not contain a String value.");
return stringData;
}
/**
* Returns the {@code StatusVariable} value if its type is
* {@code int}.
*
* @return the {@code StatusVariable} value as an {@code int}
* @throws java.lang.IllegalStateException if the type of this
* {@code StatusVariable} is not {@code int}
*/
public int getInteger() throws IllegalStateException {
if (type != TYPE_INTEGER)
throw new IllegalStateException(
"This StatusVariable does not contain an integer value.");
return intData;
}
/**
* Returns the {@code StatusVariable} value if its type is
* {@code float}.
*
* @return the {@code StatusVariable} value as a {@code float}
* @throws java.lang.IllegalStateException if the type of this
* {@code StatusVariable} is not {@code float}
*/
public float getFloat() throws IllegalStateException {
if (type != TYPE_FLOAT)
throw new IllegalStateException(
"This StatusVariable does not contain a float value.");
return floatData;
}
/**
* Returns the {@code StatusVariable} value if its type is
* {@code boolean}.
*
* @return the {@code StatusVariable} value as a {@code boolean}
* @throws java.lang.IllegalStateException if the type of this
* {@code StatusVariable} is not {@code boolean}
*/
public boolean getBoolean() throws IllegalStateException {
if (type != TYPE_BOOLEAN)
throw new IllegalStateException(
"This StatusVariable does not contain a boolean value.");
return booleanData;
}
/**
* Returns the collection method of this {@code StatusVariable}. See
* section 3.3 b) in [ETSI TS 132 403]
*
* @return one of the {@code CM_} constants
*/
public int getCollectionMethod() {
return cm;
}
/**
* Compares the specified object with this {@code StatusVariable}.
* Two {@code StatusVariable} objects are considered equal if their
* full path, collection method and type are identical, and the data
* (selected by their type) is equal.
*
* @param obj the object to compare with this {@code StatusVariable}
* @return {@code true} if the argument represents the same
* {@code StatusVariable} as this object
*/
public boolean equals(Object obj) {
if (!(obj instanceof StatusVariable))
return false;
StatusVariable other = (StatusVariable) obj;
if (!equals(id, other.id) || cm != other.cm || type != other.type)
return false;
switch (type) {
case TYPE_INTEGER: return intData == other.intData;
case TYPE_FLOAT: return floatData == other.floatData;
case TYPE_STRING: return equals(stringData, other.stringData);
case TYPE_BOOLEAN: return booleanData == other.booleanData;
}
return false; // never reached
}
/**
* Returns the hash code value for this {@code StatusVariable}. The
* hash code is calculated based on the full path, collection method and
* value of the {@code StatusVariable}.
*
* @return the hash code of this object
*/
public int hashCode() {
int hash = hashCode(id) ^ cm;
switch (type) {
case TYPE_INTEGER: return hash ^ intData;
case TYPE_FLOAT: return hash ^ hashCode(new Float(floatData));
case TYPE_BOOLEAN: return hash ^ hashCode(new Boolean(booleanData));
case TYPE_STRING: return hash ^ hashCode(stringData);
}
return 0; // never reached
}
// String representation: StatusVariable(path, cm, time, type, value)
/**
* Returns a {@code String} representation of this
* {@code StatusVariable}. The returned {@code String}
* contains the full path, collection method, timestamp, type and value
* parameters of the {@code StatusVariable} in the following format:
*
StatusVariable(<path>, <cm>, <timestamp>, <type>, <value>)
* The collection method identifiers used in the string representation are
* "CC", "DER", "GAUGE" and "SI" (without the quotes). The format of the
* timestamp is defined by the {@code Date.toString} method, while the
* type is identified by one of the strings "INTEGER", "FLOAT", "STRING" and
* "BOOLEAN". The final field contains the string representation of the
* value of the status variable.
*
* @return the {@code String} representation of this
* {@code StatusVariable}
*/
public String toString() {
String cmName = null;
switch (cm) {
case CM_CC: cmName = "CC"; break;
case CM_DER: cmName = "DER"; break;
case CM_GAUGE: cmName = "GAUGE"; break;
case CM_SI: cmName = "SI"; break;
}
String beg = "StatusVariable(" + id + ", " + cmName + ", "
+ timeStamp + ", ";
switch (type) {
case TYPE_INTEGER: return beg + "INTEGER, " + intData + ")";
case TYPE_FLOAT: return beg + "FLOAT, " + floatData + ")";
case TYPE_STRING: return beg + "STRING, " + stringData + ")";
case TYPE_BOOLEAN: return beg + "BOOLEAN, " + booleanData + ")";
}
return null; // never reached
}
//----- Private methods -----//
private void setCommon(String id, int cm)
throws IllegalArgumentException, NullPointerException {
checkId(id, "StatusVariable ID");
if (cm != CM_CC && cm != CM_DER && cm != CM_GAUGE && cm != CM_SI)
throw new IllegalArgumentException(
"Unknown data collection method constant '" + cm + "'.");
this.id = id;
this.cm = cm;
timeStamp = new Date();
}
private boolean equals(Object o1, Object o2) {
return o1 == null ? o2 == null : o1.equals(o2);
}
private int hashCode(Object o) {
return o == null ? 0 : o.hashCode();
}
private static void checkId(String id, String idName)
throws IllegalArgumentException, NullPointerException {
if (id == null)
throw new NullPointerException(idName + " is null.");
if(id.length() == 0)
throw new IllegalArgumentException(idName + " is empty.");
byte[] nameBytes;
try {
nameBytes = id.getBytes("UTF-8");
} catch (UnsupportedEncodingException e) {
// never happens, "UTF-8" must always be supported
throw new IllegalStateException(e.getMessage());
}
if(nameBytes.length > MAX_ID_LENGTH)
throw new IllegalArgumentException(idName + " is too long " +
"(over " + MAX_ID_LENGTH + " bytes in UTF-8 encoding).");
if(id.equals(".") || id.equals(".."))
throw new IllegalArgumentException(idName + " is invalid.");
if(!containsValidChars(id))
throw new IllegalArgumentException(idName +
" contains invalid characters.");
}
private static boolean containsValidChars(String name) {
char[] chars = name.toCharArray();
for(int i = 0; i < chars.length; i++)
if(SYMBOLIC_NAME_CHARACTERS.indexOf(chars[i]) == -1)
return false;
return true;
}
}