/*

 * Copyright 2003-2008 Sun Microsystems, Inc.  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.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package javax.management.remote;

import com.sun.jmx.remote.util.EnvHelp;

import java.io.IOException;

import java.util.ArrayList;

import java.util.List;

import java.util.Map;

import java.util.NoSuchElementException;

import javax.management.ClientContext;

import javax.management.MBeanInfo;  // for javadoc

import javax.management.MBeanNotificationInfo;

import javax.management.MBeanRegistration;

import javax.management.MBeanServer;

import javax.management.Notification;

import javax.management.NotificationBroadcasterSupport;

import javax.management.ObjectName;

import javax.management.event.EventClientDelegate;

/**

 * <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>Name of the attribute that specifies whether this connector

      * server can delegate notification handling to the

      * {@linkplain javax.management.event Event Service}.

      * The value associated with

      * this attribute, if any, is a String, which must be equal,

      * ignoring case, to {@code "true"} or {@code "false"}.</p>

      *

      * <p>Not all connector servers will understand this attribute, but the

      * standard {@linkplain javax.management.remote.rmi.RMIConnectorServer

      * RMI Connector Server} does.</p>

      *

      * <p>If this attribute is not present, then the system property of the

      * same name (<code>{@value}</code>) is consulted. If that is not set

      * either, then the Event Service is used if the connector server

      * supports it.</p>

      *

      * @since 1.7

      */

     public static final String DELEGATE_TO_EVENT_SERVICE =

         "jmx.remote.delegate.event.service";

     /**

      * <p>Name of the attribute that specifies whether this connector

      * server allows clients to communicate a context with each request.

      * The value associated with this attribute, if any, must be a string

      * that is equal to {@code "true"} or {@code "false"}, ignoring case.

      * If it is {@code "true"}, then the connector server will simulate

      * a namespace {@code jmx.context//}, as described in

      * {@link ClientContext#newContextForwarder}.  This namespace is needed

      * for {@link ClientContext#withContext ClientContext.withContext} to

      * function correctly.</p>

      *

      * <p>Not all connector servers will understand this attribute, but the

      * standard {@linkplain javax.management.remote.rmi.RMIConnectorServer

      * RMI Connector Server} does.  For a connector server that understands

      * this attribute, the default value is {@code "true"}.</p>

      *

      * @since 1.7

      */

     public static final String CONTEXT_FORWARDER =

         "jmx.remote.context.forwarder";

     /**

      * <p>Name of the attribute that specifies whether this connector server

      * localizes the descriptions in the {@link MBeanInfo} object returned by

      * {@link MBeanServer#getMBeanInfo MBeanServer.getMBeanInfo}, based on the

      * locale communicated by the client.</p>

      *

      * <p>The value associated with this attribute, if any, must be a string

      * that is equal to {@code "true"} or {@code "false"}, ignoring case.

      * If it is {@code "true"}, then the connector server will localize

      * {@code MBeanInfo} descriptions as specified in {@link

      * ClientContext#newLocalizeMBeanInfoForwarder}.</p>

      *

      * <p>Not all connector servers will understand this attribute, but the

      * standard {@linkplain javax.management.remote.rmi.RMIConnectorServer

      * RMI Connector Server} does.  For a connector server that understands

      * this attribute, the default value is {@code "false"}.</p>

      *

      * <p>Because localization requires the client to be able to communicate

      * its locale, it does not make sense to specify this attribute as

      * {@code "true"} if {@link #CONTEXT_FORWARDER} is not also {@code "true"}.

      * For a connector server that understands these attributes, specifying

      * this inconsistent combination will result in an {@link

      * IllegalArgumentException}.</p>

      *

      * @since 1.7

      */

     public static final String LOCALIZE_MBEAN_INFO_FORWARDER =

        "jmx.remote.localize.mbean.info";

     /**

      * <p>Name of the attribute that specifies whether this connector

      * server simulates the existence of the {@link EventClientDelegate}

      * MBean. The value associated with this attribute, if any, must

      * be a string that is equal to {@code "true"} or {@code "false"},

      * ignoring case. If it is {@code "true"}, then the connector server

      * will simulate an EventClientDelegate MBean, as described in {@link

      * EventClientDelegate#newForwarder}. This MBean is needed for {@link

      * javax.management.event.EventClient EventClient} to function correctly.</p>

      *

      * <p>Not all connector servers will understand this attribute, but the

      * standard {@linkplain javax.management.remote.rmi.RMIConnectorServer

      * RMI Connector Server} does.  For a connector server that understands

      * this attribute, the default value is {@code "true"}.</p>

      *

      * @since 1.7

      */

     public static final String EVENT_CLIENT_DELEGATE_FORWARDER =

         "jmx.remote.event.client.delegate.forwarder";

    /**

     * <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) {

        insertUserMBeanServer(mbeanServer);

    }

    /**

     * <p>Returns the MBean server that this connector server is

     * attached to, or the first in a chain of user-added

     * {@link MBeanServerForwarder}s, if any.</p>

     *

     * @return the MBean server that this connector server is attached

     * to, or null if it is not yet attached to an MBean server.

     *

     * @see #setMBeanServerForwarder

     * @see #getSystemMBeanServerForwarder

     */

    public synchronized MBeanServer getMBeanServer() {

        return userMBeanServer;

    }

    public synchronized void setMBeanServerForwarder(MBeanServerForwarder mbsf) {

        if (mbsf == null)

            throw new IllegalArgumentException("Invalid null argument: mbsf");

        if (userMBeanServer != null)

            mbsf.setMBeanServer(userMBeanServer);

        insertUserMBeanServer(mbsf);

    }

    /**

     * <p>Remove a forwarder from the chain of forwarders.  The forwarder can

     * be in the system chain or the user chain.  On successful return from

     * this method, the first occurrence in the chain of an object that is

     * {@linkplain Object#equals equal} to {@code mbsf} will have been

     * removed.</p>

     *

     * @param mbsf the forwarder to remove

     *

     * @throws NoSuchElementException if there is no occurrence of {@code mbsf}

     * in the chain.

     * @throws IllegalArgumentException if {@code mbsf} is null or is the

     * {@linkplain #getSystemMBeanServerForwarder() system forwarder}.

     *

     * @since 1.7

     */

    public synchronized void removeMBeanServerForwarder(MBeanServerForwarder mbsf) {

        if (mbsf == null)

            throw new IllegalArgumentException("Invalid null argument: mbsf");

        if (systemMBeanServerForwarder.equals(mbsf))

            throw new IllegalArgumentException("Cannot remove system forwarder");

        MBeanServerForwarder prev = systemMBeanServerForwarder;

        MBeanServer curr;

        while (true) {

            curr = prev.getMBeanServer();

            if (mbsf.equals(curr))

                break;

            if (curr instanceof MBeanServerForwarder)

                prev = (MBeanServerForwarder) curr;

            else

                throw new NoSuchElementException("MBeanServerForwarder not in chain");

        }

        MBeanServer next = mbsf.getMBeanServer();

        prev.setMBeanServer(next);

        if (userMBeanServer == mbsf)

            userMBeanServer = next;

    }

    /*

     * Set userMBeanServer to mbs and arrange for the end of the chain of

     * system MBeanServerForwarders to point to it.  See the comment before

     * the systemMBeanServer and userMBeanServer field declarations.

     */

    private void insertUserMBeanServer(MBeanServer mbs) {

        MBeanServerForwarder lastSystemMBSF = systemMBeanServerForwarder;

        while (true) {

            MBeanServer mbsi = lastSystemMBSF.getMBeanServer();

            if (mbsi == userMBeanServer)

                break;

            lastSystemMBSF = (MBeanServerForwarder) mbsi;

        }

        userMBeanServer = mbs;

        lastSystemMBSF.setMBeanServer(mbs);

    }

    /**

     * <p>Returns the first item in the chain of system and then user

     * forwarders.  There is a chain of {@link MBeanServerForwarder}s between

     * a {@code JMXConnectorServer} and its {@code MBeanServer}.  This chain

     * consists of two sub-chains: first the <em>system chain</em> and then

     * the <em>user chain</em>.  Incoming requests are given to the first

     * forwarder in the system chain.  Each forwarder can handle a request

     * itself, or more usually forward it to the next forwarder, perhaps with

     * some extra behavior such as logging or security checking before or after

     * the forwarding.  The last forwarder in the system chain is followed by

     * the first forwarder in the user chain.</p>

     *

     * <p>The object returned by this method is the first forwarder in the

     * system chain.  For a given {@code JMXConnectorServer}, this method

     * always returns the same object, which simply forwards every request

     * to the next object in the chain.</p>

     *

     * <p>Not all connector servers support a system chain of forwarders,

     * although the standard {@linkplain

     * javax.management.remote.rmi.RMIConnectorServer RMI connector

     * server} does.  For those that do not, this method will throw {@code

     * UnsupportedOperationException}.  All

     * connector servers do support a user chain of forwarders.</p>

     *

     * <p>The <em>system chain</em> is usually defined by a

     * connector server based on the environment Map; see {@link

     * JMXConnectorServerFactory#newJMXConnectorServer

     * JMXConnectorServerFactory.newJMXConnectorServer}.  Allowing

     * the connector server to define its forwarders in this way

     * ensures that they are in the correct order - some forwarders

     * need to be inserted before others for correct behavior.  It is

     * possible to modify the system chain, for example using {@code

     * connectorServer.getSystemMBeanServerForwarder().setMBeanServer(mbsf)} or

     * {@link #removeMBeanServerForwarder removeMBeanServerForwarder}, but in

     * that case the system chain is no longer guaranteed to be correct.</p>

     *

     * <p>The <em>user chain</em> is defined by calling {@link

     * #setMBeanServerForwarder setMBeanServerForwarder} to insert forwarders

     * at the head of the user chain.</p>

     *

     * <p>This code illustrates how the chains can be traversed:</p>

     *

     * <pre>

     * JMXConnectorServer cs;

     * System.out.println("system chain:");

     * MBeanServer mbs = cs.getSystemMBeanServerForwarder();

     * while (true) {

     *     if (mbs == cs.getMBeanServer())

     *         System.out.println("user chain:");

     *     if (!(mbs instanceof MBeanServerForwarder))

     *         break;

     *     MBeanServerForwarder mbsf = (MBeanServerForwarder) mbs;

     *     System.out.println("--forwarder: " + mbsf);

     *     mbs = mbsf.getMBeanServer();

     * }

     * System.out.println("--MBean Server");

     * </pre>

     *

     * <h4>Note for connector server implementors</h4>

     *

     * <p>Existing connector server implementations can be updated to support

     * a system chain of forwarders as follows:</p>

     *

     * <ul>

     * <li><p>Override the {@link #supportsSystemMBeanServerForwarder()}

     * method so that it returns true.</p>

     *

     * <li><p>Call {@link #installStandardForwarders} from the constructor of

     * the connector server.</p>

     *

     * <li><p>Direct incoming requests to the result of {@link

     * #getSystemMBeanServerForwarder()} instead of the result of {@link

     * #getMBeanServer()}.</p>

     * </ul>

     *

     * @return the first item in the system chain of forwarders.

     *

     * @throws UnsupportedOperationException if {@link

     * #supportsSystemMBeanServerForwarder} returns false.

     *

     * @see #supportsSystemMBeanServerForwarder

     * @see #setMBeanServerForwarder

     *

     * @since 1.7

     */

    public MBeanServerForwarder getSystemMBeanServerForwarder() {

        if (!supportsSystemMBeanServerForwarder()) {

            throw new UnsupportedOperationException(

                    "System MBeanServerForwarder not supported by this " +

                    "connector server");

        }

        return systemMBeanServerForwarder;

    }

    /**

     * <p>Returns true if this connector server supports a system chain of

     * {@link MBeanServerForwarder}s.  The default implementation of this

     * method returns false.  Connector servers that do support the system

     * chain must override this method to return true.

     *

     * @return true if this connector server supports the system chain of

     * forwarders.

     *

     * @since 1.7

     */

    public boolean supportsSystemMBeanServerForwarder() {

        return false;

    }

    /**

     * <p>Install {@link MBeanServerForwarder}s in the system chain

     * based on the attributes in the given {@code Map}.  A connector

     * server that {@linkplain #supportsSystemMBeanServerForwarder supports}

     * a system chain of {@code MBeanServerForwarder}s can call this method

     * to add forwarders to that chain based on the contents of {@code env}.

     * In order:</p>

     *

     * <ul>

     *

     * <li>If {@link #EVENT_CLIENT_DELEGATE_FORWARDER} is absent, or is

     * present with the value {@code "true"}, then a forwarder

     * equivalent to {@link EventClientDelegate#newForwarder

     * EventClientDelegate.newForwarder}{@code (sysMBSF.getMBeanServer(),

     * sysMBSF)} is inserted at the start of the system chain,

     * where {@code sysMBSF} is the object returned by {@link

     * #getSystemMBeanServerForwarder()}. </li>

     *

     * <li>If {@link #LOCALIZE_MBEAN_INFO_FORWARDER} is present with the

     * value {@code "true"}, then a forwarder equivalent to

     * {@link ClientContext#newLocalizeMBeanInfoForwarder

     * ClientContext.newLocalizeMBeanInfoForwarder}{@code

     * (sysMBSF.getMBeanServer())} is inserted at the start of the system

     * chain.</li>

     *

     * <li>If {@link #CONTEXT_FORWARDER} is absent, or is present with

     * the value {@code "true"}, then a forwarder equivalent to

     * {@link ClientContext#newContextForwarder

     * ClientContext.newContextForwarder}{@code (sysMSBF.getMBeanServer(),

     * sysMBSF)} is inserted at the tart of the system chain.</li>

     *

     * </ul>

     *

     * <p>For {@code EVENT_CLIENT_DELEGATE_FORWARDER} and {@code

     * CONTEXT_FORWARDER}, if the attribute is absent from the {@code

     * Map} and a system property of the same name is defined, then

     * the value of the system property is used as if it were in the

     * {@code Map}.

     *

     * <p>Since each forwarder is inserted at the start of the chain,

     * the final order of the forwarders is the <b>reverse</b> of the order

     * above.  This is important, because the {@code

     * LOCALIZE_MBEAN_INFO_FORWARDER} can only work if the {@code

     * CONTEXT_FORWARDER} has already installed the remote client's locale

     * in the {@linkplain ClientContext#getContext context} of the current

     * thread.</p>

     *

     * <p>Attributes in {@code env} that are not listed above are ignored

     * by this method.</p>

     *

     * @throws UnsupportedOperationException if {@link

     * #supportsSystemMBeanServerForwarder} is false.

     *

     * @throws IllegalArgumentException if the relevant attributes in {@code env} are

     * inconsistent, for example if {@link #LOCALIZE_MBEAN_INFO_FORWARDER} is

     * {@code "true"} but {@link #CONTEXT_FORWARDER} is {@code "false"}; or

     * if one of the attributes has an illegal value.

     *

     * @since 1.7

     */

    protected void installStandardForwarders(Map<String, ?> env) {

        MBeanServerForwarder sysMBSF = getSystemMBeanServerForwarder();

        // Remember that forwarders must be added in reverse order!

        boolean ecd = EnvHelp.computeBooleanFromString(

                env, EVENT_CLIENT_DELEGATE_FORWARDER, false, true);

        boolean localize = EnvHelp.computeBooleanFromString(

                env, LOCALIZE_MBEAN_INFO_FORWARDER, false, false);

        boolean context = EnvHelp.computeBooleanFromString(

                env, CONTEXT_FORWARDER, false, true);

        if (localize && !context) {

            throw new IllegalArgumentException(

                    "Inconsistent environment parameters: " +

                    LOCALIZE_MBEAN_INFO_FORWARDER + "=\"true\" requires " +

                    CONTEXT_FORWARDER + "=\"true\"");

        }

        if (ecd) {

            MBeanServerForwarder mbsf = EventClientDelegate.newForwarder(