/*

 * Copyright (c) 1997, 2013, 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 java.rmi.activation;

import java.lang.reflect.Constructor;

import java.lang.reflect.InvocationTargetException;

import java.rmi.MarshalledObject;

import java.rmi.Naming;

import java.rmi.Remote;

import java.rmi.RemoteException;

import java.rmi.activation.UnknownGroupException;

import java.rmi.activation.UnknownObjectException;

import java.rmi.server.RMIClassLoader;

import java.rmi.server.UnicastRemoteObject;

import java.security.AccessController;

import java.security.PrivilegedAction;

/**

 * An <code>ActivationGroup</code> is responsible for creating new

 * instances of "activatable" objects in its group, informing its

 * <code>ActivationMonitor</code> when either: its object's become

 * active or inactive, or the group as a whole becomes inactive. <p>

 *

 * An <code>ActivationGroup</code> is <i>initially</i> created in one

 * of several ways: <ul>

 * <li>as a side-effect of creating an <code>ActivationDesc</code>

 *     without an explicit <code>ActivationGroupID</code> for the

 *     first activatable object in the group, or

 * <li>via the <code>ActivationGroup.createGroup</code> method

 * <li>as a side-effect of activating the first object in a group

 *     whose <code>ActivationGroupDesc</code> was only registered.</ul><p>

 *

 * Only the activator can <i>recreate</i> an

 * <code>ActivationGroup</code>.  The activator spawns, as needed, a

 * separate VM (as a child process, for example) for each registered

 * activation group and directs activation requests to the appropriate

 * group. It is implementation specific how VMs are spawned. An

 * activation group is created via the

 * <code>ActivationGroup.createGroup</code> static method. The

 * <code>createGroup</code> method has two requirements on the group

 * to be created: 1) the group must be a concrete subclass of

 * <code>ActivationGroup</code>, and 2) the group must have a

 * constructor that takes two arguments:

 *

 * <ul>

 * <li> the group's <code>ActivationGroupID</code>, and

 * <li> the group's initialization data (in a

 *      <code>java.rmi.MarshalledObject</code>)</ul><p>

 *

 * When created, the default implementation of

 * <code>ActivationGroup</code> will override the system properties

 * with the properties requested when its

 * <code>ActivationGroupDesc</code> was created, and will set a

 * {@link SecurityManager} as the default system

 * security manager.  If your application requires specific properties

 * to be set when objects are activated in the group, the application

 * should create a special <code>Properties</code> object containing

 * these properties, then create an <code>ActivationGroupDesc</code>

 * with the <code>Properties</code> object, and use

 * <code>ActivationGroup.createGroup</code> before creating any

 * <code>ActivationDesc</code>s (before the default

 * <code>ActivationGroupDesc</code> is created).  If your application

 * requires the use of a security manager other than

 * {@link SecurityManager}, in the

 * ActivativationGroupDescriptor properties list you can set

 * <code>java.security.manager</code> property to the name of the security

 * manager you would like to install.

 *

 * @author      Ann Wollrath

 * @see         ActivationInstantiator

 * @see         ActivationGroupDesc

 * @see         ActivationGroupID

 * @since       1.2

 */

public abstract class ActivationGroup

        extends UnicastRemoteObject

        implements ActivationInstantiator

{

    /**

     * @serial the group's identifier

     */

    private ActivationGroupID groupID;

    /**

     * @serial the group's monitor

     */

    private ActivationMonitor monitor;

    /**

     * @serial the group's incarnation number

     */

    private long incarnation;

    /** the current activation group for this VM */

    private static ActivationGroup currGroup;

    /** the current group's identifier */

    private static ActivationGroupID currGroupID;

    /** the current group's activation system */

    private static ActivationSystem currSystem;

    /** used to control a group being created only once */

    private static boolean canCreate = true;

    /** indicate compatibility with the Java 2 SDK v1.2 version of class */

    private static final long serialVersionUID = -7696947875314805420L;

    /**

     * Constructs an activation group with the given activation group

     * identifier.  The group is exported as a

     * <code>java.rmi.server.UnicastRemoteObject</code>.

     *

     * @param   groupID the group's identifier

     * @throws  RemoteException if this group could not be exported

     * @throws  UnsupportedOperationException if and only if activation is

     *          not supported by this implementation

     * @since   1.2

     */

    protected ActivationGroup(ActivationGroupID groupID)

        throws RemoteException

    {

        // call super constructor to export the object

        super();

        this.groupID = groupID;

    }

    /**

     * The group's <code>inactiveObject</code> method is called

     * indirectly via a call to the <code>Activatable.inactive</code>

     * method. A remote object implementation must call

     * <code>Activatable</code>'s <code>inactive</code> method when

     * that object deactivates (the object deems that it is no longer

     * active). If the object does not call

     * <code>Activatable.inactive</code> when it deactivates, the

     * object will never be garbage collected since the group keeps

     * strong references to the objects it creates.

     *

     * <p>The group's <code>inactiveObject</code> method unexports the

     * remote object from the RMI runtime so that the object can no

     * longer receive incoming RMI calls. An object will only be unexported

     * if the object has no pending or executing calls.

     * The subclass of <code>ActivationGroup</code> must override this

     * method and unexport the object.

     *

     * <p>After removing the object from the RMI runtime, the group

     * must inform its <code>ActivationMonitor</code> (via the monitor's

     * <code>inactiveObject</code> method) that the remote object is

     * not currently active so that the remote object will be

     * re-activated by the activator upon a subsequent activation

     * request.

     *

     * <p>This method simply informs the group's monitor that the object

     * is inactive.  It is up to the concrete subclass of ActivationGroup

     * to fulfill the additional requirement of unexporting the object.

     *

     * @param id the object's activation identifier

     * @return true if the object was successfully deactivated; otherwise

     *         returns false.

     * @exception UnknownObjectException if object is unknown (may already

     * be inactive)

     * @exception RemoteException if call informing monitor fails

     * @exception ActivationException if group is inactive

     * @since 1.2

     */

    public boolean inactiveObject(ActivationID id)

        throws ActivationException, UnknownObjectException, RemoteException

    {

        getMonitor().inactiveObject(id);

        return true;

    }

    /**

     * The group's <code>activeObject</code> method is called when an

     * object is exported (either by <code>Activatable</code> object

     * construction or an explicit call to

     * <code>Activatable.exportObject</code>. The group must inform its

     * <code>ActivationMonitor</code> that the object is active (via

     * the monitor's <code>activeObject</code> method) if the group

     * hasn't already done so.

     *

     * @param id the object's identifier

     * @param obj the remote object implementation

     * @exception UnknownObjectException if object is not registered

     * @exception RemoteException if call informing monitor fails

     * @exception ActivationException if group is inactive

     * @since 1.2

     */

    public abstract void activeObject(ActivationID id, Remote obj)

        throws ActivationException, UnknownObjectException, RemoteException;

    /**

     * Create and set the activation group for the current VM.  The

     * activation group can only be set if it is not currently set.

     * An activation group is set using the <code>createGroup</code>

     * method when the <code>Activator</code> initiates the

     * re-creation of an activation group in order to carry out

     * incoming <code>activate</code> requests. A group must first be

     * registered with the <code>ActivationSystem</code> before it can

     * be created via this method.

     *

     * <p>The group class specified by the

     * <code>ActivationGroupDesc</code> must be a concrete subclass of

     * <code>ActivationGroup</code> and have a public constructor that

     * takes two arguments: the <code>ActivationGroupID</code> for the

     * group and the <code>MarshalledObject</code> containing the

     * group's initialization data (obtained from the

     * <code>ActivationGroupDesc</code>.

     *

     * <p>If the group class name specified in the

     * <code>ActivationGroupDesc</code> is <code>null</code>, then

     * this method will behave as if the group descriptor contained

     * the name of the default activation group implementation class.

     *

     * <p>Note that if your application creates its own custom

     * activation group, a security manager must be set for that

     * group.  Otherwise objects cannot be activated in the group.

     * {@link SecurityManager} is set by default.

     *

     * <p>If a security manager is already set in the group VM, this

     * method first calls the security manager's

     * <code>checkSetFactory</code> method.  This could result in a

     * <code>SecurityException</code>. If your application needs to

     * set a different security manager, you must ensure that the

     * policy file specified by the group's

     * <code>ActivationGroupDesc</code> grants the group the necessary

     * permissions to set a new security manager.  (Note: This will be

     * necessary if your group downloads and sets a security manager).

     *

     * <p>After the group is created, the

     * <code>ActivationSystem</code> is informed that the group is

     * active by calling the <code>activeGroup</code> method which

     * returns the <code>ActivationMonitor</code> for the group. The

     * application need not call <code>activeGroup</code>

     * independently since it is taken care of by this method.

     *

     * <p>Once a group is created, subsequent calls to the

     * <code>currentGroupID</code> method will return the identifier

     * for this group until the group becomes inactive.

     *

     * @param id the activation group's identifier

     * @param desc the activation group's descriptor

     * @param incarnation the group's incarnation number (zero on group's

     * initial creation)

     * @return the activation group for the VM

     * @exception ActivationException if group already exists or if error

     * occurs during group creation

     * @exception SecurityException if permission to create group is denied.

     * (Note: The default implementation of the security manager

     * <code>checkSetFactory</code>

     * method requires the RuntimePermission "setFactory")

     * @exception UnsupportedOperationException if and only if activation is

     * not supported by this implementation

     * @see SecurityManager#checkSetFactory

     * @since 1.2

     */

    public static synchronized

        ActivationGroup createGroup(ActivationGroupID id,

                                    final ActivationGroupDesc desc,

                                    long incarnation)

        throws ActivationException

    {

        SecurityManager security = System.getSecurityManager();

        if (security != null)

            security.checkSetFactory();

        if (currGroup != null)

            throw new ActivationException("group already exists");

        if (canCreate == false)

            throw new ActivationException("group deactivated and " +

                                          "cannot be recreated");

        try {

            // load group's class

            String groupClassName = desc.getClassName();

            Class<? extends ActivationGroup> cl;

            Class<? extends ActivationGroup> defaultGroupClass =

                sun.rmi.server.ActivationGroupImpl.class;

            if (groupClassName == null ||       // see 4252236

                groupClassName.equals(defaultGroupClass.getName()))

            {

                cl = defaultGroupClass;

            } else {

                Class<?> cl0;

                try {

                    cl0 = RMIClassLoader.loadClass(desc.getLocation(),

                                                   groupClassName);

                } catch (Exception ex) {

                    throw new ActivationException(

                        "Could not load group implementation class", ex);

                }

                if (ActivationGroup.class.isAssignableFrom(cl0)) {

                    cl = cl0.asSubclass(ActivationGroup.class);

                } else {

                    throw new ActivationException("group not correct class: " +

                                                  cl0.getName());

                }

            }

            // create group

            Constructor<? extends ActivationGroup> constructor =

                cl.getConstructor(ActivationGroupID.class,

                                  MarshalledObject.class);

            ActivationGroup newGroup =

                constructor.newInstance(id, desc.getData());

            currSystem = id.getSystem();

            newGroup.incarnation = incarnation;

            newGroup.monitor =

                currSystem.activeGroup(id, newGroup, incarnation);

            currGroup = newGroup;

            currGroupID = id;

            canCreate = false;

        } catch (InvocationTargetException e) {

                e.getTargetException().printStackTrace();

                throw new ActivationException("exception in group constructor",

                                              e.getTargetException());

        } catch (ActivationException e) {

            throw e;

        } catch (Exception e) {

            throw new ActivationException("exception creating group", e);

        }

        return currGroup;

    }

    /**

     * Returns the current activation group's identifier.  Returns null

     * if no group is currently active for this VM.

     * @exception UnsupportedOperationException if and only if activation is

     * not supported by this implementation

     * @return the activation group's identifier

     * @since 1.2

     */

    public static synchronized ActivationGroupID currentGroupID() {

        return currGroupID;

    }

    /**

     * Returns the activation group identifier for the VM.  If an

     * activation group does not exist for this VM, a default

     * activation group is created. A group can be created only once,

     * so if a group has already become active and deactivated.

     *

     * @return the activation group identifier

     * @exception ActivationException if error occurs during group

     * creation, if security manager is not set, or if the group

     * has already been created and deactivated.

     */

    static synchronized ActivationGroupID internalCurrentGroupID()

        throws ActivationException

    {

        if (currGroupID == null)

            throw new ActivationException("nonexistent group");

        return currGroupID;

    }

    /**

     * Set the activation system for the VM.  The activation system can

     * only be set it if no group is currently active. If the activation

     * system is not set via this call, then the <code>getSystem</code>

     * method attempts to obtain a reference to the

     * <code>ActivationSystem</code> by looking up the name

     * "java.rmi.activation.ActivationSystem" in the Activator's

     * registry. By default, the port number used to look up the

     * activation system is defined by

     * <code>ActivationSystem.SYSTEM_PORT</code>. This port can be overridden

     * by setting the property <code>java.rmi.activation.port</code>.

     *

     * <p>If there is a security manager, this method first

     * calls the security manager's <code>checkSetFactory</code> method.

     * This could result in a SecurityException.

     *

     * @param system remote reference to the <code>ActivationSystem</code>

     * @exception ActivationException if activation system is already set

     * @exception SecurityException if permission to set the activation system is denied.

     * (Note: The default implementation of the security manager

     * <code>checkSetFactory</code>

     * method requires the RuntimePermission "setFactory")

     * @exception UnsupportedOperationException if and only if activation is

     * not supported by this implementation

     * @see #getSystem

     * @see SecurityManager#checkSetFactory

     * @since 1.2

     */

    public static synchronized void setSystem(ActivationSystem system)

        throws ActivationException

    {

        SecurityManager security = System.getSecurityManager();

        if (security != null)

            security.checkSetFactory();

        if (currSystem != null)

            throw new ActivationException("activation system already set");

        currSystem = system;

    }

    /**

     * Returns the activation system for the VM. The activation system

     * may be set by the <code>setSystem</code> method. If the

     * activation system is not set via the <code>setSystem</code>

     * method, then the <code>getSystem</code> method attempts to

     * obtain a reference to the <code>ActivationSystem</code> by

     * looking up the name "java.rmi.activation.ActivationSystem" in

     * the Activator's registry. By default, the port number used to

     * look up the activation system is defined by

     * <code>ActivationSystem.SYSTEM_PORT</code>. This port can be

     * overridden by setting the property

     * <code>java.rmi.activation.port</code>.

     *

     * @return the activation system for the VM/group

     * @exception ActivationException if activation system cannot be

     *  obtained or is not bound

     * (means that it is not running)

     * @exception UnsupportedOperationException if and only if activation is

     * not supported by this implementation

     * @see #setSystem

     * @since 1.2

     */

    public static synchronized ActivationSystem getSystem()

        throws ActivationException

    {

        if (currSystem == null) {

            try {

                int port = AccessController.doPrivileged((PrivilegedAction<Integer>) () ->

                    Integer.getInteger("java.rmi.activation.port", ActivationSystem.SYSTEM_PORT));

                currSystem = (ActivationSystem)

                    Naming.lookup("//:" + port +

                                  "/java.rmi.activation.ActivationSystem");

            } catch (Exception e) {

                throw new ActivationException(

                    "unable to obtain ActivationSystem", e);

            }

        }

        return currSystem;

    }

    /**

     * This protected method is necessary for subclasses to

     * make the <code>activeObject</code> callback to the group's

     * monitor. The call is simply forwarded to the group's

     * <code>ActivationMonitor</code>.

     *

     * @param id the object's identifier

     * @param mobj a marshalled object containing the remote object's stub

     * @exception UnknownObjectException if object is not registered

     * @exception RemoteException if call informing monitor fails

     * @exception ActivationException if an activation error occurs

     * @since 1.2

     */

    protected void activeObject(ActivationID id,

                                MarshalledObject<? extends Remote> mobj)

        throws ActivationException, UnknownObjectException, RemoteException

    {

        getMonitor().activeObject(id, mobj);

    }

    /**

     * This protected method is necessary for subclasses to

     * make the <code>inactiveGroup</code> callback to the group's

     * monitor. The call is simply forwarded to the group's

     * <code>ActivationMonitor</code>. Also, the current group

     * for the VM is set to null.

     *

     * @exception UnknownGroupException if group is not registered

     * @exception RemoteException if call informing monitor fails

     * @since 1.2

     */

    protected void inactiveGroup()

        throws UnknownGroupException, RemoteException

    {

        try {

            getMonitor().inactiveGroup(groupID, incarnation);

        } finally {

            destroyGroup();

        }

    }

    /**

     * Returns the monitor for the activation group.

     */

    private ActivationMonitor getMonitor() throws RemoteException {

        synchronized (ActivationGroup.class) {

            if (monitor != null) {

                return monitor;

            }

        }

        throw new RemoteException("monitor not received");

    }

    /**

     * Destroys the current group.

     */

    private static synchronized void destroyGroup() {

        currGroup = null;

        currGroupID = null;

        // NOTE: don't set currSystem to null since it may be needed

    }

    /**