Back to index...

	/*
	* Copyright (c) 2003, 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 javax.management.remote;

	import java.io.IOException;
	import java.util.ArrayList;
	import java.util.List;
	import java.util.Map;

	import javax.management.MBeanNotificationInfo;
	import javax.management.MBeanRegistration;
	import javax.management.MBeanServer;
	import javax.management.Notification;
	import javax.management.NotificationBroadcasterSupport;
	import javax.management.ObjectName;

	/**
	* <p>Superclass of every connector server. A connector server is
	* attached to an MBean server. It listens for client connection
	* requests and creates a connection for each one.</p>
	*
	* <p>A connector server is associated with an MBean server either by
	* registering it in that MBean server, or by passing the MBean server
	* to its constructor.</p>
	*
	* <p>A connector server is inactive when created. It only starts
	* listening for client connections when the {@link #start() start}
	* method is called. A connector server stops listening for client
	* connections when the {@link #stop() stop} method is called or when
	* the connector server is unregistered from its MBean server.</p>
	*
	* <p>Stopping a connector server does not unregister it from its
	* MBean server. A connector server once stopped cannot be
	* restarted.</p>
	*
	* <p>Each time a client connection is made or broken, a notification
	* of class {@link JMXConnectionNotification} is emitted.</p>
	*
	* @since 1.5
	*/
	public abstract class JMXConnectorServer
	extends NotificationBroadcasterSupport
	implements JMXConnectorServerMBean, MBeanRegistration, JMXAddressable {

	/**
	* <p>Name of the attribute that specifies the authenticator for a
	* connector server. The value associated with this attribute, if
	* any, must be an object that implements the interface {@link
	* JMXAuthenticator}.</p>
	*/
	public static final String AUTHENTICATOR =
	"jmx.remote.authenticator";

	/**
	* <p>Constructs a connector server that will be registered as an
	* MBean in the MBean server it is attached to. This constructor
	* is typically called by one of the <code>createMBean</code>
	* methods when creating, within an MBean server, a connector
	* server that makes it available remotely.</p>
	*/
	public JMXConnectorServer() {
	this(null);
	}

	/**
	* <p>Constructs a connector server that is attached to the given
	* MBean server. A connector server that is created in this way
	* can be registered in a different MBean server, or not registered
	* in any MBean server.</p>
	*
	* @param mbeanServer the MBean server that this connector server
	* is attached to. Null if this connector server will be attached
	* to an MBean server by being registered in it.
	*/
	public JMXConnectorServer(MBeanServer mbeanServer) {
	this.mbeanServer = mbeanServer;
	}

	/**
	* <p>Returns the MBean server that this connector server is
	* attached to.</p>
	*
	* @return the MBean server that this connector server is attached
	* to, or null if it is not yet attached to an MBean server.
	*/
	public synchronized MBeanServer getMBeanServer() {
	return mbeanServer;
	}

	public synchronized void setMBeanServerForwarder(MBeanServerForwarder mbsf)
	{
	if (mbsf == null)
	throw new IllegalArgumentException("Invalid null argument: mbsf");

	if (mbeanServer != null) mbsf.setMBeanServer(mbeanServer);
	mbeanServer = mbsf;
	}

	public String[] getConnectionIds() {
	synchronized (connectionIds) {
	return connectionIds.toArray(new String[connectionIds.size()]);
	}
	}

	/**
	* <p>Returns a client stub for this connector server. A client
	* stub is a serializable object whose {@link
	* JMXConnector#connect(Map) connect} method can be used to make
	* one new connection to this connector server.</p>
	*
	* <p>A given connector need not support the generation of client
	* stubs. However, the connectors specified by the JMX Remote API do
	* (JMXMP Connector and RMI Connector).</p>
	*
	* <p>The default implementation of this method uses {@link
	* #getAddress} and {@link JMXConnectorFactory} to generate the
	* stub, with code equivalent to the following:</p>
	*
	* <pre>
	* JMXServiceURL addr = {@link #getAddress() getAddress()};
	* return {@link JMXConnectorFactory#newJMXConnector(JMXServiceURL, Map)
	* JMXConnectorFactory.newJMXConnector(addr, env)};
	* </pre>
	*
	* <p>A connector server for which this is inappropriate must
	* override this method so that it either implements the
	* appropriate logic or throws {@link
	* UnsupportedOperationException}.</p>
	*
	* @param env client connection parameters of the same sort that
	* could be provided to {@link JMXConnector#connect(Map)
	* JMXConnector.connect(Map)}. Can be null, which is equivalent
	* to an empty map.
	*
	* @return a client stub that can be used to make a new connection
	* to this connector server.
	*
	* @exception UnsupportedOperationException if this connector
	* server does not support the generation of client stubs.
	*
	* @exception IllegalStateException if the JMXConnectorServer is
	* not started (see {@link JMXConnectorServerMBean#isActive()}).
	*
	* @exception IOException if a communications problem means that a
	* stub cannot be created.
	**/
	public JMXConnector toJMXConnector(Map<String,?> env)
	throws IOException
	{
	if (!isActive()) throw new
	IllegalStateException("Connector is not active");
	JMXServiceURL addr = getAddress();
	return JMXConnectorFactory.newJMXConnector(addr, env);
	}

	/**
	* <p>Returns an array indicating the notifications that this MBean
	* sends. The implementation in <code>JMXConnectorServer</code>
	* returns an array with one element, indicating that it can emit
	* notifications of class {@link JMXConnectionNotification} with
	* the types defined in that class. A subclass that can emit other
	* notifications should return an array that contains this element
	* plus descriptions of the other notifications.</p>
	*
	* @return the array of possible notifications.
	*/
	@Override
	public MBeanNotificationInfo[] getNotificationInfo() {
	final String[] types = {
	JMXConnectionNotification.OPENED,
	JMXConnectionNotification.CLOSED,
	JMXConnectionNotification.FAILED,
	};
	final String className = JMXConnectionNotification.class.getName();
	final String description =
	"A client connection has been opened or closed";
	return new MBeanNotificationInfo[] {
	new MBeanNotificationInfo(types, className, description),
	};
	}

	/**
	* <p>Called by a subclass when a new client connection is opened.
	* Adds <code>connectionId</code> to the list returned by {@link
	* #getConnectionIds()}, then emits a {@link
	* JMXConnectionNotification} with type {@link
	* JMXConnectionNotification#OPENED}.</p>
	*
	* @param connectionId the ID of the new connection. This must be
	* different from the ID of any connection previously opened by
	* this connector server.
	*
	* @param message the message for the emitted {@link
	* JMXConnectionNotification}. Can be null. See {@link
	* Notification#getMessage()}.
	*
	* @param userData the <code>userData</code> for the emitted
	* {@link JMXConnectionNotification}. Can be null. See {@link
	* Notification#getUserData()}.
	*
	* @exception NullPointerException if <code>connectionId</code> is
	* null.
	*/
	protected void connectionOpened(String connectionId,
	String message,
	Object userData) {

	if (connectionId == null)
	throw new NullPointerException("Illegal null argument");

	synchronized (connectionIds) {
	connectionIds.add(connectionId);
	}

	sendNotification(JMXConnectionNotification.OPENED, connectionId,
	message, userData);
	}

	/**
	* <p>Called by a subclass when a client connection is closed
	* normally. Removes <code>connectionId</code> from the list returned
	* by {@link #getConnectionIds()}, then emits a {@link
	* JMXConnectionNotification} with type {@link
	* JMXConnectionNotification#CLOSED}.</p>
	*
	* @param connectionId the ID of the closed connection.
	*
	* @param message the message for the emitted {@link
	* JMXConnectionNotification}. Can be null. See {@link
	* Notification#getMessage()}.
	*
	* @param userData the <code>userData</code> for the emitted
	* {@link JMXConnectionNotification}. Can be null. See {@link
	* Notification#getUserData()}.
	*
	* @exception NullPointerException if <code>connectionId</code>
	* is null.
	*/
	protected void connectionClosed(String connectionId,
	String message,
	Object userData) {

	if (connectionId == null)
	throw new NullPointerException("Illegal null argument");

	synchronized (connectionIds) {
	connectionIds.remove(connectionId);
	}

	sendNotification(JMXConnectionNotification.CLOSED, connectionId,
	message, userData);
	}

	/**
	* <p>Called by a subclass when a client connection fails.
	* Removes <code>connectionId</code> from the list returned by
	* {@link #getConnectionIds()}, then emits a {@link
	* JMXConnectionNotification} with type {@link
	* JMXConnectionNotification#FAILED}.</p>
	*
	* @param connectionId the ID of the failed connection.
	*
	* @param message the message for the emitted {@link
	* JMXConnectionNotification}. Can be null. See {@link
	* Notification#getMessage()}.
	*
	* @param userData the <code>userData</code> for the emitted
	* {@link JMXConnectionNotification}. Can be null. See {@link
	* Notification#getUserData()}.
	*
	* @exception NullPointerException if <code>connectionId</code> is
	* null.
	*/
	protected void connectionFailed(String connectionId,
	String message,
	Object userData) {

	if (connectionId == null)
	throw new NullPointerException("Illegal null argument");

	synchronized (connectionIds) {
	connectionIds.remove(connectionId);
	}

	sendNotification(JMXConnectionNotification.FAILED, connectionId,
	message, userData);
	}

	private void sendNotification(String type, String connectionId,
	String message, Object userData) {
	Notification notif =
	new JMXConnectionNotification(type,
	getNotificationSource(),
	connectionId,
	nextSequenceNumber(),
	message,
	userData);
	sendNotification(notif);
	}

	private synchronized Object getNotificationSource() {
	if (myName != null)
	return myName;
	else
	return this;
	}

	private static long nextSequenceNumber() {
	synchronized (sequenceNumberLock) {
	return sequenceNumber++;
	}
	}

	// implements MBeanRegistration
	/**
	* <p>Called by an MBean server when this connector server is
	* registered in that MBean server. This connector server becomes
	* attached to the MBean server and its {@link #getMBeanServer()}
	* method will return <code>mbs</code>.</p>
	*
	* <p>If this connector server is already attached to an MBean
	* server, this method has no effect. The MBean server it is
	* attached to is not necessarily the one it is being registered
	* in.</p>
	*
	* @param mbs the MBean server in which this connection server is
	* being registered.
	*
	* @param name The object name of the MBean.
	*
	* @return The name under which the MBean is to be registered.
	*
	* @exception NullPointerException if <code>mbs</code> or
	* <code>name</code> is null.
	*/
	public synchronized ObjectName preRegister(MBeanServer mbs,
	ObjectName name) {
	if (mbs == null \|\| name == null)
	throw new NullPointerException("Null MBeanServer or ObjectName");
	if (mbeanServer == null) {
	mbeanServer = mbs;
	myName = name;
	}
	return name;
	}

	public void postRegister(Boolean registrationDone) {
	// do nothing
	}

	/**
	* <p>Called by an MBean server when this connector server is
	* unregistered from that MBean server. If this connector server
	* was attached to that MBean server by being registered in it,
	* and if the connector server is still active,
	* then unregistering it will call the {@link #stop stop} method.
	* If the <code>stop</code> method throws an exception, the
	* unregistration attempt will fail. It is recommended to call
	* the <code>stop</code> method explicitly before unregistering
	* the MBean.</p>
	*
	* @exception IOException if thrown by the {@link #stop stop} method.
	*/
	public synchronized void preDeregister() throws Exception {
	if (myName != null && isActive()) {
	stop();
	myName = null; // just in case stop is buggy and doesn't stop
	}
	}

	public void postDeregister() {
	myName = null;
	}

	/**
	* The MBeanServer used by this server to execute a client request.
	*/
	private MBeanServer mbeanServer = null;

	/**
	* The name used to registered this server in an MBeanServer.
	* It is null if the this server is not registered or has been unregistered.
	*/
	private ObjectName myName;

	private final List<String> connectionIds = new ArrayList<String>();

	private static final int[] sequenceNumberLock = new int[0];
	private static long sequenceNumber;
	}

Back to index...