?? MonitorAdmin
MonitorAdmin
service is a singleton service that handles
StatusVariable
query requests and measurement job control requests.
Note that an alternative but not recommended way of obtaining
StatusVariable
s is that applications having the required
ServicePermissions
can query the list of Monitorable
services
from the service registry and then query the list of StatusVariable
names from the Monitorable
services. This way all services which
publish StatusVariable
s will be returned regardless of whether they
do or do not hold the necessary MonitorPermission
for publishing
StatusVariable
s. By using the MonitorAdmin
to obtain the
StatusVariable
s it is guaranteed that only those Monitorable
services will be accessed who are authorized to publish
StatusVariable
s. It is the responsibility of the MonitorAdmin
implementation to check the required permissions and show only those
variables which pass this check.
The events posted by MonitorAdmin
contain the following properties:
mon.monitorable.pid
: The identifier of theMonitorable
mon.statusvariable.name
: The identifier of theStatusVariable
within the givenMonitorable
mon.statusvariable.value
: The value of theStatusVariable
, represented as aString
mon.listener.id
: The identifier of the initiator of the monitoring job (only present if the event was generated due to a monitoring job)
Most of the methods require either a Monitorable ID or a Status Variable path
parameter, the latter in [Monitorable_ID]/[StatusVariable_ID] format. These
parameters must not be null
, and the IDs they contain must conform to
their respective definitions in Monitorable
and
StatusVariable
. If any of the restrictions are violated, the method
must throw an IllegalArgumentException
.
-
????
??????????getDescription
(String path) Returns a human readable description of the givenStatusVariable
.String[]
Returns the names of theMonitorable
services that are currently registered.Returns the list of currently runningMonitoringJob
s.getStatusVariable
(String path) Returns aStatusVariable
addressed by its full path.String[]
getStatusVariableNames
(String monitorableId) Returns the list ofStatusVariable
names published by aMonitorable
instance.getStatusVariables
(String monitorableId) Returns theStatusVariable
objects published by aMonitorable
instance.boolean
resetStatusVariable
(String path) Issues a request to reset a givenStatusVariable
.Starts a change basedMonitoringJob
with the parameters provided.startScheduledJob
(String initiator, String[] statusVariables, int schedule, int count) Starts a time basedMonitoringJob
with the parameters provided.void
switchEvents
(String path, boolean on) Switches event sending on or off for the specifiedStatusVariable
s.
-
??????
-
getStatusVariable
Returns aStatusVariable
addressed by its full path. The entity which queries aStatusVariable
needs to holdMonitorPermission
for the given target with theread
action present.- ??:
path
- the full path of theStatusVariable
in [Monitorable_ID]/[StatusVariable_ID] format- ??:
- the
StatusVariable
object - ??:
IllegalArgumentException
- ifpath
isnull
or otherwise invalid, or points to a non-existingStatusVariable
SecurityException
- if the caller does not hold aMonitorPermission
for theStatusVariable
specified bypath
with theread
action present
-
getMonitorableNames
String[] getMonitorableNames()Returns the names of theMonitorable
services that are currently registered. TheMonitorable
instances are not accessible through theMonitorAdmin
, so that requests to individual status variables can be filtered with respect to the publishing rights of theMonitorable
and the reading rights of the caller.The returned array contains the names in alphabetical order. It cannot be
null
, an empty array is returned if noMonitorable
services are registered.- ??:
- the array of
Monitorable
names
-
getStatusVariables
Returns theStatusVariable
objects published by aMonitorable
instance. TheStatusVariables
will hold the values taken at the time of this method call. Only those status variables are returned where the following two conditions are met:- the specified
Monitorable
holds aMonitorPermission
for the status variable with thepublish
action present - the caller holds a
MonitorPermission
for the status variable with theread
action present
The elements in the returned array are in no particular order. The return value cannot be
null
, an empty array is returned if no (authorized and readable) Status Variables are provided by the givenMonitorable
.- ??:
monitorableId
- the identifier of aMonitorable
instance- ??:
- a list of
StatusVariable
objects published by the specifiedMonitorable
- ??:
IllegalArgumentException
- ifmonitorableId
isnull
or otherwise invalid, or points to a non-existingMonitorable
- the specified
-
getStatusVariableNames
Returns the list ofStatusVariable
names published by aMonitorable
instance. Only those status variables are listed where the following two conditions are met:- the specified
Monitorable
holds aMonitorPermission
for the status variable with thepublish
action present - the caller holds a
MonitorPermission
for the status variable with theread
action present
The returned array does not contain duplicates, and the elements are in alphabetical order. It cannot be
null
, an empty array is returned if no (authorized and readable) Status Variables are provided by the givenMonitorable
.- ??:
monitorableId
- the identifier of aMonitorable
instance- ??:
- a list of
StatusVariable
objects names published by the specifiedMonitorable
- ??:
IllegalArgumentException
- ifmonitorableId
isnull
or otherwise invalid, or points to a non-existingMonitorable
- the specified
-
switchEvents
Switches event sending on or off for the specifiedStatusVariable
s. When theMonitorAdmin
is notified about aStatusVariable
being updated it sends an event unless this feature is switched off. Note that events within a monitoring job can not be switched off. The event sending state of theStatusVariables
must not be persistently stored. When aStatusVariable
is registered for the first time in a framework session, its event sending state is set to ON by default.Usage of the "*" wildcard is allowed in the path argument of this method as a convenience feature. The wildcard can be used in either or both path fragments, but only at the end of the fragments. The semantics of the wildcard is that it stands for any matching
StatusVariable
at the time of the method call, it does not affect the event sending status ofStatusVariable
s which are not yet registered. As an example, when theswitchEvents("MyMonitorable/*", false)
method is executed, event sending from allStatusVariables
of the MyMonitorable service are switched off. However, if the MyMonitorable service starts to publish a newStatusVariable
later, it's event sending status is on by default.- ??:
path
- the identifier of theStatusVariable
(s) in [Monitorable_id]/[StatusVariable_id] format, possibly with the "*" wildcard at the end of either path fragmenton
-false
if event sending should be switched off,true
if it should be switched on for the given path- ??:
SecurityException
- if the caller does not holdMonitorPermission
with theswitchevents
action or if there is anyStatusVariable
in thepath
field for which it is not allowed to switch event sending on or off as per the target field of the permissionIllegalArgumentException
- ifpath
isnull
or otherwise invalid, or points to a non-existingStatusVariable
-
resetStatusVariable
Issues a request to reset a givenStatusVariable
. Depending on the semantics of theStatusVariable
this call may or may not succeed: it makes sense to reset a counter to its starting value, but e.g. aStatusVariable
of type String might not have a meaningful default value. Note that for numericStatusVariable
s the starting value may not necessarily be 0. Resetting aStatusVariable
triggers a monitor event if theStatusVariable
supports update notifications.The entity that wants to reset the
StatusVariable
needs to holdMonitorPermission
with thereset
action present. The target field of the permission must match theStatusVariable
name to be reset.- ??:
path
- the identifier of theStatusVariable
in [Monitorable_id]/[StatusVariable_id] format- ??:
true
if theMonitorable
could successfully reset the givenStatusVariable
,false
otherwise- ??:
IllegalArgumentException
- ifpath
isnull
or otherwise invalid, or points to a non-existingStatusVariable
SecurityException
- if the caller does not holdMonitorPermission
with thereset
action or if the specifiedStatusVariable
is not allowed to be reset as per the target field of the permission
-
getDescription
Returns a human readable description of the givenStatusVariable
. Thenull
value may be returned if there is no description for the givenStatusVariable
.The entity that queries a
StatusVariable
needs to holdMonitorPermission
for the given target with theread
action present.- ??:
path
- the full path of theStatusVariable
in [Monitorable_ID]/[StatusVariable_ID] format- ??:
- the human readable description of this
StatusVariable
ornull
if it is not set - ??:
IllegalArgumentException
- ifpath
isnull
or otherwise invalid, or points to a non-existingStatusVariable
SecurityException
- if the caller does not hold aMonitorPermission
for theStatusVariable
specified bypath
with theread
action present
-
startScheduledJob
MonitoringJob startScheduledJob(String initiator, String[] statusVariables, int schedule, int count) throws IllegalArgumentException, SecurityException Starts a time basedMonitoringJob
with the parameters provided. Monitoring events will be sent according to the specified schedule. All specifiedStatusVariable
s must exist when the job is started. The initiator string is used in themon.listener.id
field of all events triggered by the job, to allow filtering the events based on the initiator.The
schedule
parameter specifies the time in seconds between two measurements, it must be greater than 0. The first measurement will be taken when the timer expires for the first time, not when this method is called.The
count
parameter defines the number of measurements to be taken, and must either be a positive integer, or 0 if the measurement is to run until explicitly stopped.The entity which initiates a
MonitoringJob
needs to holdMonitorPermission
for all the specified targetStatusVariable
s with thestartjob
action present. If the permission's action string specifies a minimal sampling interval then theschedule
parameter should be at least as great as the value in the action string.- ??:
initiator
- the identifier of the entity that initiated the jobstatusVariables
- the list ofStatusVariable
s to be monitored, with eachStatusVariable
name given in [Monitorable_PID]/[StatusVariable_ID] formatschedule
- the time in seconds between two measurementscount
- the number of measurements to be taken, or 0 for the measurement to run until explicitly stopped- ??:
- the successfully started job object, cannot be
null
- ??:
IllegalArgumentException
- if the list ofStatusVariable
names contains an invalid or non-existingStatusVariable
; ifinitiator
isnull
or empty; or if theschedule
orcount
parameters are invalidSecurityException
- if the caller does not holdMonitorPermission
for all the specifiedStatusVariable
s, with thestartjob
action present, or if the permission does not allow starting the job with the given frequency
-
startJob
MonitoringJob startJob(String initiator, String[] statusVariables, int count) throws IllegalArgumentException, SecurityException Starts a change basedMonitoringJob
with the parameters provided. Monitoring events will be sent when theStatusVariable
s of this job are updated. All specifiedStatusVariable
s must exist when the job is started, and all must support update notifications. The initiator string is used in themon.listener.id
field of all events triggered by the job, to allow filtering the events based on the initiator.The
count
parameter specifies the number of changes that must happen to aStatusVariable
before a new notification is sent, this must be a positive integer.The entity which initiates a
MonitoringJob
needs to holdMonitorPermission
for all the specified targetStatusVariable
s with thestartjob
action present.- ??:
initiator
- the identifier of the entity that initiated the jobstatusVariables
- the list ofStatusVariable
s to be monitored, with eachStatusVariable
name given in [Monitorable_PID]/[StatusVariable_ID] formatcount
- the number of changes that must happen to aStatusVariable
before a new notification is sent- ??:
- the successfully started job object, cannot be
null
- ??:
IllegalArgumentException
- if the list ofStatusVariable
names contains an invalid or non-existingStatusVariable
, or one that does not support notifications; if theinitiator
isnull
or empty; or ifcount
is invalidSecurityException
- if the caller does not holdMonitorPermission
for all the specifiedStatusVariable
s, with thestartjob
action present
-
getRunningJobs
MonitoringJob[] getRunningJobs()Returns the list of currently runningMonitoringJob
s. Jobs are only visible to callers that have the necessary permissions: to receive a Monitoring Job in the returned list, the caller must hold all permissions required for starting the job. This means that if the caller does not haveMonitorPermission
with the properstartjob
action for all the Status Variables monitored by a job, then that job will be silently omitted from the results.The returned array cannot be
null
, an empty array is returned if there are no running jobs visible to the caller at the time of the call.- ??:
- the list of running jobs visible to the caller
-