ActivationDesc


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