View Javadoc
1   /*
2    * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.management.openmbean;
27  
28  /**
29   * <p>A Java class can implement this interface to indicate how it is
30   * to be converted into a {@code CompositeData} by the MXBean framework.</p>
31   *
32   * <p>A typical way to use this class is to add extra items to the
33   * {@code CompositeData} in addition to the ones that are declared in the
34   * {@code CompositeType} supplied by the MXBean framework.  To do this,
35   * you must create another {@code CompositeType} that has all the same items,
36   * plus your extra items.</p>
37   *
38   * <p>For example, suppose you have a class {@code Measure} that consists of
39   * a String called {@code units} and a {@code value} that is either a
40   * {@code long} or a {@code double}.  It might look like this:</p>
41   *
42   * <pre>
43   * public class Measure implements CompositeDataView {
44   *     private String units;
45   *     private Number value; // a Long or a Double
46   *
47   *     public Measure(String units, Number value) {
48   *         this.units = units;
49   *         this.value = value;
50   *     }
51   *
52   *     public static Measure from(CompositeData cd) {
53   *         return new Measure((String) cd.get("units"),
54   *                            (Number) cd.get("value"));
55   *     }
56   *
57   *     public String getUnits() {
58   *         return units;
59   *     }
60   *
61   *     // Can't be called getValue(), because Number is not a valid type
62   *     // in an MXBean, so the implied "value" property would be rejected.
63   *     public Number _getValue() {
64   *         return value;
65   *     }
66   *
67   *     public CompositeData toCompositeData(CompositeType ct) {
68   *         try {
69   *             {@code List<String> itemNames = new ArrayList<String>(ct.keySet());}
70   *             {@code List<String> itemDescriptions = new ArrayList<String>();}
71   *             {@code List<OpenType<?>> itemTypes = new ArrayList<OpenType<?>>();}
72   *             for (String item : itemNames) {
73   *                 itemDescriptions.add(ct.getDescription(item));
74   *                 itemTypes.add(ct.getType(item));
75   *             }
76   *             itemNames.add("value");
77   *             itemDescriptions.add("long or double value of the measure");
78   *             itemTypes.add((value instanceof Long) ? SimpleType.LONG :
79   *                           SimpleType.DOUBLE);
80   *             CompositeType xct =
81   *                 new CompositeType(ct.getTypeName(),
82   *                                   ct.getDescription(),
83   *                                   itemNames.toArray(new String[0]),
84   *                                   itemDescriptions.toArray(new String[0]),
85   *                                   itemTypes.toArray(new OpenType&lt;?&gt;[0]));
86   *             CompositeData cd =
87   *                 new CompositeDataSupport(xct,
88   *                                          new String[] {"units", "value"},
89   *                                          new Object[] {units, value});
90   *             assert ct.isValue(cd);  // check we've done it right
91   *             return cd;
92   *         } catch (Exception e) {
93   *             throw new RuntimeException(e);
94   *         }
95   *     }
96   * }
97   * </pre>
98   *
99   * <p>The {@code CompositeType} that will appear in the {@code openType} field
100  * of the {@link javax.management.Descriptor Descriptor} for an attribute or
101  * operation of this type will show only the {@code units} item, but the actual
102  * {@code CompositeData} that is generated will have both {@code units} and
103  * {@code value}.</p>
104  *
105  * @see javax.management.MXBean
106  *
107  * @since 1.6
108  */
109 public interface CompositeDataView {
110     /**
111      * <p>Return a {@code CompositeData} corresponding to the values in
112      * this object.  The returned value should usually be an instance of
113      * {@link CompositeDataSupport}, or a class that serializes as a
114      * {@code CompositeDataSupport} via a {@code writeReplace} method.
115      * Otherwise, a remote client that receives the object might not be
116      * able to reconstruct it.
117      *
118      * @param ct The expected {@code CompositeType} of the returned
119      * value.  If the returned value is {@code cd}, then
120      * {@code cd.getCompositeType().equals(ct)} should be true.
121      * Typically this will be because {@code cd} is a
122      * {@link CompositeDataSupport} constructed with {@code ct} as its
123      * {@code CompositeType}.
124      *
125      * @return the {@code CompositeData}.
126      */
127     public CompositeData toCompositeData(CompositeType ct);
128 }