/*

 * Copyright 1997-2005 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 java.rmi.activation;

import java.io.Serializable;

import java.rmi.MarshalledObject;

/**

 * An activation descriptor contains the information necessary to

 * activate an object: <ul>

 * <li> the object's group identifier,

 * <li> the object's fully-qualified class name,

 * <li> the object's code location (the location of the class), a codebase URL

 * path,

 * <li> the object's restart "mode", and,

 * <li> a "marshalled" object that can contain object specific

 * initialization data. </ul>

 *

 * <p>A descriptor registered with the activation system can be used to

 * recreate/activate the object specified by the descriptor. The

 * <code>MarshalledObject</code> in the object's descriptor is passed

 * as the second argument to the remote object's constructor for

 * object to use during reinitialization/activation.

 *

 * @author      Ann Wollrath

 * @since       1.2

 * @see         java.rmi.activation.Activatable

 */

public final class ActivationDesc implements Serializable {

    /**

     * @serial the group's identifier

     */

    private ActivationGroupID groupID;

    /**

     * @serial the object's class name

     */

    private String className;

    /**

     * @serial the object's code location

     */

    private String location;

    /**

     * @serial the object's initialization data

     */

    private MarshalledObject<?> data;

    /**

     * @serial indicates whether the object should be restarted

     */

    private boolean restart;

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

    private static final long serialVersionUID = 7455834104417690957L;

    /**

     * Constructs an object descriptor for an object whose class name

     * is <code>className</code>, that can be loaded from the

     * code <code>location</code> and whose initialization

     * information is <code>data</code>. If this form of the constructor

     * is used, the <code>groupID</code> defaults to the current id for

     * <code>ActivationGroup</code> for this VM. All objects with the

     * same <code>ActivationGroupID</code> are activated in the same VM.

     *

     * <p>Note that objects specified by a descriptor created with this

     * constructor will only be activated on demand (by default, the restart

     * mode is <code>false</code>).  If an activatable object requires restart

     * services, use one of the <code>ActivationDesc</code> constructors that

     * takes a boolean parameter, <code>restart</code>.

     *

     * <p> This constructor will throw <code>ActivationException</code> if

     * there is no current activation group for this VM.  To create an

     * <code>ActivationGroup</code> use the

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

     *

     * @param className the object's fully package qualified class name

     * @param location the object's code location (from where the class is

     * loaded)

     * @param data the object's initialization (activation) data contained

     * in marshalled form.

     * @exception ActivationException if the current group is nonexistent

     * @since 1.2

     */

    public ActivationDesc(String className,

                          String location,

                          MarshalledObject<?> data)

        throws ActivationException

    {

        this(ActivationGroup.internalCurrentGroupID(),

             className, location, data, false);

    }

    /**

     * Constructs an object descriptor for an object whose class name

     * is <code>className</code>, that can be loaded from the

     * code <code>location</code> and whose initialization

     * information is <code>data</code>. If this form of the constructor

     * is used, the <code>groupID</code> defaults to the current id for

     * <code>ActivationGroup</code> for this VM. All objects with the

     * same <code>ActivationGroupID</code> are activated in the same VM.

     *

     * <p>This constructor will throw <code>ActivationException</code> if

     * there is no current activation group for this VM.  To create an

     * <code>ActivationGroup</code> use the

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

     *

     * @param className the object's fully package qualified class name

     * @param location the object's code location (from where the class is

     * loaded)

     * @param data the object's initialization (activation) data contained

     * in marshalled form.

     * @param restart if true, the object is restarted (reactivated) when

     * either the activator is restarted or the object's activation group

     * is restarted after an unexpected crash; if false, the object is only

     * activated on demand.  Specifying <code>restart</code> to be

     * <code>true</code> does not force an initial immediate activation of

     * a newly registered object;  initial activation is lazy.

     * @exception ActivationException if the current group is nonexistent

     * @since 1.2

     */

    public ActivationDesc(String className,

                          String location,

                          MarshalledObject<?> data,

                          boolean restart)

        throws ActivationException

    {

        this(ActivationGroup.internalCurrentGroupID(),

             className, location, data, restart);

    }

    /**

     * Constructs an object descriptor for an object whose class name

     * is <code>className</code> that can be loaded from the

     * code <code>location</code> and whose initialization

     * information is <code>data</code>. All objects with the same

     * <code>groupID</code> are activated in the same Java VM.

     *

     * <p>Note that objects specified by a descriptor created with this

     * constructor will only be activated on demand (by default, the restart

     * mode is <code>false</code>).  If an activatable object requires restart

     * services, use one of the <code>ActivationDesc</code> constructors that

     * takes a boolean parameter, <code>restart</code>.

     *

     * @param groupID the group's identifier (obtained from registering

     * <code>ActivationSystem.registerGroup</code> method). The group

     * indicates the VM in which the object should be activated.

     * @param className the object's fully package-qualified class name

     * @param location the object's code location (from where the class is

     * loaded)

     * @param data  the object's initialization (activation) data contained

     * in marshalled form.

     * @exception IllegalArgumentException if <code>groupID</code> is null

     * @since 1.2

     */

    public ActivationDesc(ActivationGroupID groupID,

                          String className,

                          String location,

                          MarshalledObject<?> data)

    {

        this(groupID, className, location, data, false);

    }

    /**

     * Constructs an object descriptor for an object whose class name

     * is <code>className</code> that can be loaded from the

     * code <code>location</code> and whose initialization

     * information is <code>data</code>. All objects with the same

     * <code>groupID</code> are activated in the same Java VM.

     *

     * @param groupID the group's identifier (obtained from registering

     * <code>ActivationSystem.registerGroup</code> method). The group

     * indicates the VM in which the object should be activated.

     * @param className the object's fully package-qualified class name

     * @param location the object's code location (from where the class is

     * loaded)

     * @param data  the object's initialization (activation) data contained

     * in marshalled form.

     * @param restart if true, the object is restarted (reactivated) when

     * either the activator is restarted or the object's activation group

     * is restarted after an unexpected crash; if false, the object is only

     * activated on demand.  Specifying <code>restart</code> to be

     * <code>true</code> does not force an initial immediate activation of

     * a newly registered object;  initial activation is lazy.

     * @exception IllegalArgumentException if <code>groupID</code> is null

     * @since 1.2

     */

    public ActivationDesc(ActivationGroupID groupID,

                          String className,

                          String location,

                          MarshalledObject<?> data,

                          boolean restart)

    {

        if (groupID == null)

            throw new IllegalArgumentException("groupID can't be null");

        this.groupID = groupID;

        this.className = className;

        this.location = location;

        this.data = data;

        this.restart = restart;

    }

    /**

     * Returns the group identifier for the object specified by this

     * descriptor. A group provides a way to aggregate objects into a

     * single Java virtual machine. RMI creates/activates objects with

     * the same <code>groupID</code> in the same virtual machine.

     *

     * @return the group identifier

     * @since 1.2

     */

    public ActivationGroupID getGroupID() {

        return groupID;

    }

    /**

     * Returns the class name for the object specified by this

     * descriptor.

     * @return the class name

     * @since 1.2

     */

    public String getClassName() {

        return className;

    }

    /**

     * Returns the code location for the object specified by

     * this descriptor.

     * @return the code location

     * @since 1.2

     */

    public String getLocation() {

        return location;

    }

    /**

     * Returns a "marshalled object" containing intialization/activation

     * data for the object specified by this descriptor.

     * @return the object specific "initialization" data

     * @since 1.2

     */

    public MarshalledObject<?> getData() {

        return data;

    }

    /**

     * Returns the "restart" mode of the object associated with

     * this activation descriptor.

     *

     * @return true if the activatable object associated with this

     * activation descriptor is restarted via the activation

     * daemon when either the daemon comes up or the object's group

     * is restarted after an unexpected crash; otherwise it returns false,

     * meaning that the object is only activated on demand via a

     * method call.  Note that if the restart mode is <code>true</code>, the

     * activator does not force an initial immediate activation of

     * a newly registered object;  initial activation is lazy.

     * @since 1.2

     */

    public boolean getRestartMode() {

        return restart;

    }

    /**

     * Compares two activation descriptors for content equality.

     *

     * @param   obj     the Object to compare with

     * @return  true if these Objects are equal; false otherwise.

     * @see             java.util.Hashtable

     * @since 1.2

     */

    public boolean equals(Object obj) {

        if (obj instanceof ActivationDesc) {

            ActivationDesc desc = (ActivationDesc) obj;

            return

                ((groupID == null ? desc.groupID == null :

                  groupID.equals(desc.groupID)) &&

                 (className == null ? desc.className == null :

                  className.equals(desc.className)) &&

                 (location == null ? desc.location == null:

                  location.equals(desc.location)) &&

                 (data == null ? desc.data == null :

                  data.equals(desc.data)) &&

                 (restart == desc.restart));

        } else {

            return false;

        }

    }

    /**

     * Return the same hashCode for similar <code>ActivationDesc</code>s.

     * @return an integer

     * @see java.util.Hashtable

     */

    public int hashCode() {

        return ((location == null

                    ? 0

                    : location.hashCode() << 24) ^

                (groupID == null

                    ? 0

                    : groupID.hashCode() << 16) ^

                (className == null

                    ? 0

                    : className.hashCode() << 9) ^

                (data == null

                    ? 0

                    : data.hashCode() << 1) ^

                (restart

                    ? 1

                    : 0));

    }

}