rmiconnection.java

JAVA的一些源码 JAVA2 STANDARD EDITION DEVELOPMENT KIT 5.0

/*
 * @(#)RMIConnection.java	1.39 04/05/05
 * 
 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.management.remote.rmi;

// IO
import java.io.IOException;
import java.io.Serializable;
import java.io.InterruptedIOException;

// RMI
import java.rmi.Remote;
import java.rmi.MarshalledObject;

// JMX
import javax.management.AttributeList;
import javax.management.AttributeNotFoundException;
import javax.management.InstanceAlreadyExistsException;
import javax.management.InstanceNotFoundException;
import javax.management.IntrospectionException;
import javax.management.InvalidAttributeValueException;
import javax.management.ListenerNotFoundException;
import javax.management.MalformedObjectNameException;
import javax.management.MBeanException;
import javax.management.MBeanInfo;
import javax.management.MBeanRegistrationException;
import javax.management.MBeanServer;
import javax.management.MBeanServerConnection;
import javax.management.NotificationListener;
import javax.management.NotCompliantMBeanException;
import javax.management.ObjectInstance;
import javax.management.ObjectName;
import javax.management.ReflectionException;
import javax.management.RuntimeOperationsException;
import javax.management.loading.ClassLoaderRepository;

import javax.management.remote.NotificationResult;

// Util
import java.util.Set;

import javax.security.auth.Subject;

/** 
 * <p>RMI object used to forward an MBeanServer request from a client
 * to its MBeanServer implementation on the server side.  There is one
 * Remote object implementing this interface for each remote client
 * connected to an RMI connector.</p>
 *
 * <p>User code does not usually refer to this interface.  It is
 * specified as part of the public API so that different
 * implementations of that API will interoperate.</p>
 *
 * <p>To ensure that client parameters will be deserialized at the
 * server side with the correct classloader, client parameters such as
 * parameters used to invoke a method are wrapped in a {@link
 * MarshalledObject}.  An implementation of this interface must first
 * get the appropriate class loader for the operation and its target,
 * then deserialize the marshalled parameters with this classloader.
 * Except as noted, a parameter that is a
 * <code>MarshalledObject</code> or <code>MarshalledObject[]</code>
 * must not be null; the behavior is unspecified if it is.</p>
 *
 * <p>Class loading aspects are detailed in the companion document 
 * <em>JMX Remote API</em>, which completes this documentation.
 * It should be available as a PDF document in the same place as this 
 * Javadoc specification.</p>
 *
 * @since 1.5
 * @since.unbundled 1.0
 * <p>Most methods in this interface parallel methods in the {@link
 * MBeanServerConnection} interface.  Where an aspect of the behavior
 * of a method is not specified here, it is the same as in the
 * corresponding <code>MBeanServerConnection</code> method.
 */
public interface RMIConnection extends Remote {
    /**
     * <p>Returns the connection ID.  This string is different for
     * every open connection to a given RMI connector server.</p>
     *
     * @return the connection ID
     *
     * @see RMIConnector#connect RMIConnector.connect
     *
     * @throws IOException if a general communication exception occurred.
     */
    public String getConnectionId() throws IOException;

    /**
     * <p>Closes this connection.  On return from this method, the RMI
     * object implementing this interface is unexported, so further
     * remote calls to it will fail.</p>
     *
     * @throws IOException if the connection could not be closed,
     * or the Remote object could not be unexported, or there was a
     * communication failure when transmitting the remote close
     * request.
     */
    public void close() throws IOException;
    
    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#createMBean(String,
     * ObjectName)}.
     *
     * @param className The class name of the MBean to be instantiated.
     * @param name The object name of the MBean. May be null.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return An <code>ObjectInstance</code>, containing the
     * <code>ObjectName</code> and the Java class name of the newly
     * instantiated MBean.  If the contained <code>ObjectName</code>
     * is <code>n</code>, the contained Java class name is
     * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
     *
     * @throws ReflectionException Wraps a
     * <code>java.lang.ClassNotFoundException</code> or a
     * <code>java.lang.Exception</code> that occurred
     * when trying to invoke the MBean's constructor.
     * @throws InstanceAlreadyExistsException The MBean is already
     * under the control of the MBean server.
     * @throws MBeanRegistrationException The
     * <code>preRegister</code> (<code>MBeanRegistration</code>
     * interface) method of the MBean has thrown an exception. The
     * MBean will not be registered.
     * @throws MBeanException The constructor of the MBean has
     * thrown an exception.
     * @throws NotCompliantMBeanException This class is not a JMX
     * compliant MBean.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The className
     * passed in parameter is null, the <code>ObjectName</code> passed
     * in parameter contains a pattern or no <code>ObjectName</code>
     * is specified for the MBean.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance createMBean(String className,
                                      ObjectName name,
				      Subject delegationSubject)
	throws
	ReflectionException,
	InstanceAlreadyExistsException,
	MBeanRegistrationException, 
	MBeanException,
	NotCompliantMBeanException, 
	IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#createMBean(String,
     * ObjectName, ObjectName)}.
     *
     * @param className The class name of the MBean to be instantiated.
     * @param name The object name of the MBean. May be null.
     * @param loaderName The object name of the class loader to be used.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return An <code>ObjectInstance</code>, containing the
     * <code>ObjectName</code> and the Java class name of the newly
     * instantiated MBean.  If the contained <code>ObjectName</code>
     * is <code>n</code>, the contained Java class name is
     * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
     *
     * @throws ReflectionException Wraps a
     * <code>java.lang.ClassNotFoundException</code> or a
     * <code>java.lang.Exception</code> that occurred when trying to
     * invoke the MBean's constructor.
     * @throws InstanceAlreadyExistsException The MBean is already
     * under the control of the MBean server.
     * @throws MBeanRegistrationException The
     * <code>preRegister</code> (<code>MBeanRegistration</code>
     * interface) method of the MBean has thrown an exception. The
     * MBean will not be registered.
     * @throws MBeanException The constructor of the MBean has
     * thrown an exception.
     * @throws NotCompliantMBeanException This class is not a JMX
     * compliant MBean.
     * @throws InstanceNotFoundException The specified class loader
     * is not registered in the MBean server.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The className
     * passed in parameter is null, the <code>ObjectName</code> passed
     * in parameter contains a pattern or no <code>ObjectName</code>
     * is specified for the MBean.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance createMBean(String className,
                                      ObjectName name,
                                      ObjectName loaderName,
				      Subject delegationSubject)
	throws
	ReflectionException,
	InstanceAlreadyExistsException,
	MBeanRegistrationException,
	MBeanException,
	NotCompliantMBeanException,
	InstanceNotFoundException,
	IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#createMBean(String,
     * ObjectName, Object[], String[])}.  The <code>Object[]</code>
     * parameter is wrapped in a <code>MarshalledObject</code>.
     *
     * @param className The class name of the MBean to be instantiated.
     * @param name The object name of the MBean. May be null.
     * @param params An array containing the parameters of the
     * constructor to be invoked, encapsulated into a
     * <code>MarshalledObject</code>.  The encapsulated array can be
     * null, equivalent to an empty array.
     * @param signature An array containing the signature of the
     * constructor to be invoked.  Can be null, equivalent to an empty
     * array.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return An <code>ObjectInstance</code>, containing the
     * <code>ObjectName</code> and the Java class name of the newly
     * instantiated MBean.  If the contained <code>ObjectName</code>
     * is <code>n</code>, the contained Java class name is
     * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
     *
     * @throws ReflectionException Wraps a
     * <code>java.lang.ClassNotFoundException</code> or a
     * <code>java.lang.Exception</code> that occurred when trying to
     * invoke the MBean's constructor.
     * @throws InstanceAlreadyExistsException The MBean is already
     * under the control of the MBean server.
     * @throws MBeanRegistrationException The
     * <code>preRegister</code> (<code>MBeanRegistration</code>
     * interface) method of the MBean has thrown an exception. The
     * MBean will not be registered.
     * @throws MBeanException The constructor of the MBean has
     * thrown an exception.
     * @throws NotCompliantMBeanException This class is not a JMX
     * compliant MBean.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The className
     * passed in parameter is null, the <code>ObjectName</code> passed
     * in parameter contains a pattern, or no <code>ObjectName</code>
     * is specified for the MBean.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance createMBean(String className,
                                      ObjectName name,
                                      MarshalledObject params,
                                      String signature[],
				      Subject delegationSubject)
	throws
	ReflectionException,
	InstanceAlreadyExistsException,
	MBeanRegistrationException,
	MBeanException,
	NotCompliantMBeanException,