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.Remote; 30 import java.rmi.RemoteException; 31 import java.rmi.activation.UnknownObjectException; 32 33 /** 34 * The <code>Activator</code> facilitates remote object activation. A 35 * "faulting" remote reference calls the activator's 36 * <code>activate</code> method to obtain a "live" reference to a 37 * "activatable" remote object. Upon receiving a request for activation, 38 * the activator looks up the activation descriptor for the activation 39 * identifier, <code>id</code>, determines the group in which the 40 * object should be activated initiates object re-creation via the 41 * group's <code>ActivationInstantiator</code> (via a call to the 42 * <code>newInstance</code> method). The activator initiates the 43 * execution of activation groups as necessary. For example, if an 44 * activation group for a specific group identifier is not already 45 * executing, the activator initiates the execution of a VM for the 46 * group. <p> 47 * 48 * The <code>Activator</code> works closely with 49 * <code>ActivationSystem</code>, which provides a means for registering 50 * groups and objects within those groups, and <code>ActivationMonitor</code>, 51 * which recives information about active and inactive objects and inactive 52 * groups. <p> 53 * 54 * The activator is responsible for monitoring and detecting when 55 * activation groups fail so that it can remove stale remote references 56 * to groups and active object's within those groups.<p> 57 * 58 * @author Ann Wollrath 59 * @see ActivationInstantiator 60 * @see ActivationGroupDesc 61 * @see ActivationGroupID 62 * @since 1.2 63 */ 64 public interface Activator extends Remote { 65 /** 66 * Activate the object associated with the activation identifier, 67 * <code>id</code>. If the activator knows the object to be active 68 * already, and <code>force</code> is false , the stub with a 69 * "live" reference is returned immediately to the caller; 70 * otherwise, if the activator does not know that corresponding 71 * the remote object is active, the activator uses the activation 72 * descriptor information (previously registered) to determine the 73 * group (VM) in which the object should be activated. If an 74 * <code>ActivationInstantiator</code> corresponding to the 75 * object's group descriptor already exists, the activator invokes 76 * the activation group's <code>newInstance</code> method passing 77 * it the object's id and descriptor. <p> 78 * 79 * If the activation group for the object's group descriptor does 80 * not yet exist, the activator starts an 81 * <code>ActivationInstantiator</code> executing (by spawning a 82 * child process, for example). When the activator receives the 83 * activation group's call back (via the 84 * <code>ActivationSystem</code>'s <code>activeGroup</code> 85 * method) specifying the activation group's reference, the 86 * activator can then invoke that activation instantiator's 87 * <code>newInstance</code> method to forward each pending 88 * activation request to the activation group and return the 89 * result (a marshalled remote object reference, a stub) to the 90 * caller.<p> 91 * 92 * Note that the activator receives a "marshalled" object instead of a 93 * Remote object so that the activator does not need to load the 94 * code for that object, or participate in distributed garbage 95 * collection for that object. If the activator kept a strong 96 * reference to the remote object, the activator would then 97 * prevent the object from being garbage collected under the 98 * normal distributed garbage collection mechanism. <p> 99 * 100 * @param id the activation identifier for the object being activated 101 * @param force if true, the activator contacts the group to obtain 102 * the remote object's reference; if false, returning the cached value 103 * is allowed. 104 * @return the remote object (a stub) in a marshalled form 105 * @exception ActivationException if object activation fails 106 * @exception UnknownObjectException if object is unknown (not registered) 107 * @exception RemoteException if remote call fails 108 * @since 1.2 109 */ 110 public MarshalledObject<? extends Remote> activate(ActivationID id, 111 boolean force) 112 throws ActivationException, UnknownObjectException, RemoteException; 113 114 }