1. /*
  2. * @(#)file ModelMBeanAttributeInfo.java
  3. * @(#)author IBM Corp.
  4. * @(#)version 1.34
  5. * @(#)lastedit 04/02/10
  6. */
  7. /*
  8. * Copyright IBM Corp. 1999-2000. All rights reserved.
  9. *
  10. * The program is provided "as is" without any warranty express or implied,
  11. * including the warranty of non-infringement and the implied warranties of
  12. * merchantibility and fitness for a particular purpose. IBM will not be
  13. * liable for any damages suffered by you or any third party claim against
  14. * you regarding the Program.
  15. *
  16. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  17. * This software is the proprietary information of Sun Microsystems, Inc.
  18. * Use is subject to license terms.
  19. *
  20. * Copyright 2004 Sun Microsystems, Inc. Tous droits reserves.
  21. * Ce logiciel est propriete de Sun Microsystems, Inc.
  22. * Distribue par des licences qui en restreignent l'utilisation.
  23. *
  24. */
  25. package javax.management.modelmbean;
  26. import java.io.IOException;
  27. import java.io.ObjectInputStream;
  28. import java.io.ObjectOutputStream;
  29. import java.io.ObjectStreamField;
  30. import java.lang.reflect.*;
  31. import java.security.AccessController;
  32. import java.security.PrivilegedAction;
  33. import javax.management.Descriptor;
  34. import javax.management.DescriptorAccess;
  35. import javax.management.*;
  36. import com.sun.jmx.mbeanserver.GetPropertyAction;
  37. import com.sun.jmx.trace.Trace;
  38. /**
  39. * The ModelMBeanAttributeInfo object describes an attribute of the ModelMBean.
  40. * It is a subclass of MBeanAttributeInfo with the addition of an associated Descriptor
  41. * and an implementation of the DescriptorAccess interface.
  42. * <P>
  43. * The fields in the descriptor are defined, but not limited to, the following: <P>
  44. * <PRE>
  45. * name : attribute name
  46. * descriptorType : must be "attribute"
  47. * value : current value for attribute
  48. * default : default value for attribute
  49. * displayName : name of attribute to be used in displays
  50. * getMethod : name of operation descriptor for get method
  51. * setMethod : name of operation descriptor for set method
  52. * protocolMap : object which implements the Descriptor interface: mappings must be appropriate for the attribute
  53. * and entries can be updated or augmented at runtime.
  54. * persistPolicy : OnUpdate|OnTimer|NoMoreOftenThan|Always|Never
  55. * persistPeriod : seconds - frequency of persist cycle. Used when persistPolicy is"OnTimer" or "NoMoreOftenThan".
  56. * currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds
  57. * lastUpdatedTimeStamp : when value was set
  58. * visibility : 1-4 where 1: always visible 4: rarely visible
  59. * presentationString : xml formatted string to allow presentation of data
  60. * </PRE>
  61. * The default descriptor contains the name, descriptorType and displayName fields.
  62. *
  63. * <p><b>Note:</b> because of inconsistencies in previous versions of
  64. * this specification, it is recommended not to use negative or zero
  65. * values for <code>currencyTimeLimit</code>. To indicate that a
  66. * cached value is never valid, omit the
  67. * <code>currencyTimeLimit</code> field. To indicate that it is
  68. * always valid, use a very large number for this field.</p>
  69. *
  70. * @since 1.5
  71. */
  72. public class ModelMBeanAttributeInfo extends MBeanAttributeInfo
  73. implements DescriptorAccess, Cloneable
  74. {
  75. // Serialization compatibility stuff:
  76. // Two serial forms are supported in this class. The selected form depends
  77. // on system property "jmx.serial.form":
  78. // - "1.0" for JMX 1.0
  79. // - any other value for JMX 1.1 and higher
  80. //
  81. // Serial version for old serial form
  82. private static final long oldSerialVersionUID = 7098036920755973145L;
  83. //
  84. // Serial version for new serial form
  85. private static final long newSerialVersionUID = 6181543027787327345L;
  86. //
  87. // Serializable fields in old serial form
  88. private static final ObjectStreamField[] oldSerialPersistentFields =
  89. {
  90. new ObjectStreamField("attrDescriptor", Descriptor.class),
  91. new ObjectStreamField("currClass", String.class)
  92. };
  93. //
  94. // Serializable fields in new serial form
  95. private static final ObjectStreamField[] newSerialPersistentFields =
  96. {
  97. new ObjectStreamField("attrDescriptor", Descriptor.class)
  98. };
  99. //
  100. // Actual serial version and serial form
  101. private static final long serialVersionUID;
  102. /**
  103. * @serialField attrDescriptor Descriptor The {@link Descriptor} containing the metadata corresponding to
  104. * this attribute
  105. */
  106. private static final ObjectStreamField[] serialPersistentFields;
  107. private static boolean compat = false;
  108. static {
  109. try {
  110. PrivilegedAction act = new GetPropertyAction("jmx.serial.form");
  111. String form = (String) AccessController.doPrivileged(act);
  112. compat = (form != null && form.equals("1.0"));
  113. } catch (Exception e) {
  114. // OK: No compat with 1.0
  115. }
  116. if (compat) {
  117. serialPersistentFields = oldSerialPersistentFields;
  118. serialVersionUID = oldSerialVersionUID;
  119. } else {
  120. serialPersistentFields = newSerialPersistentFields;
  121. serialVersionUID = newSerialVersionUID;
  122. }
  123. }
  124. //
  125. // END Serialization compatibility stuff
  126. /**
  127. * @serial The {@link Descriptor} containing the metadata corresponding to
  128. * this attribute
  129. */
  130. private Descriptor attrDescriptor = createDefaultDescriptor();
  131. private final static String currClass = "ModelMBeanAttributeInfo";
  132. /**
  133. * Constructs a ModelMBeanAttributeInfo object with a default descriptor.
  134. *
  135. * @param name The name of the attribute.
  136. * @param description A human readable description of the attribute. Optional.
  137. * @param getter The method used for reading the attribute value.
  138. * May be null if the property is write-only.
  139. * @param setter The method used for writing the attribute value.
  140. * May be null if the attribute is read-only.
  141. * @exception IntrospectionException There is a consistency problem in the definition of this attribute.
  142. *
  143. */
  144. public ModelMBeanAttributeInfo(String name,
  145. String description,
  146. Method getter,
  147. Method setter)
  148. throws javax.management.IntrospectionException {
  149. super(name, description, getter, setter);
  150. if (tracing())
  151. {
  152. trace("ModelMBeanAttributeInfo(" + name + ",String,Method,Method)","Entry");
  153. }
  154. attrDescriptor = createDefaultDescriptor();
  155. // put getter and setter methods in operations list
  156. // create default descriptor
  157. }
  158. /**
  159. * Constructs a ModelMBeanAttributeInfo object.
  160. *
  161. * @param name The name of the attribute.
  162. * @param description A human readable description of the attribute. Optional.
  163. * @param getter The method used for reading the attribute value.
  164. * May be null if the property is write-only.
  165. * @param setter The method used for writing the attribute value.
  166. * May be null if the attribute is read-only.
  167. * @param descriptor An instance of Descriptor containing the appropriate metadata
  168. * for this instance of the Attribute. If it is null, then a default descriptor will be created.
  169. * If the descriptor does not contain the field "displayName" this field is added in the descriptor with its default value.
  170. *
  171. * @exception IntrospectionException There is a consistency problem in the definition of this attribute.
  172. * @exception RuntimeOperationsException Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not
  173. * equal to name parameter, or descriptor field "DescriptorType" is not equal to "attribute".
  174. *
  175. */
  176. public ModelMBeanAttributeInfo(String name,
  177. String description,
  178. Method getter,
  179. Method setter,
  180. Descriptor descriptor)
  181. throws javax.management.IntrospectionException {
  182. super(name, description, getter, setter);
  183. // put getter and setter methods in operations list
  184. if (tracing())
  185. {
  186. trace("ModelMBeanAttributeInfo(" + name + ", String, Method, Method, Descriptor)","Entry");
  187. }
  188. if (descriptor == null)
  189. {
  190. attrDescriptor = createDefaultDescriptor();
  191. } else
  192. {
  193. if (isValid(descriptor))
  194. {
  195. attrDescriptor = (Descriptor) descriptor.clone();
  196. } else
  197. {
  198. throw new RuntimeOperationsException(new IllegalArgumentException("Invalid descriptor passed in parameter"), ("Exception occured in ModelMBeanAttributeInfo constructor"));
  199. }
  200. }
  201. }
  202. /**
  203. * Constructs a ModelMBeanAttributeInfo object with a default descriptor.
  204. *
  205. * @param name The name of the attribute
  206. * @param type The type or class name of the attribute
  207. * @param description A human readable description of the attribute.
  208. * @param isReadable True if the attribute has a getter method, false otherwise.
  209. * @param isWritable True if the attribute has a setter method, false otherwise.
  210. * @param isIs True if the attribute has an "is" getter, false otherwise.
  211. *
  212. */
  213. public ModelMBeanAttributeInfo(String name,
  214. String type,
  215. String description,
  216. boolean isReadable,
  217. boolean isWritable,
  218. boolean isIs)
  219. {
  220. super(name, type, description, isReadable, isWritable, isIs);
  221. // create default descriptor
  222. if (tracing())
  223. {
  224. trace("ModelMBeanAttributeInfo(" + name + ",String,String,boolean,boolean)","Entry");
  225. }
  226. attrDescriptor = createDefaultDescriptor();
  227. }
  228. /**
  229. * Constructs a ModelMBeanAttributeInfo object with a default descriptor.
  230. *
  231. * @param name The name of the attribute
  232. * @param type The type or class name of the attribute
  233. * @param description A human readable description of the attribute.
  234. * @param isReadable True if the attribute has a getter method, false otherwise.
  235. * @param isWritable True if the attribute has a setter method, false otherwise.
  236. * @param isIs True if the attribute has an "is" getter, false otherwise.
  237. * @param descriptor An instance of Descriptor containing the appropriate metadata
  238. * for this instance of the Attribute. If it is null then a default descriptor will be created.
  239. * If the descriptor does not contain the field "displayName" this field is added in the descriptor with its default value.
  240. *
  241. * @exception RuntimeOperationsException Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not
  242. * equal to name parameter, or descriptor field "DescriptorType" is not equal to "attribute".
  243. *
  244. */
  245. public ModelMBeanAttributeInfo(String name,
  246. String type,
  247. String description,
  248. boolean isReadable,
  249. boolean isWritable,
  250. boolean isIs,
  251. Descriptor descriptor)
  252. {
  253. super(name, type, description, isReadable, isWritable, isIs);
  254. if (tracing())
  255. {
  256. trace("ModelMBeanAttributeInfo(" + name + ",String,String,boolean,boolean,Descriptor)","Entry");
  257. }
  258. if (descriptor == null)
  259. {
  260. attrDescriptor = createDefaultDescriptor();
  261. } else
  262. {
  263. if (isValid(descriptor))
  264. {
  265. attrDescriptor = (Descriptor) descriptor.clone();
  266. } else
  267. {
  268. throw new RuntimeOperationsException(new IllegalArgumentException("Invalid descriptor passed in parameter"), ("Exception occured in ModelMBeanAttributeInfo constructor"));
  269. }
  270. }
  271. }
  272. /**
  273. * Constructs a new ModelMBeanAttributeInfo object from this ModelMBeanAttributeInfo Object.
  274. * A default descriptor will be created.
  275. *
  276. * @param inInfo the ModelMBeanAttributeInfo to be duplicated
  277. */
  278. public ModelMBeanAttributeInfo(ModelMBeanAttributeInfo inInfo)
  279. {
  280. super(inInfo.getName(),
  281. inInfo.getType(),
  282. inInfo.getDescription(),
  283. inInfo.isReadable(),
  284. inInfo.isWritable(),
  285. inInfo.isIs());
  286. if (tracing())
  287. {
  288. trace("ModelMBeanAttributeInfo(ModelMBeanAttributeInfo)","Entry");
  289. }
  290. Descriptor newDesc = inInfo.getDescriptor();
  291. //Descriptor newDesc = inInfo.attrDescriptor;
  292. if ((newDesc != null) && (isValid(newDesc)))
  293. {
  294. attrDescriptor = newDesc;
  295. } else
  296. {
  297. attrDescriptor = createDefaultDescriptor();
  298. }
  299. }
  300. /**
  301. * Gets a copy of the associated Descriptor for the
  302. * ModelMBeanAttributeInfo.
  303. *
  304. * @return Descriptor associated with the
  305. * ModelMBeanAttributeInfo object.
  306. *
  307. * @see #setDescriptor
  308. */
  309. public Descriptor getDescriptor()
  310. {
  311. if (tracing())
  312. {
  313. trace("ModelMBeanAttributeInfo.getDescriptor()","Entry");
  314. }
  315. if (attrDescriptor == null)
  316. {
  317. attrDescriptor = createDefaultDescriptor();
  318. }
  319. return((Descriptor)attrDescriptor.clone());
  320. }
  321. /**
  322. * Sets associated Descriptor (full replace) for the
  323. * ModelMBeanAttributeDescriptor. If the new Descriptor is
  324. * null, then the associated Descriptor reverts to a default
  325. * descriptor. The Descriptor is validated before it is
  326. * assigned. If the new Descriptor is invalid, then a
  327. * RuntimeOperationsException wrapping an
  328. * IllegalArgumentException is thrown.
  329. *
  330. * @param inDescriptor replaces the Descriptor associated with the
  331. * ModelMBeanAttributeInfo
  332. *
  333. * @exception RuntimeOperationsException Wraps an
  334. * IllegalArgumentException for an invalid Descriptor
  335. *
  336. * @see #getDescriptor
  337. */
  338. public void setDescriptor(Descriptor inDescriptor)
  339. {
  340. if (inDescriptor != null) {
  341. if (tracing()) {
  342. trace("ModelMBeanAttributeInfo.setDescriptor()","Executed for " + inDescriptor.toString());
  343. }
  344. }
  345. if (inDescriptor == null) {
  346. if (tracing()) {
  347. trace("ModelMBeanAttributeInfo.setDescriptor()",
  348. "Received null for new descriptor value, setting descriptor to default values");
  349. }
  350. attrDescriptor = createDefaultDescriptor();
  351. }
  352. else {
  353. if (isValid(inDescriptor)) {
  354. attrDescriptor = (Descriptor) inDescriptor.clone();
  355. }
  356. else {
  357. throw new RuntimeOperationsException(new IllegalArgumentException("Invalid descriptor passed in parameter"),
  358. ("Exception occured in ModelMBeanAttributeInfo setDescriptor"));
  359. }
  360. }
  361. }
  362. /**
  363. * Creates and returns a new ModelMBeanAttributeInfo which is a duplicate of this ModelMBeanAttributeInfo.
  364. *
  365. * @exception RuntimeOperationsException for illegal value for field Names or field Values.
  366. * If the descriptor construction fails for any reason, this exception will be thrown.
  367. */
  368. public Object clone()
  369. {
  370. if (tracing())
  371. {
  372. trace("ModelMBeanAttributeInfo.clone()","Entry");
  373. }
  374. return(new ModelMBeanAttributeInfo(this));
  375. }
  376. /**
  377. * Returns a human-readable version of the
  378. * ModelMBeanAttributeInfo instance.
  379. */
  380. public String toString()
  381. {
  382. return
  383. "ModelMBeanAttributeInfo: " + this.getName() +
  384. " ; Description: " + this.getDescription() +
  385. " ; Types: " + this.getType() +
  386. " ; isReadable: " + this.isReadable() +
  387. " ; isWritable: " + this.isWritable() +
  388. " ; Descriptor: " + this.getDescriptor();
  389. }
  390. /**
  391. * Creates and returns a Descriptor with default values set:
  392. * descriptorType=attribute,name=this.getName(),displayName=this.getName(),
  393. * persistPolicy=never,visibility=1
  394. */
  395. private Descriptor createDefaultDescriptor()
  396. {
  397. if (tracing())
  398. {
  399. trace("ModelMBeanAttributeInfo.createDefaultDescriptor()","Entry");
  400. }
  401. return new DescriptorSupport(
  402. new String[] {"descriptorType=attribute",
  403. ("name=" + this.getName()),
  404. ("displayName=" + this.getName())
  405. });
  406. }
  407. /**
  408. * Tests that the descriptor is valid and adds appropriate default fields not already
  409. * specified. Field values must be correct for field names.
  410. * Descriptor must have the same name as the attribute,the descriptorType field must be "attribute",
  411. * The following fields will be defaulted if they are not already set:
  412. * displayName=this.getName(),persistPolicy=never,visibility=1
  413. */
  414. private boolean isValid(Descriptor inDesc)
  415. {
  416. // name and descriptor type must be correct
  417. // add in displayName, persistPolicy, visibility if they apply
  418. boolean results=true;
  419. String badField="none";
  420. if (inDesc == null)
  421. {
  422. badField="nullDescriptor";
  423. results = false;
  424. }
  425. else if (!inDesc.isValid())
  426. { // checks for empty descriptors, null,
  427. // checks for empty name and descriptorType adn valid values for fields.
  428. badField="inValidDescriptor";
  429. results = false;
  430. }
  431. else if (! ((String)inDesc.getFieldValue("name")).equalsIgnoreCase(this.getName()))
  432. {
  433. badField="name";
  434. results = false;
  435. } else
  436. {
  437. if (! ((String)inDesc.getFieldValue("descriptorType")).equalsIgnoreCase("attribute"))
  438. {
  439. badField="desriptorType";
  440. results = false;
  441. } else if ((inDesc.getFieldValue("displayName")) == null)
  442. {
  443. inDesc.setField("displayName",this.getName());
  444. }
  445. }
  446. if (tracing()) trace("isValid()",("Returning " + results + ": Invalid field is " + badField));
  447. return results;
  448. }
  449. // SUN Trace and debug functions
  450. private boolean tracing()
  451. {
  452. // return false;
  453. return Trace.isSelected(Trace.LEVEL_TRACE, Trace.INFO_MODELMBEAN);
  454. }
  455. private void trace(String inClass, String inMethod, String inText)
  456. {
  457. // System.out.println("TRACE: " + inClass + ":" + inMethod + ": " + inText);
  458. Trace.send(Trace.LEVEL_TRACE, Trace.INFO_MODELMBEAN, inClass,
  459. inMethod, Integer.toHexString(this.hashCode()) + " " + inText);
  460. }
  461. private void trace(String inMethod, String inText)
  462. {
  463. trace(currClass, inMethod, inText);
  464. }
  465. /**
  466. * Deserializes a {@link ModelMBeanAttributeInfo} from an {@link ObjectInputStream}.
  467. */
  468. private void readObject(ObjectInputStream in)
  469. throws IOException, ClassNotFoundException {
  470. // New serial form ignores extra field "currClass"
  471. in.defaultReadObject();
  472. }
  473. /**
  474. * Serializes a {@link ModelMBeanAttributeInfo} to an {@link ObjectOutputStream}.
  475. */
  476. private void writeObject(ObjectOutputStream out)
  477. throws IOException {
  478. if (compat)
  479. {
  480. // Serializes this instance in the old serial form
  481. //
  482. ObjectOutputStream.PutField fields = out.putFields();
  483. fields.put("attrDescriptor", attrDescriptor);
  484. fields.put("currClass", currClass);
  485. out.writeFields();
  486. }
  487. else
  488. {
  489. // Serializes this instance in the new serial form
  490. //
  491. out.defaultWriteObject();
  492. }
  493. }
  494. }