/*
* Copyright (c) 1996, 2004, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.rmi.server;
import java.rmi.*;
/**
* <code>RemoteRef</code> represents the handle for a remote object. A
* <code>RemoteStub</code> uses a remote reference to carry out a
* remote method invocation to a remote object.
*
* @author Ann Wollrath
* @since JDK1.1
* @see java.rmi.server.RemoteStub
*/
public interface RemoteRef extends java.io.Externalizable {
/** indicate compatibility with JDK 1.1.x version of class. */
static final long serialVersionUID = 3632638527362204081L;
/**
* Initialize the server package prefix: assumes that the
* implementation of server ref classes (e.g., UnicastRef,
* UnicastServerRef) are located in the package defined by the
* prefix.
*/
final static String packagePrefix = "sun.rmi.server";
/**
* Invoke a method. This form of delegating method invocation
* to the reference allows the reference to take care of
* setting up the connection to the remote host, marshaling
* some representation for the method and parameters, then
* communicating the method invocation to the remote host.
* This method either returns the result of a method invocation
* on the remote object which resides on the remote host or
* throws a RemoteException if the call failed or an
* application-level exception if the remote invocation throws
* an exception.
*
* @param obj the object that contains the RemoteRef (e.g., the
* RemoteStub for the object.
* @param method the method to be invoked
* @param params the parameter list
* @param opnum a hash that may be used to represent the method
* @return result of remote method invocation
* @exception Exception if any exception occurs during remote method
* invocation
* @since 1.2
*/
Object invoke(Remote obj,
java.lang.reflect.Method method,
Object[] params,
long opnum)
throws Exception;
/**
* Creates an appropriate call object for a new remote method
* invocation on this object. Passing operation array and index,
* allows the stubs generator to assign the operation indexes and
* interpret them. The remote reference may need the operation to
* encode in the call.
*
* @since JDK1.1
* @deprecated 1.2 style stubs no longer use this method. Instead of
* using a sequence of method calls on the stub's the remote reference
* (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
* stub uses a single method, <code>invoke(Remote, Method, Object[],
* int)</code>, on the remote reference to carry out parameter
* marshalling, remote method executing and unmarshalling of the return
* value.
*
* @param obj remote stub through which to make call
* @param op array of stub operations
* @param opnum operation number
* @param hash stub/skeleton interface hash
* @return call object representing remote call
* @throws RemoteException if failed to initiate new remote call
* @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
*/
@Deprecated
RemoteCall newCall(RemoteObject obj, Operation[] op, int opnum, long hash)
throws RemoteException;
/**
* Executes the remote call.
*
* Invoke will raise any "user" exceptions which
* should pass through and not be caught by the stub. If any
* exception is raised during the remote invocation, invoke should
* take care of cleaning up the connection before raising the
* "user" or remote exception.
*
* @since JDK1.1
* @deprecated 1.2 style stubs no longer use this method. Instead of
* using a sequence of method calls to the remote reference
* (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
* stub uses a single method, <code>invoke(Remote, Method, Object[],
* int)</code>, on the remote reference to carry out parameter
* marshalling, remote method executing and unmarshalling of the return
* value.
*
* @param call object representing remote call
* @throws Exception if any exception occurs during remote method
* @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
*/
@Deprecated
void invoke(RemoteCall call) throws Exception;
/**
* Allows the remote reference to clean up (or reuse) the connection.
* Done should only be called if the invoke returns successfully
* (non-exceptionally) to the stub.
*
* @since JDK1.1
* @deprecated 1.2 style stubs no longer use this method. Instead of
* using a sequence of method calls to the remote reference
* (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a
* stub uses a single method, <code>invoke(Remote, Method, Object[],
* int)</code>, on the remote reference to carry out parameter
* marshalling, remote method executing and unmarshalling of the return
* value.
*
* @param call object representing remote call
* @throws RemoteException if remote error occurs during call cleanup
* @see #invoke(Remote,java.lang.reflect.Method,Object[],long)
*/
@Deprecated
void done(RemoteCall call) throws RemoteException;
/**
* Returns the class name of the ref type to be serialized onto
* the stream 'out'.
* @param out the output stream to which the reference will be serialized
* @return the class name (without package qualification) of the reference
* type
* @since JDK1.1
*/
String getRefClass(java.io.ObjectOutput out);
/**
* Returns a hashcode for a remote object. Two remote object stubs
* that refer to the same remote object will have the same hash code
* (in order to support remote objects as keys in hash tables).
*
* @return remote object hashcode
* @see java.util.Hashtable
* @since JDK1.1
*/
int remoteHashCode();
/**
* Compares two remote objects for equality.
* Returns a boolean that indicates whether this remote object is
* equivalent to the specified Object. This method is used when a
* remote object is stored in a hashtable.
* @param obj the Object to compare with
* @return true if these Objects are equal; false otherwise.
* @see java.util.Hashtable
* @since JDK1.1
*/
boolean remoteEquals(RemoteRef obj);
/**
* Returns a String that represents the reference of this remote
* object.
* @return string representing remote object reference
* @since JDK1.1
*/
String remoteToString();
}