1. /*
  2. * @(#)Activator.java 1.15 00/02/02
  3. *
  4. * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package java.rmi.activation;
  11. import java.rmi.MarshalledObject;
  12. import java.rmi.Remote;
  13. import java.rmi.RemoteException;
  14. import java.rmi.activation.UnknownObjectException;
  15. /**
  16. * The <code>Activator</code> facilitates remote object activation. A
  17. * "faulting" remote reference calls the activator's
  18. * <code>activate</code> method to obtain a "live" reference to a
  19. * "activatable" remote object. Upon receiving a request for activation,
  20. * the activator looks up the activation descriptor for the activation
  21. * identifier, <code>id</code>, determines the group in which the
  22. * object should be activated initiates object re-creation via the
  23. * group's <code>ActivationInstantiator</code> (via a call to the
  24. * <code>newInstance</code> method). The activator initiates the
  25. * execution of activation groups as necessary. For example, if an
  26. * activation group for a specific group identifier is not already
  27. * executing, the activator initiates the execution of a VM for the
  28. * group. <p>
  29. *
  30. * The <code>Activator</code> works closely with
  31. * <code>ActivationSystem</code>, which provides a means for registering
  32. * groups and objects within those groups, and <code>ActivationMonitor</code>,
  33. * which recives information about active and inactive objects and inactive
  34. * groups. <p>
  35. *
  36. * The activator is responsible for monitoring and detecting when
  37. * activation groups fail so that it can remove stale remote references
  38. * to groups and active object's within those groups.<p>
  39. *
  40. * @author Ann Wollrath
  41. * @version 1.15, 02/02/00
  42. * @see ActivationInstantiator
  43. * @see ActivationGroupDesc
  44. * @see ActivationGroupID
  45. * @since 1.2
  46. */
  47. public interface Activator extends Remote {
  48. /**
  49. * Activate the object associated with the activation identifier,
  50. * <code>id</code>. If the activator knows the object to be active
  51. * already, and <code>force</code> is false , the stub with a
  52. * "live" reference is returned immediately to the caller;
  53. * otherwise, if the activator does not know that corresponding
  54. * the remote object is active, the activator uses the activation
  55. * descriptor information (previously registered) to determine the
  56. * group (VM) in which the object should be activated. If an
  57. * <code>ActivationInstantiator</code> corresponding to the
  58. * object's group descriptor already exists, the activator invokes
  59. * the activation group's <code>newInstance</code> method passing
  60. * it the object's id and descriptor. <p>
  61. *
  62. * If the activation group for the object's group descriptor does
  63. * not yet exist, the activator starts an
  64. * <code>ActivationInstantiator</code> executing (by spawning a
  65. * child process, for example). When the activator receives the
  66. * activation group's call back (via the
  67. * <code>ActivationSystem</code>'s <code>activeGroup</code>
  68. * method) specifying the activation group's reference, the
  69. * activator can then invoke that activation instantiator's
  70. * <code>newInstance</code> method to forward each pending
  71. * activation request to the activation group and return the
  72. * result (a marshalled remote object reference, a stub) to the
  73. * caller.<p>
  74. *
  75. * Note that the activator receives a "marshalled" object instead of a
  76. * Remote object so that the activator does not need to load the
  77. * code for that object, or participate in distributed garbage
  78. * collection for that object. If the activator kept a strong
  79. * reference to the remote object, the activator would then
  80. * prevent the object from being garbage collected under the
  81. * normal distributed garbage collection mechanism. <p>
  82. *
  83. * @param id the activation identifier for the object being activated
  84. * @param force if true, the activator contacts the group to obtain
  85. * the remote object's reference; if false, returning the cached value
  86. * is allowed.
  87. * @return the remote object (a stub) in a marshalled form
  88. * @exception ActivationException if object activation fails
  89. * @exception UnknownObjectException if object is unknown (not registered)
  90. * @exception RemoteException if remote call fails
  91. * @since 1.2
  92. */
  93. public MarshalledObject activate(ActivationID id, boolean force)
  94. throws ActivationException, UnknownObjectException, RemoteException;
  95. }