KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > rmi > server > RemoteRef


1 /*
2  * @(#)RemoteRef.java 1.23 04/05/18
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.server;
9
10 import java.rmi.*;
11
12 /**
13  * <code>RemoteRef</code> represents the handle for a remote object. A
14  * <code>RemoteStub</code> uses a remote reference to carry out a
15  * remote method invocation to a remote object.
16  *
17  * @version 1.23, 05/18/04
18  * @author Ann Wollrath
19  * @since JDK1.1
20  * @see java.rmi.server.RemoteStub
21  */

22 public interface RemoteRef extends java.io.Externalizable JavaDoc {
23
24     /** indicate compatibility with JDK 1.1.x version of class. */
25     static final long serialVersionUID = 3632638527362204081L;
26
27     /**
28      * Initialize the server package prefix: assumes that the
29      * implementation of server ref classes (e.g., UnicastRef,
30      * UnicastServerRef) are located in the package defined by the
31      * prefix.
32      */

33     final static String JavaDoc packagePrefix = "sun.rmi.server";
34
35     /**
36      * Invoke a method. This form of delegating method invocation
37      * to the reference allows the reference to take care of
38      * setting up the connection to the remote host, marshaling
39      * some representation for the method and parameters, then
40      * communicating the method invocation to the remote host.
41      * This method either returns the result of a method invocation
42      * on the remote object which resides on the remote host or
43      * throws a RemoteException if the call failed or an
44      * application-level exception if the remote invocation throws
45      * an exception.
46      *
47      * @param obj the object that contains the RemoteRef (e.g., the
48      * RemoteStub for the object.
49      * @param method the method to be invoked
50      * @param params the parameter list
51      * @param opnum a hash that may be used to represent the method
52      * @return result of remote method invocation
53      * @exception Exception if any exception occurs during remote method
54      * invocation
55      * @since 1.2
56      */

57     Object JavaDoc invoke(Remote obj,
58           java.lang.reflect.Method JavaDoc method,
59           Object JavaDoc[] params,
60           long opnum)
61     throws Exception JavaDoc;
62     
63     /**
64      * Creates an appropriate call object for a new remote method
65      * invocation on this object. Passing operation array and index,
66      * allows the stubs generator to assign the operation indexes and
67      * interpret them. The remote reference may need the operation to
68      * encode in the call.
69      *
70      * @since JDK1.1
71      * @deprecated 1.2 style stubs no longer use this method. Instead of
72      * using a sequence of method calls on the stub's the remote reference
73      * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
74      * stub uses a single method, <code>invoke(Remote, Method, Object[],
75      * int)</code>, on the remote reference to carry out parameter
76      * marshalling, remote method executing and unmarshalling of the return
77      * value.
78      *
79      * @param obj remote stub through which to make call
80      * @param op array of stub operations
81      * @param opnum operation number
82      * @param hash stub/skeleton interface hash
83      * @return call object representing remote call
84      * @throws RemoteException if failed to initiate new remote call
85      * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
86      */

87     @Deprecated JavaDoc
88     RemoteCall JavaDoc newCall(RemoteObject JavaDoc obj, Operation JavaDoc[] op, int opnum, long hash)
89     throws RemoteException;
90     
91     /**
92      * Executes the remote call.
93      *
94      * Invoke will raise any "user" exceptions which
95      * should pass through and not be caught by the stub. If any
96      * exception is raised during the remote invocation, invoke should
97      * take care of cleaning up the connection before raising the
98      * "user" or remote exception.
99      *
100      * @since JDK1.1
101      * @deprecated 1.2 style stubs no longer use this method. Instead of
102      * using a sequence of method calls to the remote reference
103      * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
104      * stub uses a single method, <code>invoke(Remote, Method, Object[],
105      * int)</code>, on the remote reference to carry out parameter
106      * marshalling, remote method executing and unmarshalling of the return
107      * value.
108      *
109      * @param call object representing remote call
110      * @throws Exception if any exception occurs during remote method
111      * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
112      */

113     @Deprecated JavaDoc
114     void invoke(RemoteCall JavaDoc call) throws Exception JavaDoc;
115     
116     /**
117      * Allows the remote reference to clean up (or reuse) the connection.
118      * Done should only be called if the invoke returns successfully
119      * (non-exceptionally) to the stub.
120      *
121      * @since JDK1.1
122      * @deprecated 1.2 style stubs no longer use this method. Instead of
123      * using a sequence of method calls to the remote reference
124      * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
125      * stub uses a single method, <code>invoke(Remote, Method, Object[],
126      * int)</code>, on the remote reference to carry out parameter
127      * marshalling, remote method executing and unmarshalling of the return
128      * value.
129      *
130      * @param call object representing remote call
131      * @throws RemoteException if remote error occurs during call cleanup
132      * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
133      */

134     @Deprecated JavaDoc
135     void done(RemoteCall JavaDoc call) throws RemoteException;
136     
137     /**
138      * Returns the class name of the ref type to be serialized onto
139      * the stream 'out'.
140      * @param out the output stream to which the reference will be serialized
141      * @return the class name (without package qualification) of the reference
142      * type
143      * @since JDK1.1
144      */

145     String JavaDoc getRefClass(java.io.ObjectOutput JavaDoc out);
146     
147     /**
148      * Returns a hashcode for a remote object. Two remote object stubs
149      * that refer to the same remote object will have the same hash code
150      * (in order to support remote objects as keys in hash tables).
151      *
152      * @return remote object hashcode
153      * @see java.util.Hashtable
154      * @since JDK1.1
155      */

156     int remoteHashCode();
157
158     /**
159      * Compares two remote objects for equality.
160      * Returns a boolean that indicates whether this remote object is
161      * equivalent to the specified Object. This method is used when a
162      * remote object is stored in a hashtable.
163      * @param obj the Object to compare with
164      * @return true if these Objects are equal; false otherwise.
165      * @see java.util.Hashtable
166      * @since JDK1.1
167      */

168     boolean remoteEquals(RemoteRef JavaDoc obj);
169
170     /**
171      * Returns a String that represents the reference of this remote
172      * object.
173      * @return string representing remote object reference
174      * @since JDK1.1
175      */

176     String JavaDoc remoteToString();
177     
178 }
179
Popular Tags