Home » openjdk-7 » java » rmi » activation » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.rmi.activation;
   27   
   28   import java.io.Serializable;
   29   import java.rmi.MarshalledObject;
   30   
   31   /**
   32    * An activation descriptor contains the information necessary to
   33    * activate an object: <ul>
   34    * <li> the object's group identifier,
   35    * <li> the object's fully-qualified class name,
   36    * <li> the object's code location (the location of the class), a codebase URL
   37    * path,
   38    * <li> the object's restart "mode", and,
   39    * <li> a "marshalled" object that can contain object specific
   40    * initialization data. </ul>
   41    *
   42    * <p>A descriptor registered with the activation system can be used to
   43    * recreate/activate the object specified by the descriptor. The
   44    * <code>MarshalledObject</code> in the object's descriptor is passed
   45    * as the second argument to the remote object's constructor for
   46    * object to use during reinitialization/activation.
   47    *
   48    * @author      Ann Wollrath
   49    * @since       1.2
   50    * @see         java.rmi.activation.Activatable
   51    */
   52   public final class ActivationDesc implements Serializable {
   53   
   54       /**
   55        * @serial the group's identifier
   56        */
   57       private ActivationGroupID groupID;
   58   
   59       /**
   60        * @serial the object's class name
   61        */
   62       private String className;
   63   
   64       /**
   65        * @serial the object's code location
   66        */
   67       private String location;
   68   
   69       /**
   70        * @serial the object's initialization data
   71        */
   72       private MarshalledObject<?> data;
   73   
   74       /**
   75        * @serial indicates whether the object should be restarted
   76        */
   77       private boolean restart;
   78   
   79       /** indicate compatibility with the Java 2 SDK v1.2 version of class */
   80       private static final long serialVersionUID = 7455834104417690957L;
   81   
   82       /**
   83        * Constructs an object descriptor for an object whose class name
   84        * is <code>className</code>, that can be loaded from the
   85        * code <code>location</code> and whose initialization
   86        * information is <code>data</code>. If this form of the constructor
   87        * is used, the <code>groupID</code> defaults to the current id for
   88        * <code>ActivationGroup</code> for this VM. All objects with the
   89        * same <code>ActivationGroupID</code> are activated in the same VM.
   90        *
   91        * <p>Note that objects specified by a descriptor created with this
   92        * constructor will only be activated on demand (by default, the restart
   93        * mode is <code>false</code>).  If an activatable object requires restart
   94        * services, use one of the <code>ActivationDesc</code> constructors that
   95        * takes a boolean parameter, <code>restart</code>.
   96        *
   97        * <p> This constructor will throw <code>ActivationException</code> if
   98        * there is no current activation group for this VM.  To create an
   99        * <code>ActivationGroup</code> use the
  100        * <code>ActivationGroup.createGroup</code> method.
  101        *
  102        * @param className the object's fully package qualified class name
  103        * @param location the object's code location (from where the class is
  104        * loaded)
  105        * @param data the object's initialization (activation) data contained
  106        * in marshalled form.
  107        * @exception ActivationException if the current group is nonexistent
  108        * @since 1.2
  109        */
  110       public ActivationDesc(String className,
  111                             String location,
  112                             MarshalledObject<?> data)
  113           throws ActivationException
  114       {
  115           this(ActivationGroup.internalCurrentGroupID(),
  116                className, location, data, false);
  117       }
  118   
  119       /**
  120        * Constructs an object descriptor for an object whose class name
  121        * is <code>className</code>, that can be loaded from the
  122        * code <code>location</code> and whose initialization
  123        * information is <code>data</code>. If this form of the constructor
  124        * is used, the <code>groupID</code> defaults to the current id for
  125        * <code>ActivationGroup</code> for this VM. All objects with the
  126        * same <code>ActivationGroupID</code> are activated in the same VM.
  127        *
  128        * <p>This constructor will throw <code>ActivationException</code> if
  129        * there is no current activation group for this VM.  To create an
  130        * <code>ActivationGroup</code> use the
  131        * <code>ActivationGroup.createGroup</code> method.
  132        *
  133        * @param className the object's fully package qualified class name
  134        * @param location the object's code location (from where the class is
  135        * loaded)
  136        * @param data the object's initialization (activation) data contained
  137        * in marshalled form.
  138        * @param restart if true, the object is restarted (reactivated) when
  139        * either the activator is restarted or the object's activation group
  140        * is restarted after an unexpected crash; if false, the object is only
  141        * activated on demand.  Specifying <code>restart</code> to be
  142        * <code>true</code> does not force an initial immediate activation of
  143        * a newly registered object;  initial activation is lazy.
  144        * @exception ActivationException if the current group is nonexistent
  145        * @since 1.2
  146        */
  147       public ActivationDesc(String className,
  148                             String location,
  149                             MarshalledObject<?> data,
  150                             boolean restart)
  151           throws ActivationException
  152       {
  153           this(ActivationGroup.internalCurrentGroupID(),
  154                className, location, data, restart);
  155       }
  156   
  157       /**
  158        * Constructs an object descriptor for an object whose class name
  159        * is <code>className</code> that can be loaded from the
  160        * code <code>location</code> and whose initialization
  161        * information is <code>data</code>. All objects with the same
  162        * <code>groupID</code> are activated in the same Java VM.
  163        *
  164        * <p>Note that objects specified by a descriptor created with this
  165        * constructor will only be activated on demand (by default, the restart
  166        * mode is <code>false</code>).  If an activatable object requires restart
  167        * services, use one of the <code>ActivationDesc</code> constructors that
  168        * takes a boolean parameter, <code>restart</code>.
  169        *
  170        * @param groupID the group's identifier (obtained from registering
  171        * <code>ActivationSystem.registerGroup</code> method). The group
  172        * indicates the VM in which the object should be activated.
  173        * @param className the object's fully package-qualified class name
  174        * @param location the object's code location (from where the class is
  175        * loaded)
  176        * @param data  the object's initialization (activation) data contained
  177        * in marshalled form.
  178        * @exception IllegalArgumentException if <code>groupID</code> is null
  179        * @since 1.2
  180        */
  181       public ActivationDesc(ActivationGroupID groupID,
  182                             String className,
  183                             String location,
  184                             MarshalledObject<?> data)
  185       {
  186           this(groupID, className, location, data, false);
  187       }
  188   
  189       /**
  190        * Constructs an object descriptor for an object whose class name
  191        * is <code>className</code> that can be loaded from the
  192        * code <code>location</code> and whose initialization
  193        * information is <code>data</code>. All objects with the same
  194        * <code>groupID</code> are activated in the same Java VM.
  195        *
  196        * @param groupID the group's identifier (obtained from registering
  197        * <code>ActivationSystem.registerGroup</code> method). The group
  198        * indicates the VM in which the object should be activated.
  199        * @param className the object's fully package-qualified class name
  200        * @param location the object's code location (from where the class is
  201        * loaded)
  202        * @param data  the object's initialization (activation) data contained
  203        * in marshalled form.
  204        * @param restart if true, the object is restarted (reactivated) when
  205        * either the activator is restarted or the object's activation group
  206        * is restarted after an unexpected crash; if false, the object is only
  207        * activated on demand.  Specifying <code>restart</code> to be
  208        * <code>true</code> does not force an initial immediate activation of
  209        * a newly registered object;  initial activation is lazy.
  210        * @exception IllegalArgumentException if <code>groupID</code> is null
  211        * @since 1.2
  212        */
  213       public ActivationDesc(ActivationGroupID groupID,
  214                             String className,
  215                             String location,
  216                             MarshalledObject<?> data,
  217                             boolean restart)
  218       {
  219           if (groupID == null)
  220               throw new IllegalArgumentException("groupID can't be null");
  221           this.groupID = groupID;
  222           this.className = className;
  223           this.location = location;
  224           this.data = data;
  225           this.restart = restart;
  226       }
  227   
  228       /**
  229        * Returns the group identifier for the object specified by this
  230        * descriptor. A group provides a way to aggregate objects into a
  231        * single Java virtual machine. RMI creates/activates objects with
  232        * the same <code>groupID</code> in the same virtual machine.
  233        *
  234        * @return the group identifier
  235        * @since 1.2
  236        */
  237       public ActivationGroupID getGroupID() {
  238           return groupID;
  239       }
  240   
  241       /**
  242        * Returns the class name for the object specified by this
  243        * descriptor.
  244        * @return the class name
  245        * @since 1.2
  246        */
  247       public String getClassName() {
  248           return className;
  249       }
  250   
  251       /**
  252        * Returns the code location for the object specified by
  253        * this descriptor.
  254        * @return the code location
  255        * @since 1.2
  256        */
  257       public String getLocation() {
  258           return location;
  259       }
  260   
  261       /**
  262        * Returns a "marshalled object" containing intialization/activation
  263        * data for the object specified by this descriptor.
  264        * @return the object specific "initialization" data
  265        * @since 1.2
  266        */
  267       public MarshalledObject<?> getData() {
  268           return data;
  269       }
  270   
  271       /**
  272        * Returns the "restart" mode of the object associated with
  273        * this activation descriptor.
  274        *
  275        * @return true if the activatable object associated with this
  276        * activation descriptor is restarted via the activation
  277        * daemon when either the daemon comes up or the object's group
  278        * is restarted after an unexpected crash; otherwise it returns false,
  279        * meaning that the object is only activated on demand via a
  280        * method call.  Note that if the restart mode is <code>true</code>, the
  281        * activator does not force an initial immediate activation of
  282        * a newly registered object;  initial activation is lazy.
  283        * @since 1.2
  284        */
  285       public boolean getRestartMode() {
  286           return restart;
  287       }
  288   
  289       /**
  290        * Compares two activation descriptors for content equality.
  291        *
  292        * @param   obj     the Object to compare with
  293        * @return  true if these Objects are equal; false otherwise.
  294        * @see             java.util.Hashtable
  295        * @since 1.2
  296        */
  297       public boolean equals(Object obj) {
  298   
  299           if (obj instanceof ActivationDesc) {
  300               ActivationDesc desc = (ActivationDesc) obj;
  301               return
  302                   ((groupID == null ? desc.groupID == null :
  303                     groupID.equals(desc.groupID)) &&
  304                    (className == null ? desc.className == null :
  305                     className.equals(desc.className)) &&
  306                    (location == null ? desc.location == null:
  307                     location.equals(desc.location)) &&
  308                    (data == null ? desc.data == null :
  309                     data.equals(desc.data)) &&
  310                    (restart == desc.restart));
  311   
  312           } else {
  313               return false;
  314           }
  315       }
  316   
  317       /**
  318        * Return the same hashCode for similar <code>ActivationDesc</code>s.
  319        * @return an integer
  320        * @see java.util.Hashtable
  321        */
  322       public int hashCode() {
  323           return ((location == null
  324                       ? 0
  325                       : location.hashCode() << 24) ^
  326                   (groupID == null
  327                       ? 0
  328                       : groupID.hashCode() << 16) ^
  329                   (className == null
  330                       ? 0
  331                       : className.hashCode() << 9) ^
  332                   (data == null
  333                       ? 0
  334                       : data.hashCode() << 1) ^
  335                   (restart
  336                       ? 1
  337                       : 0));
  338       }
  339   }

Home » openjdk-7 » java » rmi » activation » [javadoc | source]