/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* <p>A Java class can implement this interface to indicate how it is
* to be converted into a {@code CompositeData} by the MXBean framework.</p>
*
* <p>A typical way to use this class is to add extra items to the
* {@code CompositeData} in addition to the ones that are declared in the
* {@code CompositeType} supplied by the MXBean framework. To do this,
* you must create another {@code CompositeType} that has all the same items,
* plus your extra items.</p>
*
* <p>For example, suppose you have a class {@code Measure} that consists of
* a String called {@code units} and a {@code value} that is either a
* {@code long} or a {@code double}. It might look like this:</p>
*
* <pre>
* public class Measure implements CompositeDataView {
* private String units;
* private Number value; // a Long or a Double
*
* public Measure(String units, Number value) {
* this.units = units;
* this.value = value;
* }
*
* public static Measure from(CompositeData cd) {
* return new Measure((String) cd.get("units"),
* (Number) cd.get("value"));
* }
*
* public String getUnits() {
* return units;
* }
*
* // Can't be called getValue(), because Number is not a valid type
* // in an MXBean, so the implied "value" property would be rejected.
* public Number _getValue() {
* return value;
* }
*
* public CompositeData toCompositeData(CompositeType ct) {
* try {
* {@code List<String> itemNames = new ArrayList<String>(ct.keySet());}
* {@code List<String> itemDescriptions = new ArrayList<String>();}
* {@code List<OpenType<?>> itemTypes = new ArrayList<OpenType<?>>();}
* for (String item : itemNames) {
* itemDescriptions.add(ct.getDescription(item));
* itemTypes.add(ct.getType(item));
* }
* itemNames.add("value");
* itemDescriptions.add("long or double value of the measure");
* itemTypes.add((value instanceof Long) ? SimpleType.LONG :
* SimpleType.DOUBLE);
* CompositeType xct =
* new CompositeType(ct.getTypeName(),
* ct.getDescription(),
* itemNames.toArray(new String[0]),
* itemDescriptions.toArray(new String[0]),
* itemTypes.toArray(new OpenType<?>[0]));
* CompositeData cd =
* new CompositeDataSupport(xct,
* new String[] {"units", "value"},
* new Object[] {units, value});
* assert ct.isValue(cd); // check we've done it right
* return cd;
* } catch (Exception e) {
* throw new RuntimeException(e);
* }
* }
* }
* </pre>
*
* <p>The {@code CompositeType} that will appear in the {@code openType} field
* of the {@link javax.management.Descriptor Descriptor} for an attribute or
* operation of this type will show only the {@code units} item, but the actual
* {@code CompositeData} that is generated will have both {@code units} and
* {@code value}.</p>
*
* @see javax.management.MXBean
*
* @since 1.6
*/
public interface CompositeDataView {
/**
* <p>Return a {@code CompositeData} corresponding to the values in
* this object. The returned value should usually be an instance of
* {@link CompositeDataSupport}, or a class that serializes as a
* {@code CompositeDataSupport} via a {@code writeReplace} method.
* Otherwise, a remote client that receives the object might not be
* able to reconstruct it.
*
* @param ct The expected {@code CompositeType} of the returned
* value. If the returned value is {@code cd}, then
* {@code cd.getCompositeType().equals(ct)} should be true.
* Typically this will be because {@code cd} is a
* {@link CompositeDataSupport} constructed with {@code ct} as its
* {@code CompositeType}.
*
* @return the {@code CompositeData}.
*/
}