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