Java example source code file (MXBeanMappingFactory.java)

This example Java source code file (MXBeanMappingFactory.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

default, defaultmxbeanmappingfactory, mxbeanmappingfactory, opendataexception, reflection

The MXBeanMappingFactory.java Java example source code

/*
 * 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.

     */
    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>.

     */
    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;
}