/* * 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 javax.management.openmbean.*;import com.sun.jmx.mbeanserver.MXBeanMapping;import com.sun.jmx.mbeanserver.DefaultMXBeanMappingFactory;import java.lang.reflect.Type; /** * <p>Defines how types are mapped for a given MXBean or set of MXBeans. * An {@code MXBeanMappingFactory} can be specified either through the * {@link MXBeanMappingFactoryClass} annotation, or through the * {@link javax.management.JMX.MBeanOptions JMX.MBeanOptions} argument to a * {@link javax.management.StandardMBean StandardMBean} constructor or MXBean * proxy.</p> * * <p>An {@code MXBeanMappingFactory} must return an {@code MXBeanMapping} * for any Java type that appears in the MXBeans that the factory is being * used for.  Usually it does that by handling any custom types, and * forwarding everything else to the {@linkplain #DEFAULT default mapping * factory}.</p> * * <p>Consider the {@code MyLinkedList} example from the {@link MXBeanMapping} * documentation.  If we are unable to change the {@code MyLinkedList} class * to add an {@link MXBeanMappingClass} annotation, we could achieve the same * effect by defining {@code MyLinkedListMappingFactory} as follows:</p> * * <pre> * public class MyLinkedListMappingFactory extends MXBeanMappingFactory { *     public MyLinkedListMappingFactory() {} * *     public MXBeanMapping mappingForType(Type t, MXBeanMappingFactory f) *     throws OpenDataException { *         if (t == MyLinkedList.class) *             return new MyLinkedListMapping(t); *         else *             return MXBeanMappingFactory.DEFAULT.mappingForType(t, f); *     } * } * </pre> * * <p>The mapping factory handles only the {@code MyLinkedList} class. * Every other type is forwarded to the default mapping factory. * This includes types such as {@code MyLinkedList[]} and * {@code List<MyLinkedList>}; the default mapping factory will recursively * invoke {@code MyLinkedListMappingFactory} to map the contained * {@code MyLinkedList} type.</p> * * <p>Once we have defined {@code MyLinkedListMappingFactory}, we can use * it in an MXBean interface like this:</p> * * <pre> * {@literal @MXBeanMappingFactoryClass}(MyLinkedListMappingFactory.class) * public interface SomethingMXBean { *     public MyLinkedList getSomething(); * } * </pre> * * <p>Alternatively we can annotate the package that {@code SomethingMXBean} * appears in, or we can supply the factory to a {@link * javax.management.StandardMBean StandardMBean} constructor or MXBean * proxy.</p> * * @see <a href="../MXBean.html#custom">MXBean specification, section * "Custom MXBean type mappings"</a> */public abstract class MXBeanMappingFactory {    /**     * <p>Construct an instance of this class.</p>     */    protected MXBeanMappingFactory() {}     /**     * <p>Mapping factory that applies the default rules for MXBean     * mappings, as described in the <a     * href="../MXBean.html#MXBean-spec">MXBean specification</a>.</p>     */    public static final MXBeanMappingFactory DEFAULT =            new DefaultMXBeanMappingFactory();     /**     * <p>Return the mapping for the given Java type.  Typically, a     * mapping factory will return mappings for types it handles, and     * forward other types to another mapping factory, most often     * the {@linkplain #DEFAULT default one}.</p>     * @param t the Java type to be mapped.     * @param f the original mapping factory that was consulted to do     * the mapping.  A mapping factory should pass this parameter intact     * if it forwards a type to another mapping factory.  In the example,     * this is how {@code MyLinkedListMappingFactory} works for types     * like {@code MyLinkedList[]} and {@code List<MyLinkedList>}.     * @return the mapping for the given type.     * @throws OpenDataException if this type cannot be mapped.  This     * exception is appropriate if the factory is supposed to handle     * all types of this sort (for example, all linked lists), but     * cannot handle this particular type.     */    public abstract MXBeanMapping mappingForType(Type t, MXBeanMappingFactory f)    throws OpenDataException;}