https://openjdk.java.net/ 
/*
 * Copyright (c) 1997, 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 java.rmi.activation;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.Serializable;
import java.rmi.MarshalledObject;
import java.util.Arrays;
import java.util.Properties;


An activation group descriptor contains the information necessary to
create/recreate an activation group in which to activate objects.
Such a descriptor contains: 
    

  •  the group's class name,

  •  the group's code location (the location of the group's class), and

  •  a "marshalled" object that can contain group specific
initialization data. 
 

The group's class must be a concrete subclass of
ActivationGroup. A subclass of
ActivationGroup is created/recreated via the
ActivationGroup.createGroup static method that invokes
a special constructor that takes two arguments: 
    

  •  the group's ActivationGroupID, and

  •  the group's initialization data (in a
java.rmi.MarshalledObject)


Author:     Ann Wollrath
See Also:
Since:      1.2
/**
 * An activation group descriptor contains the information necessary to
 * create/recreate an activation group in which to activate objects.
 * Such a descriptor contains: <ul>
 * <li> the group's class name,
 * <li> the group's code location (the location of the group's class), and
 * <li> a "marshalled" object that can contain group specific
 * initialization data. </ul> <p>
 *
 * The group's class must be a concrete subclass of
 * <code>ActivationGroup</code>. A subclass of
 * <code>ActivationGroup</code> is created/recreated via the
 * <code>ActivationGroup.createGroup</code> static method that invokes
 * a special 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>
 *
 * @author      Ann Wollrath
 * @since       1.2
 * @see         ActivationGroup
 * @see         ActivationGroupID
 */
public final class ActivationGroupDesc implements Serializable {

    
@serialThe group's fully package qualified class name.
/**
     * @serial The group's fully package qualified class name.
     */
    private String className;

    
@serialThe location from where to load the group's class.
/**
     * @serial The location from where to load the group's class.
     */
    private String location;

    
@serialThe group's initialization data.
/**
     * @serial The group's initialization data.
     */
    private MarshalledObject<?> data;

    
@serialThe controlling options for executing the VM in
another process.
/**
     * @serial The controlling options for executing the VM in
     * another process.
     */
    private CommandEnvironment env;

    
@serialA properties map which will override those set
by default in the subprocess environment.
/**
     * @serial A properties map which will override those set
     * by default in the subprocess environment.
     */
    private Properties props;

    
indicate compatibility with the Java 2 SDK v1.2 version of class 
/** indicate compatibility with the Java 2 SDK v1.2 version of class */
    private static final long serialVersionUID = -4936225423168276595L;

    
Constructs a group descriptor that uses the system defaults for group
implementation and code location.  Properties specify Java
environment overrides (which will override system properties in
the group implementation's VM).  The command
environment can control the exact command/options used in
starting the child VM, or can be null to accept
rmid's default.

This constructor will create an ActivationGroupDesc
with a null group class name, which indicates the system's
default ActivationGroup implementation.

Params:
  • overrides – the set of properties to set when the group is
recreated.
  • cmd – the controlling options for executing the VM in
another process (or null).
Since:1.2
/**
     * Constructs a group descriptor that uses the system defaults for group
     * implementation and code location.  Properties specify Java
     * environment overrides (which will override system properties in
     * the group implementation's VM).  The command
     * environment can control the exact command/options used in
     * starting the child VM, or can be <code>null</code> to accept
     * rmid's default.
     *
     * <p>This constructor will create an <code>ActivationGroupDesc</code>
     * with a <code>null</code> group class name, which indicates the system's
     * default <code>ActivationGroup</code> implementation.
     *
     * @param overrides the set of properties to set when the group is
     * recreated.
     * @param cmd the controlling options for executing the VM in
     * another process (or <code>null</code>).
     * @since 1.2
     */
    public ActivationGroupDesc(Properties overrides,
                               CommandEnvironment cmd)
    {
        this(null, null, null, overrides, cmd);
    }

    
Specifies an alternate group implementation and execution
environment to be used for the group.

Params:
  • className – the group's package qualified class name or
null. A null group class name indicates
the system's default ActivationGroup implementation.
  • location – the location from where to load the group's
class
  • data – the group's initialization data contained in
marshalled form (could contain properties, for example)
  • overrides – a properties map which will override those set
by default in the subprocess environment (will be translated
into -D options), or null.
  • cmd – the controlling options for executing the VM in
another process (or null).
Since:1.2
/**
     * Specifies an alternate group implementation and execution
     * environment to be used for the group.
     *
     * @param className the group's package qualified class name or
     * <code>null</code>. A <code>null</code> group class name indicates
     * the system's default <code>ActivationGroup</code> implementation.
     * @param location the location from where to load the group's
     * class
     * @param data the group's initialization data contained in
     * marshalled form (could contain properties, for example)
     * @param overrides a properties map which will override those set
     * by default in the subprocess environment (will be translated
     * into <code>-D</code> options), or <code>null</code>.
     * @param cmd the controlling options for executing the VM in
     * another process (or <code>null</code>).
     * @since 1.2
     */
    public ActivationGroupDesc(String className,
                               String location,
                               MarshalledObject<?> data,
                               Properties overrides,
                               CommandEnvironment cmd)
    {
        this.props = overrides;
        this.env = cmd;
        this.data = data;
        this.location = location;
        this.className = className;
    }

    
Returns the group's class name (possibly null).  A
null group class name indicates the system's default
ActivationGroup implementation.

Returns:the group's class name
Since:1.2
/**
     * Returns the group's class name (possibly <code>null</code>).  A
     * <code>null</code> group class name indicates the system's default
     * <code>ActivationGroup</code> implementation.
     * @return the group's class name
     * @since 1.2
     */
    public String getClassName() {
        return className;
    }

    
Returns the group's code location.

Returns:the group's code location
Since:1.2
/**
     * Returns the group's code location.
     * @return the group's code location
     * @since 1.2
     */
    public String getLocation() {
        return location;
    }

    
Returns the group's initialization data.

Returns:the group's initialization data
Since:1.2
/**
     * Returns the group's initialization data.
     * @return the group's initialization data
     * @since 1.2
     */
    public MarshalledObject<?> getData() {
        return data;
    }

    
Returns the group's property-override list.

Returns:the property-override list, or null
Since:1.2
/**
     * Returns the group's property-override list.
     * @return the property-override list, or <code>null</code>
     * @since 1.2
     */
    public Properties getPropertyOverrides() {
        return (props != null) ? (Properties) props.clone() : null;
    }

    
Returns the group's command-environment control object.

Returns:the command-environment object, or null
Since:1.2
/**
     * Returns the group's command-environment control object.
     * @return the command-environment object, or <code>null</code>
     * @since 1.2
     */
    public CommandEnvironment getCommandEnvironment() {
        return this.env;
    }


    
Startup options for ActivationGroup implementations.
This class allows overriding default system properties and
specifying implementation-defined options for ActivationGroups.

Since:1.2
/**
     * Startup options for ActivationGroup implementations.
     *
     * This class allows overriding default system properties and
     * specifying implementation-defined options for ActivationGroups.
     * @since 1.2
     */
    public static class CommandEnvironment implements Serializable {
        private static final long serialVersionUID = 6165754737887770191L;

        
@serial
/**
         * @serial
         */
        private String command;

        
@serial
/**
         * @serial
         */
        private String[] options;

        
Create a CommandEnvironment with all the necessary
information.

Params:
  • cmdpath – the name of the java executable, including
the full path, or null, meaning "use rmid's default".
The named program must be able to accept multiple
-Dpropname=value options (as documented for the
"java" tool)
  • argv – extra options which will be used in creating the
ActivationGroup.  Null has the same effect as an empty
list.
Since:1.2
/**
         * Create a CommandEnvironment with all the necessary
         * information.
         *
         * @param cmdpath the name of the java executable, including
         * the full path, or <code>null</code>, meaning "use rmid's default".
         * The named program <em>must</em> be able to accept multiple
         * <code>-Dpropname=value</code> options (as documented for the
         * "java" tool)
         *
         * @param argv extra options which will be used in creating the
         * ActivationGroup.  Null has the same effect as an empty
         * list.
         * @since 1.2
         */
        public CommandEnvironment(String cmdpath,
                                  String[] argv)
        {
            this.command = cmdpath;     // might be null

            // Hold a safe copy of argv in this.options
            if (argv == null) {
                this.options = new String[0];
            } else {
                this.options = new String[argv.length];
                System.arraycopy(argv, 0, this.options, 0, argv.length);
            }
        }

        
Fetch the configured path-qualified java command name.

Returns:the configured name, or null if configured to
accept the default
Since:1.2
/**
         * Fetch the configured path-qualified java command name.
         *
         * @return the configured name, or <code>null</code> if configured to
         * accept the default
         * @since 1.2
         */
        public String getCommandPath() {
            return (this.command);
        }

        
Fetch the configured java command options.

Returns:An array of the command options which will be passed
to the new child command by rmid.
Note that rmid may add other options before or after these
options, or both.
Never returns null.
Since:1.2
/**
         * Fetch the configured java command options.
         *
         * @return An array of the command options which will be passed
         * to the new child command by rmid.
         * Note that rmid may add other options before or after these
         * options, or both.
         * Never returns <code>null</code>.
         * @since 1.2
         */
        public String[] getCommandOptions() {
            return options.clone();
        }

        
Compares two command environments for content equality.

Params:
  • obj –     the Object to compare with
See Also:
Returns:     true if these Objects are equal; false otherwise.
Since:1.2
/**
         * Compares two command environments 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 CommandEnvironment) {
                CommandEnvironment env = (CommandEnvironment) obj;
                return
                    ((command == null ? env.command == null :
                      command.equals(env.command)) &&
                     Arrays.equals(options, env.options));
            } else {
                return false;
            }
        }

        
Return identical values for similar
CommandEnvironments.

See Also:
Returns:an integer
/**
         * Return identical values for similar
         * <code>CommandEnvironment</code>s.
         * @return an integer
         * @see java.util.Hashtable
         */
        public int hashCode()
        {
            // hash command and ignore possibly expensive options
            return (command == null ? 0 : command.hashCode());
        }

        
readObject for custom serialization.

This method reads this object's serialized form for this
class as follows:

This method first invokes defaultReadObject on
the specified object input stream, and if options
is null, then options is set to a
zero-length array of String.

/**
         * <code>readObject</code> for custom serialization.
         *
         * <p>This method reads this object's serialized form for this
         * class as follows:
         *
         * <p>This method first invokes <code>defaultReadObject</code> on
         * the specified object input stream, and if <code>options</code>
         * is <code>null</code>, then <code>options</code> is set to a
         * zero-length array of <code>String</code>.
         */
        private void readObject(ObjectInputStream in)
            throws IOException, ClassNotFoundException
        {
            in.defaultReadObject();
            if (options == null) {
                options = new String[0];
            }
        }
    }

    
Compares two activation group descriptors for content equality.

Params:
  • obj –     the Object to compare with
See Also:
Returns: true if these Objects are equal; false otherwise.
Since:1.2
/**
     * Compares two activation group 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 ActivationGroupDesc) {
            ActivationGroupDesc desc = (ActivationGroupDesc) obj;
            return
                ((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)) &&
                 (env == null ? desc.env == null : env.equals(desc.env)) &&
                 (props == null ? desc.props == null :
                  props.equals(desc.props)));
        } else {
            return false;
        }
    }

    
Produce identical numbers for similar ActivationGroupDescs.

See Also:
Returns:an integer
/**
     * Produce identical numbers for similar <code>ActivationGroupDesc</code>s.
     * @return an integer
     * @see java.util.Hashtable
     */
    public int hashCode() {
        // hash location, className, data, and env
        // but omit props (may be expensive)
        return ((location == null
                    ? 0
                    : location.hashCode() << 24) ^
                (env == null
                    ? 0
                    : env.hashCode() << 16) ^
                (className == null
                    ? 0
                    : className.hashCode() << 8) ^
                (data == null
                    ? 0
                    : data.hashCode()));
    }
}