1. /*

  2.  * @(#)MBeanServerConnection.java	1.21 04/02/10

  3.  * 

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

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

  6.  */

  7. 

  8. package javax.management;

  9. 

  10. 

  11. // java import

  12. import java.io.IOException;

  13. import java.util.Set;

  14. 

  15. 

  16. /**

  17.  * This interface represents a way to talk to an MBean server, whether

  18.  * local or remote.  The {@link MBeanServer} interface, representing a

  19.  * local MBean server, extends this interface.

  20.  *

  21.  *

  22.  * @since 1.5

  23.  * @since.unbundled JMX 1.2

  24.  */

  25. public interface MBeanServerConnection {

  26.     /**

  27.      * <p>Instantiates and registers an MBean in the MBean server.  The

  28.      * MBean server will use its {@link

  29.      * javax.management.loading.ClassLoaderRepository Default Loader

  30.      * Repository} to load the class of the MBean.  An object name is

  31.      * associated to the MBean.	 If the object name given is null, the

  32.      * MBean must provide its own name by implementing the {@link

  33.      * javax.management.MBeanRegistration MBeanRegistration} interface

  34.      * and returning the name from the {@link

  35.      * MBeanRegistration#preRegister preRegister} method.</p>

  36.      *

  37.      * <p>This method is equivalent to {@link

  38.      * #createMBean(String,ObjectName,Object[],String[])

  39.      * createMBean(className, name, (Object[]) null, (String[])

  40.      * null)}.</p>

  41.      *

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

  43.      * @param name The object name of the MBean. May be null.	 

  44.      *

  45.      * @return An <CODE>ObjectInstance</CODE>, containing the

  46.      * <CODE>ObjectName</CODE> and the Java class name of the newly

  47.      * instantiated MBean.  If the contained <code>ObjectName</code>

  48.      * is <code>n</code>, the contained Java class name is

  49.      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

  50.      *

  51.      * @exception ReflectionException Wraps a

  52.      * <CODE>java.lang.ClassNotFoundException</CODE> or a

  53.      * <CODE><CODE>java.lang.Exception</CODE></CODE> that occurred

  54.      * when trying to invoke the MBean's constructor.

  55.      * @exception InstanceAlreadyExistsException The MBean is already

  56.      * under the control of the MBean server.

  57.      * @exception MBeanRegistrationException The

  58.      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>

  59.      * interface) method of the MBean has thrown an exception. The

  60.      * MBean will not be registered.

  61.      * @exception MBeanException The constructor of the MBean has

  62.      * thrown an exception

  63.      * @exception NotCompliantMBeanException This class is not a JMX

  64.      * compliant MBean

  65.      * @exception RuntimeOperationsException Wraps a

  66.      * <CODE>java.lang.IllegalArgumentException</CODE>: The className

  67.      * passed in parameter is null, the <CODE>ObjectName</CODE> passed

  68.      * in parameter contains a pattern or no <CODE>ObjectName</CODE>

  69.      * is specified for the MBean.

  70.      * @exception IOException A communication problem occurred when

  71.      * talking to the MBean server.

  72.      *

  73.      */

  74.     public ObjectInstance createMBean(String className, ObjectName name)

  75. 	    throws ReflectionException, InstanceAlreadyExistsException,

  76. 		   MBeanRegistrationException, MBeanException,

  77. 		   NotCompliantMBeanException, IOException;

  78. 

  79.     /**

  80.      * <p>Instantiates and registers an MBean in the MBean server.  The

  81.      * class loader to be used is identified by its object name. An

  82.      * object name is associated to the MBean. If the object name of

  83.      * the loader is null, the ClassLoader that loaded the MBean

  84.      * server will be used.  If the MBean's object name given is null,

  85.      * the MBean must provide its own name by implementing the {@link

  86.      * javax.management.MBeanRegistration MBeanRegistration} interface

  87.      * and returning the name from the {@link

  88.      * MBeanRegistration#preRegister preRegister} method.</p>

  89.      *

  90.      * <p>This method is equivalent to {@link

  91.      * #createMBean(String,ObjectName,ObjectName,Object[],String[])

  92.      * createMBean(className, name, loaderName, (Object[]) null,

  93.      * (String[]) null)}.</p>

  94.      *

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

  96.      * @param name The object name of the MBean. May be null.	 

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

  98.      *

  99.      * @return An <CODE>ObjectInstance</CODE>, containing the

  100.      * <CODE>ObjectName</CODE> and the Java class name of the newly

  101.      * instantiated MBean.  If the contained <code>ObjectName</code>

  102.      * is <code>n</code>, the contained Java class name is

  103.      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

  104.      *

  105.      * @exception ReflectionException Wraps a

  106.      * <CODE>java.lang.ClassNotFoundException</CODE> or a

  107.      * <CODE>java.lang.Exception</CODE> that occurred when trying to

  108.      * invoke the MBean's constructor.

  109.      * @exception InstanceAlreadyExistsException The MBean is already

  110.      * under the control of the MBean server.

  111.      * @exception MBeanRegistrationException The

  112.      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>

  113.      * interface) method of the MBean has thrown an exception. The

  114.      * MBean will not be registered.

  115.      * @exception MBeanException The constructor of the MBean has

  116.      * thrown an exception

  117.      * @exception NotCompliantMBeanException This class is not a JMX

  118.      * compliant MBean

  119.      * @exception InstanceNotFoundException The specified class loader

  120.      * is not registered in the MBean server.

  121.      * @exception RuntimeOperationsException Wraps a

  122.      * <CODE>java.lang.IllegalArgumentException</CODE>: The className

  123.      * passed in parameter is null, the <CODE>ObjectName</CODE> passed

  124.      * in parameter contains a pattern or no <CODE>ObjectName</CODE>

  125.      * is specified for the MBean.

  126.      * @exception IOException A communication problem occurred when

  127.      * talking to the MBean server.

  128.      */

  129.     public ObjectInstance createMBean(String className, ObjectName name,

  130. 				      ObjectName loaderName) 

  131. 	    throws ReflectionException, InstanceAlreadyExistsException,

  132. 		   MBeanRegistrationException, MBeanException,

  133. 		   NotCompliantMBeanException, InstanceNotFoundException,

  134. 		   IOException;

  135. 

  136. 

  137.     /**

  138.      * Instantiates and registers an MBean in the MBean server.  The

  139.      * MBean server will use its {@link

  140.      * javax.management.loading.ClassLoaderRepository Default Loader

  141.      * Repository} to load the class of the MBean.  An object name is

  142.      * associated to the MBean.  If the object name given is null, the

  143.      * MBean must provide its own name by implementing the {@link

  144.      * javax.management.MBeanRegistration MBeanRegistration} interface

  145.      * and returning the name from the {@link

  146.      * MBeanRegistration#preRegister preRegister} method.

  147.      *

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

  149.      * @param name The object name of the MBean. May be null.

  150.      * @param params An array containing the parameters of the

  151.      * constructor to be invoked.

  152.      * @param signature An array containing the signature of the

  153.      * constructor to be invoked.

  154.      *

  155.      * @return An <CODE>ObjectInstance</CODE>, containing the

  156.      * <CODE>ObjectName</CODE> and the Java class name of the newly

  157.      * instantiated MBean.  If the contained <code>ObjectName</code>

  158.      * is <code>n</code>, the contained Java class name is

  159.      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

  160.      *

  161.      * @exception ReflectionException Wraps a

  162.      * <CODE>java.lang.ClassNotFoundException</CODE> or a

  163.      * <CODE>java.lang.Exception</CODE> that occurred when trying to

  164.      * invoke the MBean's constructor.

  165.      * @exception InstanceAlreadyExistsException The MBean is already

  166.      * under the control of the MBean server.

  167.      * @exception MBeanRegistrationException The

  168.      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>

  169.      * interface) method of the MBean has thrown an exception. The

  170.      * MBean will not be registered.

  171.      * @exception MBeanException The constructor of the MBean has

  172.      * thrown an exception

  173.      * @exception NotCompliantMBeanException This class is not a JMX

  174.      * compliant MBean

  175.      * @exception RuntimeOperationsException Wraps a

  176.      * <CODE>java.lang.IllegalArgumentException</CODE>: The className

  177.      * passed in parameter is null, the <CODE>ObjectName</CODE> passed

  178.      * in parameter contains a pattern or no <CODE>ObjectName</CODE>

  179.      * is specified for the MBean.

  180.      * @exception IOException A communication problem occurred when

  181.      * talking to the MBean server.

  182.      *

  183.      */

  184.     public ObjectInstance createMBean(String className, ObjectName name,

  185. 				      Object params[], String signature[]) 

  186. 	    throws ReflectionException, InstanceAlreadyExistsException,

  187. 	    	   MBeanRegistrationException, MBeanException,

  188. 	    	   NotCompliantMBeanException, IOException;

  189. 

  190.     /**

  191.      * Instantiates and registers an MBean in the MBean server.  The

  192.      * class loader to be used is identified by its object name. An

  193.      * object name is associated to the MBean. If the object name of

  194.      * the loader is not specified, the ClassLoader that loaded the

  195.      * MBean server will be used.  If the MBean object name given is

  196.      * null, the MBean must provide its own name by implementing the

  197.      * {@link javax.management.MBeanRegistration MBeanRegistration}

  198.      * interface and returning the name from the {@link

  199.      * MBeanRegistration#preRegister preRegister} method.

  200.      *

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

  202.      * @param name The object name of the MBean. May be null.

  203.      * @param params An array containing the parameters of the

  204.      * constructor to be invoked.

  205.      * @param signature An array containing the signature of the

  206.      * constructor to be invoked.

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

  208.      *

  209.      * @return An <CODE>ObjectInstance</CODE>, containing the

  210.      * <CODE>ObjectName</CODE> and the Java class name of the newly

  211.      * instantiated MBean.  If the contained <code>ObjectName</code>

  212.      * is <code>n</code>, the contained Java class name is

  213.      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

  214.      *

  215.      * @exception ReflectionException Wraps a

  216.      * <CODE>java.lang.ClassNotFoundException</CODE> or a

  217.      * <CODE>java.lang.Exception</CODE> that occurred when trying to

  218.      * invoke the MBean's constructor.

  219.      * @exception InstanceAlreadyExistsException The MBean is already

  220.      * under the control of the MBean server.

  221.      * @exception MBeanRegistrationException The

  222.      * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>

  223.      * interface) method of the MBean has thrown an exception. The

  224.      * MBean will not be registered.

  225.      * @exception MBeanException The constructor of the MBean has

  226.      * thrown an exception

  227.      * @exception NotCompliantMBeanException This class is not a JMX

  228.      * compliant MBean

  229.      * @exception InstanceNotFoundException The specified class loader

  230.      * is not registered in the MBean server.

  231.      * @exception RuntimeOperationsException Wraps a

  232.      * <CODE>java.lang.IllegalArgumentException</CODE>: The className

  233.      * passed in parameter is null, the <CODE>ObjectName</CODE> passed

  234.      * in parameter contains a pattern or no <CODE>ObjectName</CODE>

  235.      * is specified for the MBean.

  236.      * @exception IOException A communication problem occurred when

  237.      * talking to the MBean server.

  238.      *

  239.      */

  240.     public ObjectInstance createMBean(String className, ObjectName name,

  241. 				      ObjectName loaderName, Object params[],

  242. 				      String signature[]) 

  243. 	    throws ReflectionException, InstanceAlreadyExistsException,

  244. 	    	   MBeanRegistrationException, MBeanException,

  245. 	    	   NotCompliantMBeanException, InstanceNotFoundException,

  246. 	    	   IOException;

  247. 

  248.     /**

  249.      * Unregisters an MBean from the MBean server. The MBean is

  250.      * identified by its object name. Once the method has been

  251.      * invoked, the MBean may no longer be accessed by its object

  252.      * name.

  253.      *

  254.      * @param name The object name of the MBean to be unregistered.

  255.      *

  256.      * @exception InstanceNotFoundException The MBean specified is not

  257.      * registered in the MBean server.

  258.      * @exception MBeanRegistrationException The preDeregister

  259.      * ((<CODE>MBeanRegistration</CODE> interface) method of the MBean

  260.      * has thrown an exception.

  261.      * @exception RuntimeOperationsException Wraps a

  262.      * <CODE>java.lang.IllegalArgumentException</CODE>: The object

  263.      * name in parameter is null or the MBean you are when trying to

  264.      * unregister is the {@link javax.management.MBeanServerDelegate

  265.      * MBeanServerDelegate} MBean.

  266.      * @exception IOException A communication problem occurred when

  267.      * talking to the MBean server.

  268.      *

  269.      */

  270.     public void unregisterMBean(ObjectName name)

  271. 	    throws InstanceNotFoundException, MBeanRegistrationException,

  272. 	    	   IOException;

  273. 

  274.     /**

  275.      * Gets the <CODE>ObjectInstance</CODE> for a given MBean

  276.      * registered with the MBean server.

  277.      *

  278.      * @param name The object name of the MBean.

  279.      *

  280.      * @return The <CODE>ObjectInstance</CODE> associated with the MBean

  281.      * specified by <VAR>name</VAR>.  The contained <code>ObjectName</code>

  282.      * is <code>name</code> and the contained class name is

  283.      * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>.

  284.      *

  285.      * @exception InstanceNotFoundException The MBean specified is not

  286.      * registered in the MBean server.

  287.      * @exception IOException A communication problem occurred when

  288.      * talking to the MBean server.

  289.      */

  290.     public ObjectInstance getObjectInstance(ObjectName name)

  291. 	    throws InstanceNotFoundException, IOException;

  292. 

  293.     /**

  294.      * Gets MBeans controlled by the MBean server. This method allows

  295.      * any of the following to be obtained: All MBeans, a set of

  296.      * MBeans specified by pattern matching on the

  297.      * <CODE>ObjectName</CODE> and/or a Query expression, a specific

  298.      * MBean. When the object name is null or no domain and key

  299.      * properties are specified, all objects are to be selected (and

  300.      * filtered if a query is specified). It returns the set of

  301.      * <CODE>ObjectInstance</CODE> objects (containing the

  302.      * <CODE>ObjectName</CODE> and the Java Class name) for the

  303.      * selected MBeans.

  304.      *

  305.      * @param name The object name pattern identifying the MBeans to

  306.      * be retrieved. If null or no domain and key properties are

  307.      * specified, all the MBeans registered will be retrieved.

  308.      * @param query The query expression to be applied for selecting

  309.      * MBeans. If null no query expression will be applied for

  310.      * selecting MBeans.

  311.      *

  312.      * @return A set containing the <CODE>ObjectInstance</CODE>

  313.      * objects for the selected MBeans.  If no MBean satisfies the

  314.      * query an empty list is returned.

  315.      *

  316.      * @exception IOException A communication problem occurred when

  317.      * talking to the MBean server.

  318.      */

  319.     public Set queryMBeans(ObjectName name, QueryExp query)

  320. 	    throws IOException;

  321. 

  322.     /**

  323.      * Gets the names of MBeans controlled by the MBean server. This

  324.      * method enables any of the following to be obtained: The names

  325.      * of all MBeans, the names of a set of MBeans specified by

  326.      * pattern matching on the <CODE>ObjectName</CODE> and/or a Query

  327.      * expression, a specific MBean name (equivalent to testing

  328.      * whether an MBean is registered). When the object name is null

  329.      * or no domain and key properties are specified, all objects are

  330.      * selected (and filtered if a query is specified). It returns the

  331.      * set of ObjectNames for the MBeans selected.

  332.      *

  333.      * @param name The object name pattern identifying the MBean names

  334.      * to be retrieved. If null or no domain and key properties are

  335.      * specified, the name of all registered MBeans will be retrieved.

  336.      * @param query The query expression to be applied for selecting

  337.      * MBeans. If null no query expression will be applied for

  338.      * selecting MBeans.

  339.      *

  340.      * @return A set containing the ObjectNames for the MBeans

  341.      * selected.  If no MBean satisfies the query, an empty list is

  342.      * returned.

  343.      *

  344.      * @exception IOException A communication problem occurred when

  345.      * talking to the MBean server.

  346.      */

  347.     public Set queryNames(ObjectName name, QueryExp query)

  348. 	    throws IOException;

  349. 

  350. 

  351. 

  352.     /**

  353.      * Checks whether an MBean, identified by its object name, is

  354.      * already registered with the MBean server.

  355.      *

  356.      * @param name The object name of the MBean to be checked.

  357.      *

  358.      * @return True if the MBean is already registered in the MBean

  359.      * server, false otherwise.

  360.      *

  361.      * @exception RuntimeOperationsException Wraps a

  362.      * <CODE>java.lang.IllegalArgumentException</CODE>: The object

  363.      * name in parameter is null.

  364.      * @exception IOException A communication problem occurred when

  365.      * talking to the MBean server.

  366.      */

  367.     public boolean isRegistered(ObjectName name)

  368. 	    throws IOException;

  369. 

  370. 

  371.     /**

  372.      * Returns the number of MBeans registered in the MBean server.

  373.      *

  374.      * @return the number of MBeans registered.

  375.      *

  376.      * @exception IOException A communication problem occurred when

  377.      * talking to the MBean server.

  378.      */

  379.     public Integer getMBeanCount()

  380. 	    throws IOException;

  381. 

  382.     /**

  383.      * Gets the value of a specific attribute of a named MBean. The MBean

  384.      * is identified by its object name.

  385.      *

  386.      * @param name The object name of the MBean from which the

  387.      * attribute is to be retrieved.

  388.      * @param attribute A String specifying the name of the attribute

  389.      * to be retrieved.

  390.      *

  391.      * @return	The value of the retrieved attribute.

  392.      *

  393.      * @exception AttributeNotFoundException The attribute specified

  394.      * is not accessible in the MBean.

  395.      * @exception MBeanException Wraps an exception thrown by the

  396.      * MBean's getter.

  397.      * @exception InstanceNotFoundException The MBean specified is not

  398.      * registered in the MBean server.

  399.      * @exception ReflectionException Wraps a

  400.      * <CODE>java.lang.Exception</CODE> thrown when trying to invoke

  401.      * the setter.

  402.      * @exception RuntimeOperationsException Wraps a

  403.      * <CODE>java.lang.IllegalArgumentException</CODE>: The object

  404.      * name in parameter is null or the attribute in parameter is

  405.      * null.

  406.      * @exception IOException A communication problem occurred when

  407.      * talking to the MBean server.

  408.      *

  409.      * @see #setAttribute

  410.      */

  411.     public Object getAttribute(ObjectName name, String attribute)

  412. 	    throws MBeanException, AttributeNotFoundException,

  413. 	    	   InstanceNotFoundException, ReflectionException,

  414. 	    	   IOException;

  415. 

  416. 

  417.     /**

  418.      * Enables the values of several attributes of a named MBean. The MBean

  419.      * is identified by its object name.

  420.      *

  421.      * @param name The object name of the MBean from which the

  422.      * attributes are retrieved.

  423.      * @param attributes A list of the attributes to be retrieved.

  424.      *

  425.      * @return The list of the retrieved attributes.

  426.      *

  427.      * @exception InstanceNotFoundException The MBean specified is not

  428.      * registered in the MBean server.

  429.      * @exception ReflectionException An exception occurred when

  430.      * trying to invoke the getAttributes method of a Dynamic MBean.

  431.      * @exception RuntimeOperationsException Wrap a

  432.      * <CODE>java.lang.IllegalArgumentException</CODE>: The object

  433.      * name in parameter is null or attributes in parameter is null.

  434.      * @exception IOException A communication problem occurred when

  435.      * talking to the MBean server.

  436.      *

  437.      * @see #setAttributes

  438.      */

  439.     public AttributeList getAttributes(ObjectName name, String[] attributes)

  440. 	    throws InstanceNotFoundException, ReflectionException,

  441. 		   IOException;

  442. 

  443.     /**

  444.      * Sets the value of a specific attribute of a named MBean. The MBean

  445.      * is identified by its object name.

  446.      *

  447.      * @param name The name of the MBean within which the attribute is

  448.      * to be set.

  449.      * @param attribute The identification of the attribute to be set

  450.      * and the value it is to be set to.

  451.      *

  452.      * @exception InstanceNotFoundException The MBean specified is not

  453.      * registered in the MBean server.

  454.      * @exception AttributeNotFoundException The attribute specified

  455.      * is not accessible in the MBean.

  456.      * @exception InvalidAttributeValueException The value specified

  457.      * for the attribute is not valid.

  458.      * @exception MBeanException Wraps an exception thrown by the

  459.      * MBean's setter.

  460.      * @exception ReflectionException Wraps a

  461.      * <CODE>java.lang.Exception</CODE> thrown when trying to invoke

  462.      * the setter.

  463.      * @exception RuntimeOperationsException Wraps a

  464.      * <CODE>java.lang.IllegalArgumentException</CODE>: The object

  465.      * name in parameter is null or the attribute in parameter is

  466.      * null.

  467.      * @exception IOException A communication problem occurred when

  468.      * talking to the MBean server.

  469.      *

  470.      * @see #getAttribute

  471.      */

  472.     public void setAttribute(ObjectName name, Attribute attribute)

  473. 	    throws InstanceNotFoundException, AttributeNotFoundException,

  474. 		   InvalidAttributeValueException, MBeanException, 

  475. 		   ReflectionException, IOException;

  476. 

  477. 

  478. 

  479.     /**

  480.      * Sets the values of several attributes of a named MBean. The MBean is

  481.      * identified by its object name.

  482.      *

  483.      * @param name The object name of the MBean within which the

  484.      * attributes are to be set.

  485.      * @param attributes A list of attributes: The identification of

  486.      * the attributes to be set and the values they are to be set to.

  487.      *

  488.      * @return The list of attributes that were set, with their new

  489.      * values.

  490.      *

  491.      * @exception InstanceNotFoundException The MBean specified is not

  492.      * registered in the MBean server.

  493.      * @exception ReflectionException An exception occurred when

  494.      * trying to invoke the getAttributes method of a Dynamic MBean.

  495.      * @exception RuntimeOperationsException Wraps a

  496.      * <CODE>java.lang.IllegalArgumentException</CODE>: The object

  497.      * name in parameter is null or attributes in parameter is null.

  498.      * @exception IOException A communication problem occurred when

  499.      * talking to the MBean server.

  500.      *

  501.      * @see #getAttributes

  502.      */

  503.     public AttributeList setAttributes(ObjectName name,

  504. 				       AttributeList attributes)

  505. 	throws InstanceNotFoundException, ReflectionException, IOException;

  506. 

  507.     /**

  508.      * Invokes an operation on an MBean.

  509.      *

  510.      * @param name The object name of the MBean on which the method is

  511.      * to be invoked.

  512.      * @param operationName The name of the operation to be invoked.

  513.      * @param params An array containing the parameters to be set when

  514.      * the operation is invoked

  515.      * @param signature An array containing the signature of the

  516.      * operation. The class objects will be loaded using the same

  517.      * class loader as the one used for loading the MBean on which the

  518.      * operation was invoked.

  519.      *

  520.      * @return The object returned by the operation, which represents

  521.      * the result of invoking the operation on the MBean specified.

  522.      *

  523.      * @exception InstanceNotFoundException The MBean specified is not

  524.      * registered in the MBean server.

  525.      * @exception MBeanException Wraps an exception thrown by the

  526.      * MBean's invoked method.

  527.      * @exception ReflectionException Wraps a

  528.      * <CODE>java.lang.Exception</CODE> thrown while trying to invoke

  529.      * the method.

  530.      * @exception IOException A communication problem occurred when

  531.      * talking to the MBean server.

  532.      *

  533.      */

  534.     public Object invoke(ObjectName name, String operationName,

  535. 			 Object params[], String signature[])

  536. 	    throws InstanceNotFoundException, MBeanException,

  537. 		   ReflectionException, IOException;

  538.  

  539. 

  540.   

  541.     /**

  542.      * Returns the default domain used for naming the MBean.

  543.      * The default domain name is used as the domain part in the ObjectName

  544.      * of MBeans if no domain is specified by the user.

  545.      *

  546.      * @return the default domain.

  547.      *

  548.      * @exception IOException A communication problem occurred when

  549.      * talking to the MBean server.

  550.      */

  551.     public String getDefaultDomain()

  552. 	    throws IOException;

  553. 

  554.     /**

  555.      * <p>Returns the list of domains in which any MBean is currently

  556.      * registered.  A string is in the returned array if and only if

  557.      * there is at least one MBean registered with an ObjectName whose

  558.      * {@link ObjectName#getDomain() getDomain()} is equal to that

  559.      * string.  The order of strings within the returned array is

  560.      * not defined.</p>

  561.      *

  562.      * @return the list of domains.

  563.      *

  564.      * @exception IOException A communication problem occurred when

  565.      * talking to the MBean server.

  566.      *

  567.      * @since.unbundled JMX 1.2

  568.      */

  569.     public String[] getDomains()

  570. 	    throws IOException;

  571. 

  572.     /**

  573.      * <p>Adds a listener to a registered MBean.</p>

  574.      *

  575.      * <P> A notification emitted by an MBean will be forwarded by the

  576.      * MBeanServer to the listener.  If the source of the notification

  577.      * is a reference to an MBean object, the MBean server will replace it

  578.      * by that MBean's ObjectName.  Otherwise the source is unchanged.

  579.      *

  580.      * @param name The name of the MBean on which the listener should

  581.      * be added.

  582.      * @param listener The listener object which will handle the

  583.      * notifications emitted by the registered MBean.

  584.      * @param filter The filter object. If filter is null, no

  585.      * filtering will be performed before handling notifications.

  586.      * @param handback The context to be sent to the listener when a

  587.      * notification is emitted.

  588.      *

  589.      * @exception InstanceNotFoundException The MBean name provided

  590.      * does not match any of the registered MBeans.

  591.      * @exception IOException A communication problem occurred when

  592.      * talking to the MBean server.

  593.      *

  594.      * @see #removeNotificationListener(ObjectName, NotificationListener)

  595.      * @see #removeNotificationListener(ObjectName, NotificationListener,

  596.      * NotificationFilter, Object)

  597.      */

  598.     public void addNotificationListener(ObjectName name,

  599. 					NotificationListener listener,

  600. 					NotificationFilter filter,

  601. 					Object handback)

  602. 	    throws InstanceNotFoundException, IOException;

  603. 

  604. 

  605.     /**

  606.      * <p>Adds a listener to a registered MBean.</p>

  607.      *

  608.      * <p>A notification emitted by an MBean will be forwarded by the

  609.      * MBeanServer to the listener.  If the source of the notification

  610.      * is a reference to an MBean object, the MBean server will

  611.      * replace it by that MBean's ObjectName.  Otherwise the source is

  612.      * unchanged.</p>

  613.      *

  614.      * <p>The listener object that receives notifications is the one

  615.      * that is registered with the given name at the time this method

  616.      * is called.  Even if it is subsequently unregistered, it will

  617.      * continue to receive notifications.</p>

  618.      *

  619.      * @param name The name of the MBean on which the listener should

  620.      * be added.

  621.      * @param listener The object name of the listener which will

  622.      * handle the notifications emitted by the registered MBean.

  623.      * @param filter The filter object. If filter is null, no

  624.      * filtering will be performed before handling notifications.

  625.      * @param handback The context to be sent to the listener when a

  626.      * notification is emitted.

  627.      *

  628.      * @exception InstanceNotFoundException The MBean name of the

  629.      * notification listener or of the notification broadcaster does

  630.      * not match any of the registered MBeans.

  631.      * @exception RuntimeOperationsException Wraps an {@link

  632.      * IllegalArgumentException}.  The MBean named by

  633.      * <code>listener</code> exists but does not implement the {@link

  634.      * NotificationListener} interface.

  635.      * @exception IOException A communication problem occurred when

  636.      * talking to the MBean server.

  637.      *

  638.      * @see #removeNotificationListener(ObjectName, ObjectName)

  639.      * @see #removeNotificationListener(ObjectName, ObjectName,

  640.      * NotificationFilter, Object)

  641.      */

  642.     public void addNotificationListener(ObjectName name,

  643. 					ObjectName listener,

  644. 					NotificationFilter filter,

  645. 					Object handback)

  646. 	    throws InstanceNotFoundException, IOException;

  647. 

  648. 

  649.     /**

  650.      * Removes a listener from a registered MBean.

  651.      *

  652.      * <P> If the listener is registered more than once, perhaps with

  653.      * different filters or callbacks, this method will remove all

  654.      * those registrations.

  655.      *

  656.      * @param name The name of the MBean on which the listener should

  657.      * be removed.

  658.      * @param listener The object name of the listener to be removed.

  659.      *

  660.      * @exception InstanceNotFoundException The MBean name provided

  661.      * does not match any of the registered MBeans.

  662.      * @exception ListenerNotFoundException The listener is not

  663.      * registered in the MBean.

  664.      * @exception IOException A communication problem occurred when

  665.      * talking to the MBean server.

  666.      *

  667.      * @see #addNotificationListener(ObjectName, ObjectName,

  668.      * NotificationFilter, Object)

  669.      */

  670.     public void removeNotificationListener(ObjectName name,

  671. 					   ObjectName listener) 

  672. 	throws InstanceNotFoundException, ListenerNotFoundException,

  673. 	       IOException;

  674. 

  675.     /**

  676.      * <p>Removes a listener from a registered MBean.</p>

  677.      *

  678.      * <p>The MBean must have a listener that exactly matches the

  679.      * given <code>listener</code>, <code>filter</code>, and

  680.      * <code>handback</code> parameters.  If there is more than one

  681.      * such listener, only one is removed.</p>

  682.      *

  683.      * <p>The <code>filter</code> and <code>handback</code> parameters

  684.      * may be null if and only if they are null in a listener to be

  685.      * removed.</p>

  686.      *

  687.      * @param name The name of the MBean on which the listener should

  688.      * be removed.

  689.      * @param listener A listener that was previously added to this

  690.      * MBean.

  691.      * @param filter The filter that was specified when the listener

  692.      * was added.

  693.      * @param handback The handback that was specified when the

  694.      * listener was added.

  695.      *

  696.      * @exception InstanceNotFoundException The MBean name provided

  697.      * does not match any of the registered MBeans.

  698.      * @exception ListenerNotFoundException The listener is not

  699.      * registered in the MBean, or it is not registered with the given

  700.      * filter and handback.

  701.      * @exception IOException A communication problem occurred when

  702.      * talking to the MBean server.

  703.      *

  704.      * @see #addNotificationListener(ObjectName, ObjectName,

  705.      * NotificationFilter, Object)

  706.      *

  707.      * @since.unbundled JMX 1.2

  708.      */

  709.     public void removeNotificationListener(ObjectName name,

  710. 					   ObjectName listener,

  711. 					   NotificationFilter filter,

  712. 					   Object handback)

  713. 	    throws InstanceNotFoundException, ListenerNotFoundException,

  714. 		   IOException;

  715. 

  716. 

  717.     /**

  718.      * <p>Removes a listener from a registered MBean.</p>

  719.      *

  720.      * <P> If the listener is registered more than once, perhaps with

  721.      * different filters or callbacks, this method will remove all

  722.      * those registrations.

  723.      *

  724.      * @param name The name of the MBean on which the listener should

  725.      * be removed.

  726.      * @param listener The object name of the listener to be removed.

  727.      *

  728.      * @exception InstanceNotFoundException The MBean name provided

  729.      * does not match any of the registered MBeans.

  730.      * @exception ListenerNotFoundException The listener is not

  731.      * registered in the MBean.

  732.      * @exception IOException A communication problem occurred when

  733.      * talking to the MBean server.

  734.      *

  735.      * @see #addNotificationListener(ObjectName, NotificationListener,

  736.      * NotificationFilter, Object)

  737.      */

  738.     public void removeNotificationListener(ObjectName name,

  739. 					   NotificationListener listener)

  740. 	    throws InstanceNotFoundException, ListenerNotFoundException,

  741. 		   IOException;

  742. 

  743.     /**

  744.      * <p>Removes a listener from a registered MBean.</p>

  745.      *

  746.      * <p>The MBean must have a listener that exactly matches the

  747.      * given <code>listener</code>, <code>filter</code>, and

  748.      * <code>handback</code> parameters.  If there is more than one

  749.      * such listener, only one is removed.</p>

  750.      *

  751.      * <p>The <code>filter</code> and <code>handback</code> parameters

  752.      * may be null if and only if they are null in a listener to be

  753.      * removed.</p>

  754.      *

  755.      * @param name The name of the MBean on which the listener should

  756.      * be removed.

  757.      * @param listener A listener that was previously added to this

  758.      * MBean.

  759.      * @param filter The filter that was specified when the listener

  760.      * was added.

  761.      * @param handback The handback that was specified when the

  762.      * listener was added.

  763.      *

  764.      * @exception InstanceNotFoundException The MBean name provided

  765.      * does not match any of the registered MBeans.

  766.      * @exception ListenerNotFoundException The listener is not

  767.      * registered in the MBean, or it is not registered with the given

  768.      * filter and handback.

  769.      * @exception IOException A communication problem occurred when

  770.      * talking to the MBean server.

  771.      *

  772.      * @see #addNotificationListener(ObjectName, NotificationListener,

  773.      * NotificationFilter, Object)

  774.      *

  775.      * @since.unbundled JMX 1.2

  776.      */

  777.     public void removeNotificationListener(ObjectName name,

  778. 					   NotificationListener listener,

  779. 					   NotificationFilter filter,

  780. 					   Object handback)

  781. 	    throws InstanceNotFoundException, ListenerNotFoundException,

  782. 		   IOException;

  783. 

  784.     /**

  785.      * This method discovers the attributes and operations that an

  786.      * MBean exposes for management.

  787.      *

  788.      * @param name The name of the MBean to analyze

  789.      *

  790.      * @return An instance of <CODE>MBeanInfo</CODE> allowing the

  791.      * retrieval of all attributes and operations of this MBean.

  792.      *

  793.      * @exception IntrospectionException An exception occurred during

  794.      * introspection.

  795.      * @exception InstanceNotFoundException The MBean specified was

  796.      * not found.

  797.      * @exception ReflectionException An exception occurred when

  798.      * trying to invoke the getMBeanInfo of a Dynamic MBean.

  799.      * @exception IOException A communication problem occurred when

  800.      * talking to the MBean server.

  801.      */

  802.     public MBeanInfo getMBeanInfo(ObjectName name)

  803. 	    throws InstanceNotFoundException, IntrospectionException,

  804. 	    	   ReflectionException, IOException;

  805. 

  806.  

  807.     /**

  808.      * <p>Returns true if the MBean specified is an instance of the

  809.      * specified class, false otherwise.</p>

  810.      *

  811.      * <p>If <code>name</code> does not name an MBean, this method

  812.      * throws {@link InstanceNotFoundException}.</p>

  813.      *

  814.      * <p>Otherwise, let<br>

  815.      * X be the MBean named by <code>name</code>,<br>

  816.      * L be the ClassLoader of X,<br>

  817.      * N be the class name in X's {@link MBeanInfo}.</p>

  818.      *

  819.      * <p>If N equals <code>className</code>, the result is true.</p>

  820.      *

  821.      * <p>Otherwise, if L successfully loads both N and

  822.      * <code>className</code>, and the second class is assignable from

  823.      * the first, the result is true.</p>

  824.      *

  825.      * <p>Otherwise, the result is false.</p>

  826.      * 

  827.      * @param name The <CODE>ObjectName</CODE> of the MBean.

  828.      * @param className The name of the class.

  829.      *

  830.      * @return true if the MBean specified is an instance of the

  831.      * specified class according to the rules above, false otherwise.

  832.      *

  833.      * @exception InstanceNotFoundException The MBean specified is not

  834.      * registered in the MBean server.

  835.      * @exception IOException A communication problem occurred when

  836.      * talking to the MBean server.

  837.      */

  838.     public boolean isInstanceOf(ObjectName name, String className)

  839. 	    throws InstanceNotFoundException, IOException;

  840. }