src/share/classes/com/sun/jmx/mbeanserver/MXBeanMapping.java - toolchain/jdk/jdk9_jdk - Git at Google

 /*
  * Copyright (c) 2007, 2008, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * 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.
  */

 package com.sun.jmx.mbeanserver;

 import java.io.InvalidObjectException;
 import java.lang.reflect.Type;
 import javax.management.openmbean.OpenDataException;
 import javax.management.openmbean.OpenType;

 /**
  * <p>A custom mapping between Java types and Open types for use in MXBeans.
  * To define such a mapping, subclass this class and define at least the
  * {@link #fromOpenValue fromOpenValue} and {@link #toOpenValue toOpenValue}
  * methods, and optionally the {@link #checkReconstructible} method.
  * Then either use an {@link MXBeanMappingClass} annotation on your custom
  * Java types, or include this MXBeanMapping in an
  * {@link MXBeanMappingFactory}.</p>
  *
  * <p>For example, suppose we have a class {@code MyLinkedList}, which looks
  * like this:</p>
  *
  * <pre>
  * public class MyLinkedList {
  *     public MyLinkedList(String name, MyLinkedList next) {...}
  *     public String getName() {...}
  *     public MyLinkedList getNext() {...}
  * }
  * </pre>
  *
  * <p>This is not a valid type for MXBeans, because it contains a
  * self-referential property "next" defined by the {@code getNext()}
  * method.  MXBeans do not support recursive types.  So we would like
  * to specify a mapping for {@code MyLinkedList} explicitly. When an
  * MXBean interface contains {@code MyLinkedList}, that will be mapped
  * into a {@code String[]}, which is a valid Open Type.</p>
  *
  * <p>To define this mapping, we first subclass {@code MXBeanMapping}:</p>
  *
  * <pre>
  * public class MyLinkedListMapping extends MXBeanMapping {
  *     public MyLinkedListMapping(Type type) throws OpenDataException {
  *         super(MyLinkedList.class, ArrayType.getArrayType(SimpleType.STRING));
  *         if (type != MyLinkedList.class)
  *             throw new OpenDataException("Mapping only valid for MyLinkedList");
  *     }
  *
  *     {@literal @Override}
  *     public Object fromOpenValue(Object openValue) throws InvalidObjectException {
  *         String[] array = (String[]) openValue;
  *         MyLinkedList list = null;
  *         for (int i = array.length - 1; i &gt;= 0; i--)
  *             list = new MyLinkedList(array[i], list);
  *         return list;
  *     }
  *
  *     {@literal @Override}
  *     public Object toOpenValue(Object javaValue) throws OpenDataException {
  *         ArrayList&lt;String&gt; array = new ArrayList&lt;String&gt;();
  *         for (MyLinkedList list = (MyLinkedList) javaValue; list != null;
  *              list = list.getNext())
  *             array.add(list.getName());
  *         return array.toArray(new String[0]);
  *     }
  * }
  * </pre>
  *
  * <p>The call to the superclass constructor specifies what the
  * original Java type is ({@code MyLinkedList.class}) and what Open
  * Type it is mapped to ({@code
  * ArrayType.getArrayType(SimpleType.STRING)}). The {@code
  * fromOpenValue} method says how we go from the Open Type ({@code
  * String[]}) to the Java type ({@code MyLinkedList}), and the {@code
  * toOpenValue} method says how we go from the Java type to the Open
  * Type.</p>
  *
  * <p>With this mapping defined, we can annotate the {@code MyLinkedList}
  * class appropriately:</p>
  *
  * <pre>
  * {@literal @MXBeanMappingClass}(MyLinkedListMapping.class)
  * public class MyLinkedList {...}
  * </pre>
  *
  * <p>Now we can use {@code MyLinkedList} in an MXBean interface and it
  * will work.</p>
  *
  * <p>If we are unable to modify the {@code MyLinkedList} class,
  * we can define an {@link MXBeanMappingFactory}.  See the documentation
  * of that class for further details.</p>
  *
  * @see <a href="../MXBean.html#custom">MXBean specification, section
  * "Custom MXBean type mappings"</a>
  */
 public abstract class MXBeanMapping {
     private final Type javaType;
     private final OpenType<?> openType;
     private final Class<?> openClass;

     /**
      * <p>Construct a mapping between the given Java type and the given
      * Open Type.</p>
      *
      * @param javaType the Java type (for example, {@code MyLinkedList}).
      * @param openType the Open Type (for example, {@code
      * ArrayType.getArrayType(SimpleType.STRING)})
      *
      * @throws NullPointerException if either argument is null.
      */
     protected MXBeanMapping(Type javaType, OpenType<?> openType) {
         if (javaType == null || openType == null)
             throw new NullPointerException("Null argument");
         this.javaType = javaType;
         this.openType = openType;
         this.openClass = makeOpenClass(javaType, openType);
     }

     /**
      * <p>The Java type that was supplied to the constructor.</p>
      * @return the Java type that was supplied to the constructor.
      */
     public final Type getJavaType() {
         return javaType;
     }

     /**
      * <p>The Open Type that was supplied to the constructor.</p>
      * @return the Open Type that was supplied to the constructor.
      */
     public final OpenType<?> getOpenType() {
         return openType;
     }

     /**
      * <p>The Java class that corresponds to instances of the
      * {@linkplain #getOpenType() Open Type} for this mapping.</p>
      * @return the Java class that corresponds to instances of the
      * Open Type for this mapping.
      * @see OpenType#getClassName
      */
     public final Class<?> getOpenClass() {
         return openClass;
     }

     private static Class<?> makeOpenClass(Type javaType, OpenType<?> openType) {
         if (javaType instanceof Class<?> && ((Class<?>) javaType).isPrimitive())
             return (Class<?>) javaType;
         try {
             String className = openType.getClassName();
             return Class.forName(className, false, null);
         } catch (ClassNotFoundException e) {
             throw new RuntimeException(e);  // should not happen
         }
     }

     /**
      * <p>Convert an instance of the Open Type into the Java type.
      * @param openValue the value to be converted.
      * @return the converted value.
      * @throws InvalidObjectException if the value cannot be converted.
      */
     public abstract Object fromOpenValue(Object openValue)
     throws InvalidObjectException;

     /**
      * <p>Convert an instance of the Java type into the Open Type.
      * @param javaValue the value to be converted.
      * @return the converted value.
      * @throws OpenDataException if the value cannot be converted.
      */
     public abstract Object toOpenValue(Object javaValue)
     throws OpenDataException;


     /**
      * <p>Throw an appropriate InvalidObjectException if we will not
      * be able to convert back from the open data to the original Java
      * object.  The {@link #fromOpenValue fromOpenValue} throws an
      * exception if a given open data value cannot be converted.  This
      * method throws an exception if <em>no</em> open data values can
      * be converted.  The default implementation of this method never
      * throws an exception.  Subclasses can override it as
      * appropriate.</p>
      * @throws InvalidObjectException if {@code fromOpenValue} will throw
      * an exception no matter what its argument is.
      */
     public void checkReconstructible() throws InvalidObjectException {}
 }
	/*
	* Copyright (c) 2007, 2008, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* 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.
	*/

	package com.sun.jmx.mbeanserver;

	import java.io.InvalidObjectException;
	import java.lang.reflect.Type;
	import javax.management.openmbean.OpenDataException;
	import javax.management.openmbean.OpenType;

	/**
	* <p>A custom mapping between Java types and Open types for use in MXBeans.
	* To define such a mapping, subclass this class and define at least the
	* {@link #fromOpenValue fromOpenValue} and {@link #toOpenValue toOpenValue}
	* methods, and optionally the {@link #checkReconstructible} method.
	* Then either use an {@link MXBeanMappingClass} annotation on your custom
	* Java types, or include this MXBeanMapping in an
	* {@link MXBeanMappingFactory}.</p>
	*
	* <p>For example, suppose we have a class {@code MyLinkedList}, which looks
	* like this:</p>
	*
	* <pre>
	* public class MyLinkedList {
	* public MyLinkedList(String name, MyLinkedList next) {...}
	* public String getName() {...}
	* public MyLinkedList getNext() {...}
	* }
	* </pre>
	*
	* <p>This is not a valid type for MXBeans, because it contains a
	* self-referential property "next" defined by the {@code getNext()}
	* method. MXBeans do not support recursive types. So we would like
	* to specify a mapping for {@code MyLinkedList} explicitly. When an
	* MXBean interface contains {@code MyLinkedList}, that will be mapped
	* into a {@code String[]}, which is a valid Open Type.</p>
	*
	* <p>To define this mapping, we first subclass {@code MXBeanMapping}:</p>
	*
	* <pre>
	* public class MyLinkedListMapping extends MXBeanMapping {
	* public MyLinkedListMapping(Type type) throws OpenDataException {
	* super(MyLinkedList.class, ArrayType.getArrayType(SimpleType.STRING));
	* if (type != MyLinkedList.class)
	* throw new OpenDataException("Mapping only valid for MyLinkedList");
	* }
	*
	* {@literal @Override}
	* public Object fromOpenValue(Object openValue) throws InvalidObjectException {
	* String[] array = (String[]) openValue;
	* MyLinkedList list = null;
	* for (int i = array.length - 1; i >= 0; i--)
	* list = new MyLinkedList(array[i], list);
	* return list;
	* }
	*
	* {@literal @Override}
	* public Object toOpenValue(Object javaValue) throws OpenDataException {
	* ArrayList<String> array = new ArrayList<String>();
	* for (MyLinkedList list = (MyLinkedList) javaValue; list != null;
	* list = list.getNext())
	* array.add(list.getName());
	* return array.toArray(new String[0]);
	* }
	* }
	* </pre>
	*
	* <p>The call to the superclass constructor specifies what the
	* original Java type is ({@code MyLinkedList.class}) and what Open
	* Type it is mapped to ({@code
	* ArrayType.getArrayType(SimpleType.STRING)}). The {@code
	* fromOpenValue} method says how we go from the Open Type ({@code
	* String[]}) to the Java type ({@code MyLinkedList}), and the {@code
	* toOpenValue} method says how we go from the Java type to the Open
	* Type.</p>
	*
	* <p>With this mapping defined, we can annotate the {@code MyLinkedList}
	* class appropriately:</p>
	*
	* <pre>
	* {@literal @MXBeanMappingClass}(MyLinkedListMapping.class)
	* public class MyLinkedList {...}
	* </pre>
	*
	* <p>Now we can use {@code MyLinkedList} in an MXBean interface and it
	* will work.</p>
	*
	* <p>If we are unable to modify the {@code MyLinkedList} class,
	* we can define an {@link MXBeanMappingFactory}. See the documentation
	* of that class for further details.</p>
	*
	* @see <a href="../MXBean.html#custom">MXBean specification, section
	* "Custom MXBean type mappings"</a>
	*/
	public abstract class MXBeanMapping {
	private final Type javaType;
	private final OpenType<?> openType;
	private final Class<?> openClass;

	/**
	* <p>Construct a mapping between the given Java type and the given
	* Open Type.</p>
	*
	* @param javaType the Java type (for example, {@code MyLinkedList}).
	* @param openType the Open Type (for example, {@code
	* ArrayType.getArrayType(SimpleType.STRING)})
	*
	* @throws NullPointerException if either argument is null.
	*/
	protected MXBeanMapping(Type javaType, OpenType<?> openType) {
	if (javaType == null \|\| openType == null)
	throw new NullPointerException("Null argument");
	this.javaType = javaType;
	this.openType = openType;
	this.openClass = makeOpenClass(javaType, openType);
	}

	/**
	* <p>The Java type that was supplied to the constructor.</p>
	* @return the Java type that was supplied to the constructor.
	*/
	public final Type getJavaType() {
	return javaType;
	}

	/**
	* <p>The Open Type that was supplied to the constructor.</p>
	* @return the Open Type that was supplied to the constructor.
	*/
	public final OpenType<?> getOpenType() {
	return openType;
	}

	/**
	* <p>The Java class that corresponds to instances of the
	* {@linkplain #getOpenType() Open Type} for this mapping.</p>
	* @return the Java class that corresponds to instances of the
	* Open Type for this mapping.
	* @see OpenType#getClassName
	*/
	public final Class<?> getOpenClass() {
	return openClass;
	}

	private static Class<?> makeOpenClass(Type javaType, OpenType<?> openType) {
	if (javaType instanceof Class<?> && ((Class<?>) javaType).isPrimitive())
	return (Class<?>) javaType;
	try {
	String className = openType.getClassName();
	return Class.forName(className, false, null);
	} catch (ClassNotFoundException e) {
	throw new RuntimeException(e); // should not happen
	}
	}

	/**
	* <p>Convert an instance of the Open Type into the Java type.
	* @param openValue the value to be converted.
	* @return the converted value.
	* @throws InvalidObjectException if the value cannot be converted.
	*/
	public abstract Object fromOpenValue(Object openValue)
	throws InvalidObjectException;

	/**
	* <p>Convert an instance of the Java type into the Open Type.
	* @param javaValue the value to be converted.
	* @return the converted value.
	* @throws OpenDataException if the value cannot be converted.
	*/
	public abstract Object toOpenValue(Object javaValue)
	throws OpenDataException;


	/**
	* <p>Throw an appropriate InvalidObjectException if we will not
	* be able to convert back from the open data to the original Java
	* object. The {@link #fromOpenValue fromOpenValue} throws an
	* exception if a given open data value cannot be converted. This
	* method throws an exception if <em>no</em> open data values can
	* be converted. The default implementation of this method never
	* throws an exception. Subclasses can override it as
	* appropriate.</p>
	* @throws InvalidObjectException if {@code fromOpenValue} will throw
	* an exception no matter what its argument is.
	*/
	public void checkReconstructible() throws InvalidObjectException {}
	}