Descriptor.java 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393
  1. /* Descriptor.java -- Metadata container.
  2. Copyright (C) 2007 Free Software Foundation, Inc.
  3. This file is part of GNU Classpath.
  4. GNU Classpath is free software; you can redistribute it and/or modify
  5. it under the terms of the GNU General Public License as published by
  6. the Free Software Foundation; either version 2, or (at your option)
  7. any later version.
  8. GNU Classpath is distributed in the hope that it will be useful, but
  9. WITHOUT ANY WARRANTY; without even the implied warranty of
  10. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  11. General Public License for more details.
  12. You should have received a copy of the GNU General Public License
  13. along with GNU Classpath; see the file COPYING. If not, write to the
  14. Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  15. 02110-1301 USA.
  16. Linking this library statically or dynamically with other modules is
  17. making a combined work based on this library. Thus, the terms and
  18. conditions of the GNU General Public License cover the whole
  19. combination.
  20. As a special exception, the copyright holders of this library give you
  21. permission to link this library with independent modules to produce an
  22. executable, regardless of the license terms of these independent
  23. modules, and to copy and distribute the resulting executable under
  24. terms of your choice, provided that you also meet, for each linked
  25. independent module, the terms and conditions of the license of that
  26. module. An independent module is a module which is not derived from
  27. or based on this library. If you modify this library, you may extend
  28. this exception to your version of the library, but you are not
  29. obligated to do so. If you do not wish to do so, delete this
  30. exception statement from your version. */
  31. package javax.management;
  32. import java.io.Serializable;
  33. /**
  34. * <p>
  35. * Provides metadata for a management element as a series
  36. * of fields, formed from name-value pairs. Descriptors
  37. * are usually attached to one of the <code>Info</code>
  38. * classes, such as {@link MBeanAttributeInfo}.
  39. * </p>
  40. * <p>
  41. * Field names are not case-sensitive, but are case-preserving
  42. * (in that the same use of case will be returned by
  43. * {@link #getFields()} and {@link #getFieldNames()}).
  44. * The type of the value should match the type returned
  45. * by the <code>getType()</code> method of the associated
  46. * <code>Info</code> object. In the case of {@link MXBean}s,
  47. * this should be the mapped type returned by the mapping rules.
  48. * </p>
  49. * <p>
  50. * The contents of a descriptor may be immutable, in which
  51. * case, attempts to change the contents of the descriptor
  52. * will cause an exception to be thrown. Immutable descriptors
  53. * are usually instances or subclasses of {@link ImmutableDescriptor},
  54. * while mutable descriptors are usually instances or subclasses
  55. * of {@link javax.management.modelmbean.DescriptorSupport}.
  56. * </p>
  57. * <p>
  58. * A series of field names are predefined, but additional
  59. * ones can be added as needed. Predefined names never include
  60. * a period ('.'), and so additional names may safely avoid
  61. * conflicts by including this character. It is recommended that
  62. * additional names make use of the same syntax as Java package
  63. * names e.g. <code>gnu.classpath.ImportantMetadata</code>.
  64. * </p>
  65. * <p>
  66. * The predefined names are as follows:
  67. * </p>
  68. * <table>
  69. * <th>
  70. * <td>Name</td><td>Type</td><td>Used In</td><td>Meaning</td>
  71. * </th>
  72. * <tr>
  73. * <td>defaultValue</td><td>Object</td><td>{@link MBeanAttributeInfo},
  74. * {@link MBeanParameterInfo}</td><td>Default value for an attribute
  75. * or parameter.</td>
  76. * </tr>
  77. * <tr>
  78. * <td>deprecated</td><td>String</td><td>Any</td><td>The annotated element
  79. * has been deprecated. Conventially, the field's value takes the form
  80. * of the version in which the element was deprecated, followed by an
  81. * explaination.</td>
  82. * </tr>
  83. * <tr>
  84. * <td>descriptionResourceBundleBaseName</td><td>String</td><td>Any</td>
  85. * <td>The base name for the bundle in which the <code>descriptionResourceKey</code>
  86. * can be found.</td>
  87. * </tr>
  88. * <tr>
  89. * <td>descriptionResourceKey</td><td>String</td><td>Any</td>
  90. * <td>The name of the resource key which contains a localized description of
  91. * this element.</td>
  92. * </tr>
  93. * <tr>
  94. * <td>enabled</td><td>String</td><td>{@link MBeanAttributeInfo},
  95. * {@link MBeanNotificationInfo}, {@link MBeanOperationInfo}</td>
  96. * <td>Specifies whether the annotated element is currently enabled or
  97. * not, via a value of either <code>"true"</code> or <code>"false"</code>.
  98. * </tr>
  99. * <tr>
  100. * <td>immutableInfo</td><td>String</td><td>{@link MBeanInfo}</td>
  101. * <td>If the value of this field is <code>"true"</code>, this means that
  102. * the annotated element will not change and thus may be cached.</td>
  103. * </tr>
  104. * <tr>
  105. * <td>infoTimeout</td><td>String or Long</td><td>{@link MBeanInfo}</td>
  106. * <td>If this field is present, and non-zero, it will contain a value
  107. * in milliseconds for which the value of the annotated element will
  108. * remain unchanged, allowing it to be safely cached for that period.</td>
  109. * </tr>
  110. * <tr>
  111. * <td>interfaceClassName</td><td>String</td><td>{@link MBeanInfo}</td>
  112. * <td>The Java interface name associated with the bean, as returned
  113. * by {@link Class#getName()}.</td>
  114. * </tr>
  115. * <tr>
  116. * <td>legalValues</td><td>Set<?></td><td>{@link MBeanAttributeInfo},
  117. * {@link MBeanParameterInfo}</td><td>Legal values for an attribute
  118. * or parameter.</td>
  119. * </tr>
  120. * <tr>
  121. * <td>maxValue</td><td>Object</td><td><td>{@link MBeanAttributeInfo},
  122. * {@link MBeanParameterInfo}</td><td>Maximum legal value for an attribute
  123. * or parameter.</td>
  124. * </tr>
  125. * <tr>
  126. * <td>metricType</td><td>String</td><td>{@link MBeanAttributeInfo},
  127. * {@link MBeanOperationInfo}</td><td>Specifies the type of metric represented
  128. * by the annotated element. This will be either <code>"counter"</code>
  129. * (an increasing value, which will only be reset and never decrease)
  130. * or <code>"gauge"</code> (an increasing and decreasing value).</td>
  131. * </tr>
  132. * <tr>
  133. * <td>minValue</td><td>Object</td><td>{@link MBeanAttributeInfo},
  134. * {@link MBeanParameterInfo}</td><td>Minimum legal value for an attribute
  135. * or parameter.</td>
  136. * </tr>
  137. * <tr>
  138. * <td>mxbean</td><td>String</td><td>{@link MBeanInfo}</td>
  139. * <td>Specifies whether the annotated element is an {@link MXBean} or
  140. * not, via a value of either <code>"true"</code> or <code>"false"</code>.
  141. * </tr>
  142. * <tr>
  143. * <td>openType</td><td>{@link javax.management.openmbean.OpenType}</td>
  144. * <td>{@link MBeanAttributeInfo}, {@link MBeanOperationInfo}</td>,
  145. * {@link MBeanNotificationInfo}, {@link MBeanParameterInfo}</td>
  146. * <td>Specifies the open type of the attribute or parameter, the return
  147. * value of the operation or the user data of the notification respectively.
  148. * This is present on <code>Open*Info</code> instances and for {@link MXBean}s.</td>
  149. * <tr>
  150. * <td>originalType</td><td>String</td><td>{@link MBeanAttributeInfo},
  151. * {@link MBeanOperationInfo}, {@link MBeanParameterInfo}</td>
  152. * <td>The original Java type of an element which has been converted
  153. * to another type according to the {@link MXBean} typing rules.
  154. * For example, {@link java.lang.management.MemoryType} becomes a
  155. * String after conversion. This field would contain
  156. * <code>"java.lang.management.MemoryType"</code> to represent the
  157. * earlier type of an element with the converted type.</td>
  158. * </tr>
  159. * <tr>
  160. * <td>severity</td><td>Integer or String</td>
  161. * <td>{@link MBeanNotificationInfo}</td><td>Represents the severity
  162. * of the notification, ranging from 1 (most severe) to 6 (least
  163. * severe), with 0 representing unknown severity.</td>
  164. * </tr>
  165. * <tr>
  166. * <td>since</td><td>String</td><td>Any</td>
  167. * <td>The version in which this field was introduced.</td>
  168. * </tr>
  169. * <tr>
  170. * <td>units</td><td>String</td><td>{@link MBeanAttributeInfo},
  171. * {@link MBeanOperationInfo}, {@link MBeanParameterInfo}</td>
  172. * <td>The units used by the value of an attribute or parameter,
  173. * or the return value of an operation, such as <code>"bytes"</code>,
  174. * <code>"milliseconds"</code> or <code>"kilogrammes"</code>.
  175. * </tr>
  176. * </table>
  177. * <p>Some names are also defined as part of the Model MBeans package.
  178. * See {@link javax.management.modelmbean.ModelMBeanInfo}.</p>
  179. *
  180. * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  181. * @since 1.5
  182. */
  183. public interface Descriptor
  184. extends Serializable, Cloneable
  185. {
  186. /**
  187. * Returns a clone of this descriptor, which can then be modified
  188. * independently of this descriptor. If the descriptor is
  189. * immutable, it is sufficient to return this instance.
  190. *
  191. * @return a clone of this descriptor.
  192. * @throws RuntimeOperationsException if creation of the new
  193. * descriptor fails for any
  194. * reason.
  195. */
  196. Object clone()
  197. throws RuntimeOperationsException;
  198. /**
  199. * <p>
  200. * Returns true if this descriptor is equivalent to the
  201. * supplied object. This is true if the following holds:
  202. * </p>
  203. * <ul>
  204. * <li>The given object is also a {@link Descriptor}.</li>
  205. * <li>Has the same field names, independent of case.</li>
  206. * <li>Has the same values, based on the following:
  207. * <ul>
  208. * <li>If one value is <code>null</code>, the other must be.</li>
  209. * <li>If one value is a primitive array, the other must be a
  210. * primitive array of the same type with the same elements.</li>
  211. * <li>If one value is an {@link Object} array, the other
  212. * must be and {@link java.util.Arrays#deepEquals(Object[],Object[])}
  213. * must return true.</li>
  214. * <li>Otherwise, {@link Object#equals(Object)} must return true.</li>
  215. * </ul>
  216. *
  217. * @param obj the object to compare according to the above.
  218. * @return true if the above holds.
  219. * @see Object#equals(Object)
  220. * @see Object#hashCode()
  221. * @since 1.6
  222. */
  223. boolean equals(Object obj);
  224. /**
  225. * Returns the field names of the descriptor. If the
  226. * descriptor is empty, an empty array is returned.
  227. *
  228. * @return the field names as an array of Strings.
  229. */
  230. String[] getFieldNames();
  231. /**
  232. * <p>
  233. * Returns all the field name and value pairs, in the
  234. * form <code>name=value</code>. The value is converted
  235. * to a String as follows:
  236. * </p>
  237. * <ul>
  238. * <li>If the value is a String, it is used as is.</li>
  239. * <li>If the value is <code>null</code>, the printed
  240. * value will be empty.</li>
  241. * <li>Otherwise, the value will be converted to a
  242. * String using its {@link Object#toString()} method,
  243. * and included as <code>"(" + string + ")"</code>.</li>
  244. * </ul>
  245. * <p>If the descriptor is empty, an empty array is returned.</p>
  246. *
  247. * @return the field names and values as an array of Strings.
  248. * @see #setFields(String[],Object[])
  249. */
  250. String[] getFields();
  251. /**
  252. * Returns the value of the specified field, or <code>null</code>
  253. * if no value is present for the given field name.
  254. *
  255. * @param name the field name.
  256. * @return the value of the field, or <code>null</code> if there
  257. * is no value present.
  258. * @throws RuntimeOperationsException if the field name is illegal.
  259. */
  260. Object getFieldValue(String name);
  261. /**
  262. * Returns the values corresponding to the fields named in
  263. * the specified array, in the same order. If an empty
  264. * array is supplied, an empty array is returned. A value
  265. * of <code>null</code> leads to behaviour equivalent to
  266. * {@link #getFields()}. Field values are obtained as specified
  267. * in {@link #getFieldValue(String)}, with <code>null</code>
  268. * being returned if the field is not present. This applies
  269. * even if the given field name is <code>null</code> or
  270. * the empty string.
  271. *
  272. * @param names an array of field names whose values should
  273. * be returned.
  274. * @return the values of the specified fields.
  275. * @see #getFields()
  276. * @see #getFieldValue(String)
  277. */
  278. Object[] getFieldValues(String... names);
  279. /**
  280. * <p>
  281. * Returns the hash code of the descriptor. The hashcode
  282. * is computed as the sum of the hashcodes for each field,
  283. * which in turn is calculated as the sum of
  284. * the hashcode of the name, <code>n</code>, computed
  285. * using <code>n.toLowerCase().hashCode()</code>, and the
  286. * hashcode of the value, <code>v</code>, computed
  287. * using:
  288. * </p>
  289. * <ul>
  290. * <li>If <code>v</code> is <code>null</code>, then the
  291. * hash code is 0.</li>
  292. * <li>If <code>v</code> is a primitive array, then the
  293. * hash code is computed using the appropriate method
  294. * from {@link java.util.Arrays}.</li>
  295. * <li>If <code>v</code> is an {@link java.lang.Object}
  296. * array, then the hash code is computed using the
  297. * {@link java.util.Arrays#deepHashCode(Object[])} method.</li>
  298. * <li>Otherwise, the hashcode is equal to
  299. * <code>v.hashCode()</code>.
  300. * </ul>
  301. *
  302. * @return a hashcode for this descriptor.
  303. * @since 1.6
  304. * @see Object#equals(Object)
  305. * @see Object#hashCode()
  306. */
  307. int hashCode();
  308. /**
  309. * Returns true if all the fields have legal values, given
  310. * their names. Validity is determined by the implementation.
  311. *
  312. * @return true if the values are legal.
  313. * @throws RuntimeOperationsException if the validity check
  314. * fails for some reason.
  315. */
  316. boolean isValid()
  317. throws RuntimeOperationsException;
  318. /**
  319. * Removes a field from the descriptor. If the field name
  320. * is illegal or not found, this method fails silently.
  321. *
  322. * @param name the name of the field to remove.
  323. * @throws RuntimeOperationsException if the field exists
  324. * and the descriptor is
  325. * immutable. This wraps
  326. * an {@link UnsupportedOperationException}.
  327. */
  328. void removeField(String name);
  329. /**
  330. * Attempts to set the specified field to the supplied
  331. * value. If the field does not exist, it will be created.
  332. * If the field value given is invalid, then an exception will
  333. * be thrown. Validity is determined by the implementation
  334. * of the descriptor.
  335. *
  336. * @param name the field to set. Can not be <code>null</code>
  337. * or empty.
  338. * @param value the value to use, the validity of which is
  339. * determined by the implementation.
  340. * @throws RuntimeOperationsException if the name or value is
  341. * illegal (wrapping a
  342. * {@link IllegalArgumentException})
  343. * or if the descriptor is
  344. * immutable (wrapping a
  345. * {@link UnsupportedOperationException}.
  346. */
  347. void setField(String name, Object value)
  348. throws RuntimeOperationsException;
  349. /**
  350. * Sets the field named in the first array to the corresponding
  351. * value specified in the second. The array sizes must match.
  352. * Empty arrays have no effect. An invalid value will cause
  353. * an exception to be thrown.
  354. *
  355. * @param names the names of the fields to change. Neither
  356. * the array or its elements may be <code>null</code>.
  357. * @param values the values to use. The array must not be
  358. * <code>null</code>. The value of the elements
  359. * depends on the validity constraints of the
  360. * implementation.
  361. * @throws RuntimeOperationsException if the arrays differ in
  362. * length, or a name or value is
  363. * illegal (wrapping a
  364. * {@link IllegalArgumentException})
  365. * or if the descriptor is
  366. * immutable (wrapping a
  367. * {@link UnsupportedOperationException}.
  368. * @see #setField(String,Object)
  369. */
  370. void setFields(String[] names, Object[] values);
  371. }