ActivationID


1   /*
2    * @(#)ActivationID.java    1.28 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.io.IOException  ;
11  import java.io.InvalidObjectException  ;
12  import java.lang.reflect.InvocationHandler  ;
13  import java.lang.reflect.Proxy  ;
14  import java.rmi.MarshalledObject  ;
15  import java.rmi.Remote  ;
16  import java.rmi.RemoteException  ;
17  import java.rmi.UnmarshalException  ;
18  import java.rmi.server.RemoteObject  ;
19  import java.rmi.server.RemoteObjectInvocationHandler  ;
20  import java.rmi.server.RemoteRef  ;
21  import java.rmi.server.RemoteStub  ;
22  import java.rmi.server.UID  ;
23  
24  /**
25   * Activation makes use of special identifiers to denote remote
26   * objects that can be activated over time. An activation identifier
27   * (an instance of the class <code>ActivationID</code>) contains several
28   * pieces of information needed for activating an object:
29   * <ul>
30   * <li> a remote reference to the object's activator (a {@link
31   * java.rmi.server.RemoteRef RemoteRef}
32   * instance), and
33   * <li> a unique identifier (a {@link java.rmi.server.UID UID}
34   * instance) for the object. </ul> <p>
35   *
36   * An activation identifier for an object can be obtained by registering
37   * an object with the activation system. Registration is accomplished
38   * in a few ways: <ul>
39   * <li>via the <code>Activatable.register</code> method
40   * <li>via the first <code>Activatable</code> constructor (that takes
41   * three arguments and both registers and exports the object, and
42   * <li>via the first <code>Activatable.exportObject</code> method
43   * that takes the activation descriptor, object and port as arguments;
44   * this method both registers and exports the object. </ul>
45   *
46   * @author  Ann Wollrath
47   * @version 1.28, 03/12/19
48   * @see     Activatable
49   * @since   1.2
50   */
51  public class ActivationID implements java.io.Serializable   {
52      /**
53       * the object's activator 
54       */
55      private transient Activator   activator;
56  
57      /**
58       * the object's unique id 
59       */
60      private transient UID   uid = new UID  ();
61  
62      /** indicate compatibility with the Java 2 SDK v1.2 version of class */
63      private static final long serialVersionUID = -4608673054848209235L;
64  
65      /**
66       * The constructor for <code>ActivationID</code> takes a single
67       * argument, activator, that specifies a remote reference to the
68       * activator responsible for activating the object associated with
69       * this identifier. An instance of <code>ActivationID</code> is globally
70       * unique.
71       *
72       * @param activator reference to the activator responsible for
73       * activating the object
74       * @since 1.2
75       */
76      public ActivationID(Activator   activator) {
77      this.activator = activator;
78      }
79  
80      /**
81       * Activate the object for this id.
82       *
83       * @param force if true, forces the activator to contact the group
84       * when activating the object (instead of returning a cached reference);
85       * if false, returning a cached value is acceptable.
86       * @return the reference to the active remote object
87       * @exception ActivationException if activation fails
88       * @exception UnknownObjectException if the object is unknown
89       * @exception RemoteException if remote call fails
90       * @since 1.2
91       */
92      public Remote   activate(boolean force)
93      throws ActivationException  , UnknownObjectException  , RemoteException  
94      {
95      try {
96          MarshalledObject   mobj =
97          (MarshalledObject  ) activator.activate(this, force);
98          return (Remote  ) mobj.get();
99      } catch (RemoteException   e) {
100         throw e;
101     } catch (IOException   e) {
102         throw new UnmarshalException  ("activation failed", e);
103     } catch (ClassNotFoundException   e) {
104         throw new UnmarshalException  ("activation failed", e);
105     }
106     
107     }
108     
109     /**
110      * Returns a hashcode for the activation id.  Two identifiers that
111      * refer to the same remote object will have the same hash code.
112      *
113      * @see java.util.Hashtable
114      * @since 1.2
115      */
116     public int hashCode() {
117     return uid.hashCode();
118     }
119 
120     /**
121      * Compares two activation ids for content equality.
122      * Returns true if both of the following conditions are true:
123      * 1) the unique identifiers equivalent (by content), and
124      * 2) the activator specified in each identifier
125      *    refers to the same remote object.
126      *
127      * @param   obj the Object to compare with
128      * @return  true if these Objects are equal; false otherwise.
129      * @see     java.util.Hashtable
130      * @since 1.2
131      */
132     public boolean equals(Object   obj) {
133     if (obj instanceof ActivationID  ) {
134         ActivationID   id = (ActivationID  ) obj;
135         return (uid.equals(id.uid) && activator.equals(id.activator));
136     } else {
137         return false;
138     }
139     }
140     
141     /**
142      * <code>writeObject</code> for custom serialization.
143      *
144      * <p>This method writes this object's serialized form for
145      * this class as follows:
146      *
147      * <p>The <code>writeObject</code> method is invoked on
148      * <code>out</code> passing this object's unique identifier
149      * (a {@link java.rmi.server.UID UID} instance) as the argument.
150      *
151      * <p>Next, the {@link
152      * java.rmi.server.RemoteRef#getRefClass(java.io.ObjectOutput)
153      * getRefClass} method is invoked on the activator's
154      * <code>RemoteRef</code> instance to obtain its external ref
155      * type name.  Next, the <code>writeUTF</code> method is
156      * invoked on <code>out</code> with the value returned by
157      * <code>getRefClass</code>, and then the
158      * <code>writeExternal</code> method is invoked on the
159      * <code>RemoteRef</code> instance passing <code>out</code>
160      * as the argument.
161      *
162      * @serialData The serialized data for this class comprises a
163      * <code>java.rmi.server.UID</code> (written with
164      * <code>ObjectOutput.writeObject</code>) followed by the
165      * external ref type name of the activator's
166      * <code>RemoteRef</code> instance (a string written with
167      * <code>ObjectOutput.writeUTF</code>), followed by the
168      * external form of the <code>RemoteRef</code> instance as
169      * written by its <code>writeExternal</code> method.
170      *
171      * <p>The external ref type name of the 
172      * <code>RemoteRef</Code> instance is
173      * determined using the definitions of external ref type
174      * names specified in the {@link java.rmi.server.RemoteObject
175      * RemoteObject} <code>writeObject</code> method
176      * <b>serialData</b> specification.  Similarly, the data
177      * written by the <code>writeExternal</code> method and read
178      * by the <code>readExternal</code> method of
179      * <code>RemoteRef</code> implementation classes
180      * corresponding to each of the defined external ref type
181      * names is specified in the {@link
182      * java.rmi.server.RemoteObject RemoteObject}
183      * <code>writeObject</code> method <b>serialData</b>
184      * specification.
185      **/
186     private void writeObject(java.io.ObjectOutputStream   out)
187     throws IOException  , ClassNotFoundException  
188     {
189     out.writeObject(uid);
190 
191     RemoteRef   ref;
192     if (activator instanceof RemoteObject  ) {
193         ref = ((RemoteObject  ) activator).getRef();
194     } else if (Proxy.isProxyClass(activator.getClass())) {
195         InvocationHandler   handler = Proxy.getInvocationHandler(activator);
196         if (!(handler instanceof RemoteObjectInvocationHandler  )) {
197         throw new InvalidObjectException  (
198             "unexpected invocation handler");
199         }
200         ref = ((RemoteObjectInvocationHandler  ) handler).getRef();
201         
202     } else {
203         throw new InvalidObjectException  ("unexpected activator type");
204     }
205     out.writeUTF(ref.getRefClass(out));
206     ref.writeExternal(out);
207     }
208 
209     /**
210      * <code>readObject</code> for custom serialization.
211      *
212      * <p>This method reads this object's serialized form for this
213      * class as follows:
214      * 
215      * <p>The <code>readObject</code> method is invoked on
216      * <code>in</code> to read this object's unique identifier
217      * (a {@link java.rmi.server.UID UID} instance).
218      *
219      * <p>Next, the <code>readUTF</code> method is invoked on
220      * <code>in</code> to read the external ref type name of the
221      * <code>RemoteRef</code> instance for this object's
222      * activator.  Next, the <code>RemoteRef</code>
223      * instance is created of an implementation-specific class
224      * corresponding to the external ref type name (returned by
225      * <code>readUTF</code>), and the <code>readExternal</code>
226      * method is invoked on that <code>RemoteRef</code> instance
227      * to read the external form corresponding to the external
228      * ref type name.
229      *
230      * <p>Note: If the external ref type name is
231      * <code>"UnicastRef"</code>, <code>"UnicastServerRef"</code>,
232      * <code>"UnicastRef2"</code>, <code>"UnicastServerRef2"</code>,
233      * or <code>"ActivatableRef"</code>, a corresponding
234      * implementation-specific class must be found, and its
235      * <code>readExternal</code> method must read the serial data
236      * for that external ref type name as specified to be written
237      * in the <b>serialData</b> documentation for this class.
238      * If the external ref type name is any other string (of non-zero
239      * length), a <code>ClassNotFoundException</code> will be thrown,
240      * unless the implementation provides an implementation-specific
241      * class corresponding to that external ref type name, in which
242      * case the <code>RemoteRef</code> will be an instance of
243      * that implementation-specific class.
244      */
245     private void readObject(java.io.ObjectInputStream   in) 
246     throws IOException  , ClassNotFoundException  
247     {
248     uid = (UID  )in.readObject();
249     
250     try {
251         Class   refClass = Class.forName(RemoteRef.packagePrefix + "." +
252                        in.readUTF());
253         RemoteRef   ref = (RemoteRef  ) refClass.newInstance();
254         ref.readExternal(in);
255         activator = (Activator  )
256         Proxy.newProxyInstance(null,
257                        new Class  []{ Activator  .class },
258                        new RemoteObjectInvocationHandler  (ref));
259 
260     } catch (InstantiationException   e) {
261         throw (IOException  )
262         new InvalidObjectException  (
263             "Unable to create remote reference").initCause(e);
264     } catch (IllegalAccessException   e) {
265         throw (IOException  )
266         new InvalidObjectException  (
267             "Unable to create remote reference").initCause(e);
268     }
269     }
270 }
271
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags