/*

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

}