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.rmi.MarshalledObject;
   29   import java.rmi.NoSuchObjectException;
   30   import java.rmi.Remote;
   31   import java.rmi.RemoteException;
   32   import java.rmi.activation.UnknownGroupException;
   33   import java.rmi.activation.UnknownObjectException;
   34   import java.rmi.server.RMIClientSocketFactory;
   35   import java.rmi.server.RMIServerSocketFactory;
   36   import java.rmi.server.RemoteServer;
   37   import sun.rmi.server.ActivatableServerRef;
   38   
   39   /**
   40    * The <code>Activatable</code> class provides support for remote
   41    * objects that require persistent access over time and that
   42    * can be activated by the system.
   43    *
   44    * <p>For the constructors and static <code>exportObject</code> methods,
   45    * the stub for a remote object being exported is obtained as described in
   46    * {@link java.rmi.server.UnicastRemoteObject}.
   47    *
   48    * <p>An attempt to serialize explicitly an instance of this class will
   49    * fail.
   50    *
   51    * @author      Ann Wollrath
   52    * @since       1.2
   53    * @serial      exclude
   54    */
   55   public abstract class Activatable extends RemoteServer {
   56   
   57       private ActivationID id;
   58       /** indicate compatibility with the Java 2 SDK v1.2 version of class */
   59       private static final long serialVersionUID = -3120617863591563455L;
   60   
   61       /**
   62        * Constructs an activatable remote object by registering
   63        * an activation descriptor (with the specified location, data, and
   64        * restart mode) for this object, and exporting the object with the
   65        * specified port.
   66        *
   67        * <p><strong>Note:</strong> Using the <code>Activatable</code>
   68        * constructors that both register and export an activatable remote
   69        * object is strongly discouraged because the actions of registering
   70        * and exporting the remote object are <i>not</i> guaranteed to be
   71        * atomic.  Instead, an application should register an activation
   72        * descriptor and export a remote object separately, so that exceptions
   73        * can be handled properly.
   74        *
   75        * <p>This method invokes the {@link
   76        * #exportObject(Remote,String,MarshalledObject,boolean,int)
   77        * exportObject} method with this object, and the specified location,
   78        * data, restart mode, and port.  Subsequent calls to {@link #getID}
   79        * will return the activation identifier returned from the call to
   80        * <code>exportObject</code>.
   81        *
   82        * @param location the location for classes for this object
   83        * @param data the object's initialization data
   84        * @param port the port on which the object is exported (an anonymous
   85        * port is used if port=0)
   86        * @param restart if true, the object is restarted (reactivated) when
   87        * either the activator is restarted or the object's activation group
   88        * is restarted after an unexpected crash; if false, the object is only
   89        * activated on demand.  Specifying <code>restart</code> to be
   90        * <code>true</code> does not force an initial immediate activation of
   91        * a newly registered object;  initial activation is lazy.
   92        * @exception ActivationException if object registration fails.
   93        * @exception RemoteException if either of the following fails:
   94        * a) registering the object with the activation system or b) exporting
   95        * the object to the RMI runtime.
   96        * @since 1.2
   97        **/
   98       protected Activatable(String location,
   99                             MarshalledObject<?> data,
  100                             boolean restart,
  101                             int port)
  102           throws ActivationException, RemoteException
  103       {
  104           super();
  105           id = exportObject(this, location, data, restart, port);
  106       }
  107   
  108       /**
  109        * Constructs an activatable remote object by registering
  110        * an activation descriptor (with the specified location, data, and
  111        * restart mode) for this object, and exporting the object with the
  112        * specified port, and specified client and server socket factories.
  113        *
  114        * <p><strong>Note:</strong> Using the <code>Activatable</code>
  115        * constructors that both register and export an activatable remote
  116        * object is strongly discouraged because the actions of registering
  117        * and exporting the remote object are <i>not</i> guaranteed to be
  118        * atomic.  Instead, an application should register an activation
  119        * descriptor and export a remote object separately, so that exceptions
  120        * can be handled properly.
  121        *
  122        * <p>This method invokes the {@link
  123        * #exportObject(Remote,String,MarshalledObject,boolean,int,RMIClientSocketFactory,RMIServerSocketFactory)
  124        * exportObject} method with this object, and the specified location,
  125        * data, restart mode, port, and client and server socket factories.
  126        * Subsequent calls to {@link #getID} will return the activation
  127        * identifier returned from the call to <code>exportObject</code>.
  128        *
  129        * @param location the location for classes for this object
  130        * @param data the object's initialization data
  131        * @param restart if true, the object is restarted (reactivated) when
  132        * either the activator is restarted or the object's activation group
  133        * is restarted after an unexpected crash; if false, the object is only
  134        * activated on demand.  Specifying <code>restart</code> to be
  135        * <code>true</code> does not force an initial immediate activation of
  136        * a newly registered object;  initial activation is lazy.
  137        * @param port the port on which the object is exported (an anonymous
  138        * port is used if port=0)
  139        * @param csf the client-side socket factory for making calls to the
  140        * remote object
  141        * @param ssf the server-side socket factory for receiving remote calls
  142        * @exception ActivationException if object registration fails.
  143        * @exception RemoteException if either of the following fails:
  144        * a) registering the object with the activation system or b) exporting
  145        * the object to the RMI runtime.
  146        * @since 1.2
  147        **/
  148       protected Activatable(String location,
  149                             MarshalledObject<?> data,
  150                             boolean restart,
  151                             int port,
  152                             RMIClientSocketFactory csf,
  153                             RMIServerSocketFactory ssf)
  154           throws ActivationException, RemoteException
  155       {
  156           super();
  157           id = exportObject(this, location, data, restart, port, csf, ssf);
  158       }
  159   
  160       /**
  161        * Constructor used to activate/export the object on a specified
  162        * port. An "activatable" remote object must have a constructor that
  163        * takes two arguments: <ul>
  164        * <li>the object's activation identifier (<code>ActivationID</code>), and
  165        * <li>the object's initialization data (a <code>MarshalledObject</code>).
  166        * </ul><p>
  167        *
  168        * A concrete subclass of this class must call this constructor when it is
  169        * <i>activated</i> via the two parameter constructor described above. As
  170        * a side-effect of construction, the remote object is "exported"
  171        * to the RMI runtime (on the specified <code>port</code>) and is
  172        * available to accept incoming calls from clients.
  173        *
  174        * @param id activation identifier for the object
  175        * @param port the port number on which the object is exported
  176        * @exception RemoteException if exporting the object to the RMI
  177        * runtime fails
  178        * @since 1.2
  179        */
  180       protected Activatable(ActivationID id, int port)
  181           throws RemoteException
  182       {
  183           super();
  184           this.id = id;
  185           exportObject(this, id, port);
  186       }
  187   
  188       /**
  189        * Constructor used to activate/export the object on a specified
  190        * port. An "activatable" remote object must have a constructor that
  191        * takes two arguments: <ul>
  192        * <li>the object's activation identifier (<code>ActivationID</code>), and
  193        * <li>the object's initialization data (a <code>MarshalledObject</code>).
  194        * </ul><p>
  195        *
  196        * A concrete subclass of this class must call this constructor when it is
  197        * <i>activated</i> via the two parameter constructor described above. As
  198        * a side-effect of construction, the remote object is "exported"
  199        * to the RMI runtime (on the specified <code>port</code>) and is
  200        * available to accept incoming calls from clients.
  201        *
  202        * @param id activation identifier for the object
  203        * @param port the port number on which the object is exported
  204        * @param csf the client-side socket factory for making calls to the
  205        * remote object
  206        * @param ssf the server-side socket factory for receiving remote calls
  207        * @exception RemoteException if exporting the object to the RMI
  208        * runtime fails
  209        * @since 1.2
  210        */
  211       protected Activatable(ActivationID id, int port,
  212                             RMIClientSocketFactory csf,
  213                             RMIServerSocketFactory ssf)
  214           throws RemoteException
  215       {
  216           super();
  217           this.id = id;
  218           exportObject(this, id, port, csf, ssf);
  219       }
  220   
  221       /**
  222        * Returns the object's activation identifier.  The method is
  223        * protected so that only subclasses can obtain an object's
  224        * identifier.
  225        * @return the object's activation identifier
  226        * @since 1.2
  227        */
  228       protected ActivationID getID() {
  229           return id;
  230       }
  231   
  232       /**
  233        * Register an object descriptor for an activatable remote
  234        * object so that is can be activated on demand.
  235        *
  236        * @param desc  the object's descriptor
  237        * @return the stub for the activatable remote object
  238        * @exception UnknownGroupException if group id in <code>desc</code>
  239        * is not registered with the activation system
  240        * @exception ActivationException if activation system is not running
  241        * @exception RemoteException if remote call fails
  242        * @since 1.2
  243        */
  244       public static Remote register(ActivationDesc desc)
  245           throws UnknownGroupException, ActivationException, RemoteException
  246       {
  247           // register object with activator.
  248           ActivationID id =
  249               ActivationGroup.getSystem().registerObject(desc);
  250           return sun.rmi.server.ActivatableRef.getStub(desc, id);
  251       }
  252   
  253       /**
  254        * Informs the system that the object with the corresponding activation
  255        * <code>id</code> is currently inactive. If the object is currently
  256        * active, the object is "unexported" from the RMI runtime (only if
  257        * there are no pending or in-progress calls)
  258        * so the that it can no longer receive incoming calls. This call
  259        * informs this VM's ActivationGroup that the object is inactive,
  260        * that, in turn, informs its ActivationMonitor. If this call
  261        * completes successfully, a subsequent activate request to the activator
  262        * will cause the object to reactivate. The operation may still
  263        * succeed if the object is considered active but has already
  264        * unexported itself.
  265        *
  266        * @param id the object's activation identifier
  267        * @return true if the operation succeeds (the operation will
  268        * succeed if the object in currently known to be active and is
  269        * either already unexported or is currently exported and has no
  270        * pending/executing calls); false is returned if the object has
  271        * pending/executing calls in which case it cannot be deactivated
  272        * @exception UnknownObjectException if object is not known (it may
  273        * already be inactive)
  274        * @exception ActivationException if group is not active
  275        * @exception RemoteException if call informing monitor fails
  276        * @since 1.2
  277        */
  278       public static boolean inactive(ActivationID id)
  279           throws UnknownObjectException, ActivationException, RemoteException
  280       {
  281           return ActivationGroup.currentGroup().inactiveObject(id);
  282       }
  283   
  284       /**
  285        * Revokes previous registration for the activation descriptor
  286        * associated with <code>id</code>. An object can no longer be
  287        * activated via that <code>id</code>.
  288        *
  289        * @param id the object's activation identifier
  290        * @exception UnknownObjectException if object (<code>id</code>) is unknown
  291        * @exception ActivationException if activation system is not running
  292        * @exception RemoteException if remote call to activation system fails
  293        * @since 1.2
  294        */
  295       public static void unregister(ActivationID id)
  296           throws UnknownObjectException, ActivationException, RemoteException
  297       {
  298           ActivationGroup.getSystem().unregisterObject(id);
  299       }
  300   
  301       /**
  302        * Registers an activation descriptor (with the specified location,
  303        * data, and restart mode) for the specified object, and exports that
  304        * object with the specified port.
  305        *
  306        * <p><strong>Note:</strong> Using this method (as well as the
  307        * <code>Activatable</code> constructors that both register and export
  308        * an activatable remote object) is strongly discouraged because the
  309        * actions of registering and exporting the remote object are
  310        * <i>not</i> guaranteed to be atomic.  Instead, an application should
  311        * register an activation descriptor and export a remote object
  312        * separately, so that exceptions can be handled properly.
  313        *
  314        * <p>This method invokes the {@link
  315        * #exportObject(Remote,String,MarshalledObject,boolean,int,RMIClientSocketFactory,RMIServerSocketFactory)
  316        * exportObject} method with the specified object, location, data,
  317        * restart mode, and port, and <code>null</code> for both client and
  318        * server socket factories, and then returns the resulting activation
  319        * identifier.
  320        *
  321        * @param obj the object being exported
  322        * @param location the object's code location
  323        * @param data the object's bootstrapping data
  324        * @param restart if true, the object is restarted (reactivated) when
  325        * either the activator is restarted or the object's activation group
  326        * is restarted after an unexpected crash; if false, the object is only
  327        * activated on demand.  Specifying <code>restart</code> to be
  328        * <code>true</code> does not force an initial immediate activation of
  329        * a newly registered object;  initial activation is lazy.
  330        * @param port the port on which the object is exported (an anonymous
  331        * port is used if port=0)
  332        * @return the activation identifier obtained from registering the
  333        * descriptor, <code>desc</code>, with the activation system
  334        * the wrong group
  335        * @exception ActivationException if activation group is not active
  336        * @exception RemoteException if object registration or export fails
  337        * @since 1.2
  338        **/
  339       public static ActivationID exportObject(Remote obj,
  340                                               String location,
  341                                               MarshalledObject<?> data,
  342                                               boolean restart,
  343                                               int port)
  344           throws ActivationException, RemoteException
  345       {
  346           return exportObject(obj, location, data, restart, port, null, null);
  347       }
  348   
  349       /**
  350        * Registers an activation descriptor (with the specified location,
  351        * data, and restart mode) for the specified object, and exports that
  352        * object with the specified port, and the specified client and server
  353        * socket factories.
  354        *
  355        * <p><strong>Note:</strong> Using this method (as well as the
  356        * <code>Activatable</code> constructors that both register and export
  357        * an activatable remote object) is strongly discouraged because the
  358        * actions of registering and exporting the remote object are
  359        * <i>not</i> guaranteed to be atomic.  Instead, an application should
  360        * register an activation descriptor and export a remote object
  361        * separately, so that exceptions can be handled properly.
  362        *
  363        * <p>This method first registers an activation descriptor for the
  364        * specified object as follows. It obtains the activation system by
  365        * invoking the method {@link ActivationGroup#getSystem
  366        * ActivationGroup.getSystem}.  This method then obtains an {@link
  367        * ActivationID} for the object by invoking the activation system's
  368        * {@link ActivationSystem#registerObject registerObject} method with
  369        * an {@link ActivationDesc} constructed with the specified object's
  370        * class name, and the specified location, data, and restart mode.  If
  371        * an exception occurs obtaining the activation system or registering
  372        * the activation descriptor, that exception is thrown to the caller.
  373        *
  374        * <p>Next, this method exports the object by invoking the {@link
  375        * #exportObject(Remote,ActivationID,int,RMIClientSocketFactory,RMIServerSocketFactory)
  376        * exportObject} method with the specified remote object, the
  377        * activation identifier obtained from registration, the specified
  378        * port, and the specified client and server socket factories.  If an
  379        * exception occurs exporting the object, this method attempts to
  380        * unregister the activation identifier (obtained from registration) by
  381        * invoking the activation system's {@link
  382        * ActivationSystem#unregisterObject unregisterObject} method with the
  383        * activation identifier.  If an exception occurs unregistering the
  384        * identifier, that exception is ignored, and the original exception
  385        * that occurred exporting the object is thrown to the caller.
  386        *
  387        * <p>Finally, this method invokes the {@link
  388        * ActivationGroup#activeObject activeObject} method on the activation
  389        * group in this VM with the activation identifier and the specified
  390        * remote object, and returns the activation identifier to the caller.
  391        *
  392        * @param obj the object being exported
  393        * @param location the object's code location
  394        * @param data the object's bootstrapping data
  395        * @param restart if true, the object is restarted (reactivated) when
  396        * either the activator is restarted or the object's activation group
  397        * is restarted after an unexpected crash; if false, the object is only
  398        * activated on demand.  Specifying <code>restart</code> to be
  399        * <code>true</code> does not force an initial immediate activation of
  400        * a newly registered object;  initial activation is lazy.
  401        * @param port the port on which the object is exported (an anonymous
  402        * port is used if port=0)
  403        * @param csf the client-side socket factory for making calls to the
  404        * remote object
  405        * @param ssf the server-side socket factory for receiving remote calls
  406        * @return the activation identifier obtained from registering the
  407        * descriptor with the activation system
  408        * @exception ActivationException if activation group is not active
  409        * @exception RemoteException if object registration or export fails
  410        * @since 1.2
  411        **/
  412       public static ActivationID exportObject(Remote obj,
  413                                               String location,
  414                                               MarshalledObject<?> data,
  415                                               boolean restart,
  416                                               int port,
  417                                               RMIClientSocketFactory csf,
  418                                               RMIServerSocketFactory ssf)
  419           throws ActivationException, RemoteException
  420       {
  421           ActivationDesc desc = new ActivationDesc(obj.getClass().getName(),
  422                                                    location, data, restart);
  423           /*
  424            * Register descriptor.
  425            */
  426           ActivationSystem system =  ActivationGroup.getSystem();
  427           ActivationID id = system.registerObject(desc);
  428   
  429           /*
  430            * Export object.
  431            */
  432           try {
  433               exportObject(obj, id, port, csf, ssf);
  434           } catch (RemoteException e) {
  435               /*
  436                * Attempt to unregister activation descriptor because export
  437                * failed and register/export should be atomic (see 4323621).
  438                */
  439               try {
  440                   system.unregisterObject(id);
  441               } catch (Exception ex) {
  442               }
  443               /*
  444                * Report original exception.
  445                */
  446               throw e;
  447           }
  448   
  449           /*
  450            * This call can't fail (it is a local call, and the only possible
  451            * exception, thrown if the group is inactive, will not be thrown
  452            * because the group is not inactive).
  453            */
  454           ActivationGroup.currentGroup().activeObject(id, obj);
  455   
  456           return id;
  457       }
  458   
  459       /**
  460        * Export the activatable remote object to the RMI runtime to make
  461        * the object available to receive incoming calls. The object is
  462        * exported on an anonymous port, if <code>port</code> is zero. <p>
  463        *
  464        * During activation, this <code>exportObject</code> method should
  465        * be invoked explicitly by an "activatable" object, that does not
  466        * extend the <code>Activatable</code> class. There is no need for objects
  467        * that do extend the <code>Activatable</code> class to invoke this
  468        * method directly because the object is exported during construction.
  469        *
  470        * @return the stub for the activatable remote object
  471        * @param obj the remote object implementation
  472        * @param id the object's  activation identifier
  473        * @param port the port on which the object is exported (an anonymous
  474        * port is used if port=0)
  475        * @exception RemoteException if object export fails
  476        * @since 1.2
  477        */
  478       public static Remote exportObject(Remote obj,
  479                                         ActivationID id,
  480                                         int port)
  481           throws RemoteException
  482       {
  483           return exportObject(obj, new ActivatableServerRef(id, port));
  484       }
  485   
  486       /**
  487        * Export the activatable remote object to the RMI runtime to make
  488        * the object available to receive incoming calls. The object is
  489        * exported on an anonymous port, if <code>port</code> is zero. <p>
  490        *
  491        * During activation, this <code>exportObject</code> method should
  492        * be invoked explicitly by an "activatable" object, that does not
  493        * extend the <code>Activatable</code> class. There is no need for objects
  494        * that do extend the <code>Activatable</code> class to invoke this
  495        * method directly because the object is exported during construction.
  496        *
  497        * @return the stub for the activatable remote object
  498        * @param obj the remote object implementation
  499        * @param id the object's  activation identifier
  500        * @param port the port on which the object is exported (an anonymous
  501        * port is used if port=0)
  502        * @param csf the client-side socket factory for making calls to the
  503        * remote object
  504        * @param ssf the server-side socket factory for receiving remote calls
  505        * @exception RemoteException if object export fails
  506        * @since 1.2
  507        */
  508       public static Remote exportObject(Remote obj,
  509                                         ActivationID id,
  510                                         int port,
  511                                         RMIClientSocketFactory csf,
  512                                         RMIServerSocketFactory ssf)
  513           throws RemoteException
  514       {
  515           return exportObject(obj, new ActivatableServerRef(id, port, csf, ssf));
  516       }
  517   
  518       /**
  519        * Remove the remote object, obj, from the RMI runtime. If
  520        * successful, the object can no longer accept incoming RMI calls.
  521        * If the force parameter is true, the object is forcibly unexported
  522        * even if there are pending calls to the remote object or the
  523        * remote object still has calls in progress.  If the force
  524        * parameter is false, the object is only unexported if there are
  525        * no pending or in progress calls to the object.
  526        *
  527        * @param obj the remote object to be unexported
  528        * @param force if true, unexports the object even if there are
  529        * pending or in-progress calls; if false, only unexports the object
  530        * if there are no pending or in-progress calls
  531        * @return true if operation is successful, false otherwise
  532        * @exception NoSuchObjectException if the remote object is not
  533        * currently exported
  534        * @since 1.2
  535        */
  536       public static boolean unexportObject(Remote obj, boolean force)
  537           throws NoSuchObjectException
  538       {
  539           return sun.rmi.transport.ObjectTable.unexportObject(obj, force);
  540       }
  541   
  542       /**
  543        * Exports the specified object using the specified server ref.
  544        */
  545       private static Remote exportObject(Remote obj, ActivatableServerRef sref)
  546           throws RemoteException
  547       {
  548           // if obj extends Activatable, set its ref.
  549           if (obj instanceof Activatable) {
  550               ((Activatable) obj).ref = sref;
  551   
  552           }
  553           return sref.exportObject(obj, null, false);
  554       }
  555   }

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