org.osgi.service.monitor.Monitorable Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2004, 2010). 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;
/**
* A {@code Monitorable} can provide information about itself in the form
* of {@code StatusVariables}. Instances of this interface should register
* themselves at the OSGi Service Registry. The {@code MonitorAdmin}
* listens to the registration of {@code Monitorable} services, and makes
* the information they provide available also through the Device Management
* Tree (DMT) for remote access.
*
* The monitorable service is identified by its PID string which 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 PID must not exceed
* 20 characters.
*
* A {@code Monitorable} may optionally support sending notifications when
* the status of its {@code StatusVariables} change. Support for change
* notifications can be defined per {@code StatusVariable}.
*
* Publishing {@code StatusVariables} requires the presence of the
* {@code MonitorPermission} with the {@code publish} action string.
* This permission, however, is not checked during registration of the
* {@code Monitorable} service. Instead, the {@code MonitorAdmin}
* implementation must make sure that when a {@code StatusVariable} is
* queried, it is shown only if the {@code Monitorable} is authorized to
* publish the given {@code StatusVariable}.
*
* @version $Id: 575bb0add2cfea32c4008106b3ee2943c7c73e25 $
*/
public interface Monitorable {
/**
* Returns the list of {@code StatusVariable} identifiers published by this
* {@code Monitorable}. A {@code StatusVariable} name is unique within the
* scope of a {@code Monitorable}. The array contains the elements in no
* particular order. The returned value must not be {@code null}.
*
* @return the {@code StatusVariable} identifiers published by this object,
* or an empty array if none are published
*/
public String[] getStatusVariableNames();
/**
* Returns the {@code StatusVariable} object addressed by its
* identifier. The {@code StatusVariable} will hold the value taken
* at the time of this method call.
*
* The given identifier does not contain the Monitorable PID, i.e. it
* specifies the name and not the path of the Status Variable.
*
* @param id the identifier of the {@code StatusVariable}, cannot be
* {@code null}
* @return the {@code StatusVariable} object
* @throws java.lang.IllegalArgumentException if {@code id} points to a
* non-existing {@code StatusVariable}
*/
public StatusVariable getStatusVariable(String id)
throws IllegalArgumentException;
/**
* Tells whether the {@code StatusVariable} provider is able to send
* instant notifications when the given {@code StatusVariable}
* changes. If the {@code Monitorable} supports sending change
* updates it must notify the {@code MonitorListener} when the value
* of the {@code StatusVariable} changes. The
* {@code Monitorable} finds the {@code MonitorListener}
* service through the Service Registry.
*
* The given identifier does not contain the Monitorable PID, i.e. it
* specifies the name and not the path of the Status Variable.
*
* @param id the identifier of the {@code StatusVariable}, cannot be
* {@code null}
* @return {@code true} if the {@code Monitorable} can send
* notification when the given {@code StatusVariable}
* changes, {@code false} otherwise
* @throws java.lang.IllegalArgumentException if {@code id} points to a
* non-existing {@code StatusVariable}
*/
public boolean notifiesOnChange(String id) throws IllegalArgumentException;
/**
* Issues a request to reset a given {@code StatusVariable}.
* Depending on the semantics of the actual Status Variable this call may or
* may not succeed: it makes sense to reset a counter to its starting value,
* but for example a {@code StatusVariable} of type {@code String}
* might not have a meaningful default value. Note that for numeric
* {@code StatusVariables} the starting value may not necessarily be
* 0. Resetting a {@code StatusVariable} must trigger a monitor event.
*
* The given identifier does not contain the Monitorable PID, i.e. it
* specifies the name and not the path of the Status Variable.
*
* @param id the identifier of the {@code StatusVariable}, cannot be
* {@code null}
* @return {@code true} if the {@code Monitorable} could
* successfully reset the given {@code StatusVariable},
* {@code false} otherwise
* @throws java.lang.IllegalArgumentException if {@code id} points to a
* non-existing {@code StatusVariable}
*/
public boolean resetStatusVariable(String id)
throws IllegalArgumentException;
/**
* Returns a human readable description of a {@code StatusVariable}.
* This can be used by management systems on their GUI. The
* {@code null} return value is allowed if there is no description for
* the specified Status Variable.
*
* The given identifier does not contain the Monitorable PID, i.e. it
* specifies the name and not the path of the Status Variable.
*
* @param id the identifier of the {@code StatusVariable}, cannot be
* {@code null}
* @return the human readable description of this
* {@code StatusVariable} or {@code null} if it is not
* set
* @throws java.lang.IllegalArgumentException if {@code id} points to a
* non-existing {@code StatusVariable}
*/
public String getDescription(String id) throws IllegalArgumentException;
}