Back to index...

	/*
	* 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();

	}

Back to index...