1/*
2 * Copyright (c) 1996, 2004, 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
26package java.rmi.server;
27
28import java.rmi.*;
29
30/**
31 * <code>RemoteRef</code> represents the handle for a remote object. A
32 * <code>RemoteStub</code> uses a remote reference to carry out a
33 * remote method invocation to a remote object.
34 *
35 * @author  Ann Wollrath
36 * @since   1.1
37 * @see     java.rmi.server.RemoteStub
38 */
39public interface RemoteRef extends java.io.Externalizable {
40
41    /** indicate compatibility with JDK 1.1.x version of class. */
42    static final long serialVersionUID = 3632638527362204081L;
43
44    /**
45     * Initialize the server package prefix: assumes that the
46     * implementation of server ref classes (e.g., UnicastRef,
47     * UnicastServerRef) are located in the package defined by the
48     * prefix.
49     */
50    final static String packagePrefix = "sun.rmi.server";
51
52    /**
53     * Invoke a method. This form of delegating method invocation
54     * to the reference allows the reference to take care of
55     * setting up the connection to the remote host, marshaling
56     * some representation for the method and parameters, then
57     * communicating the method invocation to the remote host.
58     * This method either returns the result of a method invocation
59     * on the remote object which resides on the remote host or
60     * throws a RemoteException if the call failed or an
61     * application-level exception if the remote invocation throws
62     * an exception.
63     *
64     * @param obj the object that contains the RemoteRef (e.g., the
65     *            RemoteStub for the object.
66     * @param method the method to be invoked
67     * @param params the parameter list
68     * @param opnum  a hash that may be used to represent the method
69     * @return result of remote method invocation
70     * @exception Exception if any exception occurs during remote method
71     * invocation
72     * @since 1.2
73     */
74    Object invoke(Remote obj,
75                  java.lang.reflect.Method method,
76                  Object[] params,
77                  long opnum)
78        throws Exception;
79
80    /**
81     * Creates an appropriate call object for a new remote method
82     * invocation on this object.  Passing operation array and index,
83     * allows the stubs generator to assign the operation indexes and
84     * interpret them. The remote reference may need the operation to
85     * encode in the call.
86     *
87     * @since 1.1
88     * @deprecated 1.2 style stubs no longer use this method. Instead of
89     * using a sequence of method calls on the stub's the remote reference
90     * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
91     * stub uses a single method, <code>invoke(Remote, Method, Object[],
92     * int)</code>, on the remote reference to carry out parameter
93     * marshalling, remote method executing and unmarshalling of the return
94     * value.
95     *
96     * @param obj remote stub through which to make call
97     * @param op array of stub operations
98     * @param opnum operation number
99     * @param hash stub/skeleton interface hash
100     * @return call object representing remote call
101     * @throws RemoteException if failed to initiate new remote call
102     * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
103     */
104    @Deprecated
105    RemoteCall newCall(RemoteObject obj, Operation[] op, int opnum, long hash)
106        throws RemoteException;
107
108    /**
109     * Executes the remote call.
110     *
111     * Invoke will raise any "user" exceptions which
112     * should pass through and not be caught by the stub.  If any
113     * exception is raised during the remote invocation, invoke should
114     * take care of cleaning up the connection before raising the
115     * "user" or remote exception.
116     *
117     * @since 1.1
118     * @deprecated 1.2 style stubs no longer use this method. Instead of
119     * using a sequence of method calls to the remote reference
120     * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
121     * stub uses a single method, <code>invoke(Remote, Method, Object[],
122     * int)</code>, on the remote reference to carry out parameter
123     * marshalling, remote method executing and unmarshalling of the return
124     * value.
125     *
126     * @param call object representing remote call
127     * @throws Exception if any exception occurs during remote method
128     * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
129     */
130    @Deprecated
131    void invoke(RemoteCall call) throws Exception;
132
133    /**
134     * Allows the remote reference to clean up (or reuse) the connection.
135     * Done should only be called if the invoke returns successfully
136     * (non-exceptionally) to the stub.
137     *
138     * @since 1.1
139     * @deprecated 1.2 style stubs no longer use this method. Instead of
140     * using a sequence of method calls to the remote reference
141     * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
142     * stub uses a single method, <code>invoke(Remote, Method, Object[],
143     * int)</code>, on the remote reference to carry out parameter
144     * marshalling, remote method executing and unmarshalling of the return
145     * value.
146     *
147     * @param call object representing remote call
148     * @throws RemoteException if remote error occurs during call cleanup
149     * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
150     */
151    @Deprecated
152    void done(RemoteCall call) throws RemoteException;
153
154    /**
155     * Returns the class name of the ref type to be serialized onto
156     * the stream 'out'.
157     * @param out the output stream to which the reference will be serialized
158     * @return the class name (without package qualification) of the reference
159     * type
160     * @since 1.1
161     */
162    String getRefClass(java.io.ObjectOutput out);
163
164    /**
165     * Returns a hashcode for a remote object.  Two remote object stubs
166     * that refer to the same remote object will have the same hash code
167     * (in order to support remote objects as keys in hash tables).
168     *
169     * @return remote object hashcode
170     * @see             java.util.Hashtable
171     * @since 1.1
172     */
173    int remoteHashCode();
174
175    /**
176     * Compares two remote objects for equality.
177     * Returns a boolean that indicates whether this remote object is
178     * equivalent to the specified Object. This method is used when a
179     * remote object is stored in a hashtable.
180     * @param   obj     the Object to compare with
181     * @return  true if these Objects are equal; false otherwise.
182     * @see             java.util.Hashtable
183     * @since 1.1
184     */
185    boolean remoteEquals(RemoteRef obj);
186
187    /**
188     * Returns a String that represents the reference of this remote
189     * object.
190     * @return string representing remote object reference
191     * @since 1.1
192     */
193    String remoteToString();
194
195}
196