Christian van Spaandonk | 6381441 | 2008-08-02 09:56:01 +0000 | [diff] [blame] | 1 | /* |
Richard S. Hall | 8df9ab1 | 2009-07-24 17:06:37 +0000 | [diff] [blame] | 2 | * Copyright (c) OSGi Alliance (2004, 2008). All Rights Reserved. |
Christian van Spaandonk | 6381441 | 2008-08-02 09:56:01 +0000 | [diff] [blame] | 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package org.osgi.service.monitor; |
| 18 | |
| 19 | /** |
| 20 | * A <code>Monitorable</code> can provide information about itself in the form |
Richard S. Hall | 8df9ab1 | 2009-07-24 17:06:37 +0000 | [diff] [blame] | 21 | * of <code>StatusVariables</code>. Instances of this interface should register |
| 22 | * themselves at the OSGi Service Registry. The <code>MonitorAdmin</code> |
| 23 | * listens to the registration of <code>Monitorable</code> services, and makes |
| 24 | * the information they provide available also through the Device Management |
| 25 | * Tree (DMT) for remote access. |
Christian van Spaandonk | 6381441 | 2008-08-02 09:56:01 +0000 | [diff] [blame] | 26 | * <p> |
| 27 | * The monitorable service is identified by its PID string which must be a non- |
| 28 | * <code>null</code>, non-empty string that conforms to the "symbolic-name" |
| 29 | * definition in the OSGi core specification. This means that only the |
| 30 | * characters [-_.a-zA-Z0-9] may be used. The length of the PID must not exceed |
| 31 | * 20 characters. |
| 32 | * <p> |
Richard S. Hall | 8df9ab1 | 2009-07-24 17:06:37 +0000 | [diff] [blame] | 33 | * A <code>Monitorable</code> may optionally support sending notifications when |
| 34 | * the status of its <code>StatusVariables</code> change. Support for change |
| 35 | * notifications can be defined per <code>StatusVariable</code>. |
Christian van Spaandonk | 6381441 | 2008-08-02 09:56:01 +0000 | [diff] [blame] | 36 | * <p> |
| 37 | * Publishing <code>StatusVariables</code> requires the presence of the |
Richard S. Hall | 8df9ab1 | 2009-07-24 17:06:37 +0000 | [diff] [blame] | 38 | * <code>MonitorPermission</code> with the <code>publish</code> action string. |
| 39 | * This permission, however, is not checked during registration of the |
Christian van Spaandonk | 6381441 | 2008-08-02 09:56:01 +0000 | [diff] [blame] | 40 | * <code>Monitorable</code> service. Instead, the <code>MonitorAdmin</code> |
Richard S. Hall | a361758 | 2009-09-01 13:57:57 +0000 | [diff] [blame^] | 41 | * implementation must make sure that when a <code>StatusVariable</code> is |
Christian van Spaandonk | 6381441 | 2008-08-02 09:56:01 +0000 | [diff] [blame] | 42 | * queried, it is shown only if the <code>Monitorable</code> is authorized to |
| 43 | * publish the given <code>StatusVariable</code>. |
Richard S. Hall | 8df9ab1 | 2009-07-24 17:06:37 +0000 | [diff] [blame] | 44 | * |
Richard S. Hall | a361758 | 2009-09-01 13:57:57 +0000 | [diff] [blame^] | 45 | * @version $Revision: 7940 $ |
Christian van Spaandonk | 6381441 | 2008-08-02 09:56:01 +0000 | [diff] [blame] | 46 | */ |
| 47 | public interface Monitorable { |
| 48 | /** |
| 49 | * Returns the list of <code>StatusVariable</code> identifiers published |
| 50 | * by this <code>Monitorable</code>. A <code>StatusVariable</code> name |
| 51 | * is unique within the scope of a <code>Monitorable</code>. The array |
| 52 | * contains the elements in no particular order. The returned value must not |
| 53 | * be <code>null</code>. |
| 54 | * |
| 55 | * @return the <code>StatusVariable<code> identifiers published by this |
| 56 | * object, or an empty array if none are published |
| 57 | */ |
| 58 | public String[] getStatusVariableNames(); |
| 59 | |
| 60 | /** |
| 61 | * Returns the <code>StatusVariable</code> object addressed by its |
| 62 | * identifier. The <code>StatusVariable</code> will hold the value taken |
| 63 | * at the time of this method call. |
| 64 | * <p> |
| 65 | * The given identifier does not contain the Monitorable PID, i.e. it |
| 66 | * specifies the name and not the path of the Status Variable. |
| 67 | * |
| 68 | * @param id the identifier of the <code>StatusVariable</code>, cannot be |
| 69 | * <code>null</code> |
| 70 | * @return the <code>StatusVariable</code> object |
| 71 | * @throws java.lang.IllegalArgumentException if <code>id</code> points to a |
| 72 | * non-existing <code>StatusVariable</code> |
| 73 | */ |
| 74 | public StatusVariable getStatusVariable(String id) |
| 75 | throws IllegalArgumentException; |
| 76 | |
| 77 | /** |
| 78 | * Tells whether the <code>StatusVariable</code> provider is able to send |
| 79 | * instant notifications when the given <code>StatusVariable</code> |
| 80 | * changes. If the <code>Monitorable</code> supports sending change |
| 81 | * updates it must notify the <code>MonitorListener</code> when the value |
| 82 | * of the <code>StatusVariable</code> changes. The |
| 83 | * <code>Monitorable</code> finds the <code>MonitorListener</code> |
| 84 | * service through the Service Registry. |
| 85 | * <p> |
| 86 | * The given identifier does not contain the Monitorable PID, i.e. it |
| 87 | * specifies the name and not the path of the Status Variable. |
| 88 | * |
| 89 | * @param id the identifier of the <code>StatusVariable</code>, cannot be |
| 90 | * <code>null</code> |
| 91 | * @return <code>true</code> if the <code>Monitorable</code> can send |
| 92 | * notification when the given <code>StatusVariable</code> |
| 93 | * changes, <code>false</code> otherwise |
| 94 | * @throws java.lang.IllegalArgumentException if <code>id</code> points to a |
| 95 | * non-existing <code>StatusVariable</code> |
| 96 | */ |
| 97 | public boolean notifiesOnChange(String id) throws IllegalArgumentException; |
| 98 | |
| 99 | /** |
| 100 | * Issues a request to reset a given <code>StatusVariable</code>. |
| 101 | * Depending on the semantics of the actual Status Variable this call may or |
| 102 | * may not succeed: it makes sense to reset a counter to its starting value, |
| 103 | * but for example a <code>StatusVariable</code> of type <code>String</code> |
| 104 | * might not have a meaningful default value. Note that for numeric |
| 105 | * <code>StatusVariables</code> the starting value may not necessarily be |
| 106 | * 0. Resetting a <code>StatusVariable</code> must trigger a monitor event. |
| 107 | * <p> |
| 108 | * The given identifier does not contain the Monitorable PID, i.e. it |
| 109 | * specifies the name and not the path of the Status Variable. |
| 110 | * |
| 111 | * @param id the identifier of the <code>StatusVariable</code>, cannot be |
| 112 | * <code>null</code> |
| 113 | * @return <code>true</code> if the <code>Monitorable</code> could |
| 114 | * successfully reset the given <code>StatusVariable</code>, |
| 115 | * <code>false</code> otherwise |
| 116 | * @throws java.lang.IllegalArgumentException if <code>id</code> points to a |
| 117 | * non-existing <code>StatusVariable</code> |
| 118 | */ |
| 119 | public boolean resetStatusVariable(String id) |
| 120 | throws IllegalArgumentException; |
| 121 | |
| 122 | /** |
| 123 | * Returns a human readable description of a <code>StatusVariable</code>. |
| 124 | * This can be used by management systems on their GUI. The |
| 125 | * <code>null</code> return value is allowed if there is no description for |
| 126 | * the specified Status Variable. |
| 127 | * <p> |
| 128 | * The given identifier does not contain the Monitorable PID, i.e. it |
| 129 | * specifies the name and not the path of the Status Variable. |
| 130 | * |
| 131 | * @param id the identifier of the <code>StatusVariable</code>, cannot be |
| 132 | * <code>null</code> |
| 133 | * @return the human readable description of this |
| 134 | * <code>StatusVariable</code> or <code>null</code> if it is not |
| 135 | * set |
| 136 | * @throws java.lang.IllegalArgumentException if <code>id</code> points to a |
| 137 | * non-existing <code>StatusVariable</code> |
| 138 | */ |
| 139 | public String getDescription(String id) throws IllegalArgumentException; |
| 140 | } |