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 26 package java.rmi.server; 27 28 import 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 */ 39 public 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 }