1. /*

  2.  * @(#)MBeanInstantiator.java	1.25 03/12/19

  3.  * 

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package com.sun.jmx.mbeanserver;

  9. 

  10. import javax.management.*; 

  11. import java.io.ObjectInputStream;

  12. 

  13. /**

  14.  * Contains methods for instantiating objects, finding the class given

  15.  * its name and using different class loaders, deserializing objects

  16.  * in the context of a given class loader.

  17.  *

  18.  * @since 1.5

  19.  * @since.unbundled JMX RI 1.2

  20.  */

  21. public interface MBeanInstantiator {

  22. 

  23.     /** 

  24.      * This methods tests if the MBean class makes it possible to 

  25.      * instantiate an MBean of this class in the MBeanServer.

  26.      * e.g. it must have a public constructor, be a concrete class...

  27.      */    

  28.     public void testCreation(Class c) throws NotCompliantMBeanException;

  29. 

  30.     /**

  31.      * Loads the class with the specified name using this object's 

  32.      * Default Loader Repository. 

  33.      **/

  34.     public Class findClassWithDefaultLoaderRepository(String className) 

  35. 	throws ReflectionException;

  36. 

  37. 

  38.     /**

  39.      * Return the Default Loader Repository used by this instantiator object.

  40.      **/

  41.     public ModifiableClassLoaderRepository getClassLoaderRepository();

  42. 

  43.     /**

  44.      * Gets the class for the specified class name using the MBean 

  45.      * Interceptor's classloader

  46.      */

  47.     public Class findClass(String className, ClassLoader loader) 

  48. 	throws ReflectionException;

  49. 

  50.     /**

  51.      * Gets the class for the specified class name using the specified 

  52.      * class loader

  53.      */

  54.     public Class findClass(String className, ObjectName loaderName) 

  55.         throws ReflectionException, InstanceNotFoundException ;

  56. 

  57.     /**

  58.      * Return an array of Class corresponding to the given signature, using

  59.      * the specified class loader.

  60.      */

  61.     public Class[] findSignatureClasses(String signature[],

  62. 					ClassLoader loader)

  63. 	throws ReflectionException;

  64.     /**

  65.      * De-serializes a byte array in the context of a classloader.

  66.      *

  67.      * @param loader the classloader to use for de-serialization

  68.      * @param data The byte array to be de-sererialized.

  69.      *

  70.      * @return  The de-serialized object stream.

  71.      *

  72.      * @exception OperationsException Any of the usual Input/Output related

  73.      * exceptions.

  74.      */

  75.     public ObjectInputStream deserialize(ClassLoader loader, byte[] data)

  76. 	throws OperationsException;

  77. 

  78.     /**

  79.      * De-serializes a byte array in the context of a given MBean class loader.

  80.      * <P>The class loader is the one that loaded the class with name

  81.      * "className".

  82.      * <P>The name of the class loader to be used for loading the specified

  83.      * class is specified. If null, a default one has to be provided (for a

  84.      * MBean Server, its own class loader will be used).

  85.      *

  86.      * @param className The name of the class whose class loader should 

  87.      *  be used for the de-serialization.

  88.      * @param data The byte array to be de-sererialized.

  89.      * @param loaderName The name of the class loader to be used for loading

  90.      * the specified class. If null, a default one has to be provided (for a

  91.      * MBean Server, its own class loader will be used).

  92.      *

  93.      * @return  The de-serialized object stream.

  94.      *

  95.      * @exception InstanceNotFoundException The specified class loader MBean is

  96.      * not found.          

  97.      * @exception OperationsException Any of the usual Input/Output related

  98.      * exceptions.

  99.      * @exception ReflectionException The specified class could not be loaded

  100.      * by the specified class loader.

  101.      */

  102.     public ObjectInputStream deserialize(String className,

  103. 					 ObjectName loaderName,

  104. 					 byte[] data,

  105. 					 ClassLoader loader)

  106. 	throws InstanceNotFoundException,

  107. 	       OperationsException,

  108. 	       ReflectionException;

  109. 

  110.     /**

  111.      * Instantiates an object using the list of all class loaders registered

  112.      * in the MBean Interceptor

  113.      * (using its {@link javax.management.loading.ClassLoaderRepository}).

  114.      * <P>The object's class should have a public constructor.

  115.      * <P>It returns a reference to the newly created object.

  116.      * <P>The newly created object is not registered in the MBean Interceptor.

  117.      *

  118.      * @param className The class name of the object to be instantiated.    

  119.      *

  120.      * @return The newly instantiated object.    

  121.      *

  122.      * @exception ReflectionException Wraps a

  123.      * <CODE>java.lang.ClassNotFoundException</CODE> or the

  124.      * <CODE>java.lang.Exception</CODE> that occurred when trying to invoke the

  125.      * object's constructor.

  126.      * @exception MBeanException The constructor of the object has thrown an

  127.      * exception

  128.      * @exception RuntimeOperationsException Wraps a

  129.      * <CODE>java.lang.IllegalArgumentException</CODE>: the className passed in

  130.      * parameter is null.

  131.      */

  132.     public Object instantiate(String className)

  133. 	throws ReflectionException,

  134. 	       MBeanException;

  135. 

  136.     /**

  137.      * Instantiates an object using the class Loader specified by its

  138.      * <CODE>ObjectName</CODE>.

  139.      * <P>If the loader name is null, a default one has to be provided (for a

  140.      * MBean Server, the ClassLoader that loaded it will be used).

  141.      * <P>The object's class should have a public constructor.

  142.      * <P>It returns a reference to the newly created object.

  143.      * <P>The newly created object is not registered in the MBean Interceptor.

  144.      *

  145.      * @param className The class name of the MBean to be instantiated.    

  146.      * @param loaderName The object name of the class loader to be used.

  147.      *

  148.      * @return The newly instantiated object.    

  149.      *

  150.      * @exception ReflectionException Wraps a

  151.      * <CODE>java.lang.ClassNotFoundException</CODE> or the

  152.      * <CODE>java.lang.Exception</CODE> that occurred when trying to invoke the

  153.      * object's constructor.

  154.      * @exception MBeanException The constructor of the object has thrown an

  155.      * exception.

  156.      * @exception InstanceNotFoundException The specified class loader is not

  157.      * registered in the MBeanServerInterceptor.

  158.      * @exception RuntimeOperationsException Wraps a

  159.      * <CODE>java.lang.IllegalArgumentException</CODE>: the className passed in

  160.      * parameter is null.

  161.      */

  162.     public Object instantiate(String className, ObjectName loaderName, ClassLoader loader) 

  163.         throws ReflectionException,

  164. 	       MBeanException,

  165. 	       InstanceNotFoundException;

  166. 

  167.     /**

  168.      * Instantiates an object using the list of all class loaders registered

  169.      * in the MBean server

  170.      * (using its {@link javax.management.loading.ClassLoaderRepository}).

  171.      * <P>The object's class should have a public constructor.

  172.      * <P>The call returns a reference to the newly created object.

  173.      * <P>The newly created object is not registered in the MBean Interceptor.

  174.      *

  175.      * @param className The class name of the object to be instantiated.

  176.      * @param params An array containing the parameters of the constructor to

  177.      * be invoked.

  178.      * @param signature An array containing the signature of the constructor to

  179.      * be invoked.     

  180.      *

  181.      * @return The newly instantiated object.    

  182.      *

  183.      * @exception ReflectionException Wraps a

  184.      * <CODE>java.lang.ClassNotFoundException</CODE> or the

  185.      * <CODE>java.lang.Exception</CODE> that occurred when trying to invoke the

  186.      * object's constructor.  

  187.      * @exception MBeanException The constructor of the object has thrown an

  188.      * exception

  189.      * @exception RuntimeOperationsException Wraps a

  190.      * <CODE>java.lang.IllegalArgumentException</CODE>: the className passed in

  191.      * parameter is null.

  192.      */    

  193.     public Object instantiate(String className,

  194. 			      Object params[],

  195. 			      String signature[],

  196. 			      ClassLoader loader) 

  197.         throws ReflectionException,

  198. 	       MBeanException ; 

  199. 

  200. 

  201.     /**

  202.      * Instantiates an object. The class loader to be used is identified by its

  203.      * object name.

  204.      * <P>If the object name of the loader is null, a default has to be

  205.      * provided (for example, for a MBean Server, the ClassLoader that loaded

  206.      * it will be used).

  207.      * <P>The object's class should have a public constructor.

  208.      * <P>The call returns a reference to the newly created object.

  209.      * <P>The newly created object is not registered in the MBean server.

  210.      *

  211.      * @param className The class name of the object to be instantiated.

  212.      * @param params An array containing the parameters of the constructor to

  213.      * be invoked.

  214.      * @param signature An array containing the signature of the constructor to

  215.      * be invoked.     

  216.      * @param loaderName The object name of the class loader to be used.

  217.      *

  218.      * @return The newly instantiated object.    

  219.      *

  220.      * @exception ReflectionException Wraps a

  221.      * <CODE>java.lang.ClassNotFoundException</CODE> or the

  222.      * <CODE>java.lang.Exception</CODE> that occurred when trying to invoke the

  223.      * object's constructor.  

  224.      * @exception MBeanException The constructor of the object has thrown an

  225.      * exception

  226.      * @exception InstanceNotFoundException The specified class loader is not

  227.      * registered in the MBean Interceptor. 

  228.      * @exception RuntimeOperationsException Wraps a

  229.      * <CODE>java.lang.IllegalArgumentException</CODE>: the className passed in

  230.      * parameter is null.

  231.      */    

  232.     public Object instantiate(String className,

  233. 			      ObjectName loaderName,

  234. 			      Object params[],

  235. 			      String signature[],

  236. 			      ClassLoader loader) 

  237.         throws ReflectionException,

  238. 	       MBeanException,

  239. 	       InstanceNotFoundException;

  240. 

  241. 

  242.     /**

  243.      * Instantiates an object given its class, using its empty constructor.

  244.      * The call returns a reference to the newly created object.

  245.      */

  246.     public Object instantiate(Class theClass) throws ReflectionException, MBeanException;

  247. 

  248. 

  249.    /**

  250.      * Instantiates an object given its class, the parameters and signature of its constructor

  251.      * The call returns a reference to the newly created object.

  252.      */

  253.     public Object instantiate(Class theClass, Object params[], String signature[], ClassLoader loader) throws ReflectionException, MBeanException;

  254. }