1. /*

  2.  * @(#)RemoteRef.java	1.18 00/02/02

  3.  *

  4.  * Copyright 1996-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.rmi.server;

  12. 

  13. import java.rmi.*;

  14. 

  15. /**

  16.  * <code>RemoteRef</code> represents the handle for a remote object. A

  17.  * <code>RemoteStub</code> uses a remote reference to carry out a

  18.  * remote method invocation to a remote object.

  19.  *

  20.  * @version 1.18, 02/02/00

  21.  * @author  Ann Wollrath

  22.  * @since   JDK1.1

  23.  * @see     java.rmi.server.RemoteStub

  24.  */

  25. public interface RemoteRef extends java.io.Externalizable {

  26. 

  27.     /** indicate compatibility with JDK 1.1.x version of class. */

  28.     static final long serialVersionUID = 3632638527362204081L;

  29. 

  30.     /**

  31.      * Initialize the server package prefix: assumes that the

  32.      * implementation of server ref classes (e.g., UnicastRef,

  33.      * UnicastServerRef) are located in the package defined by the

  34.      * prefix.

  35.      */

  36.     final static String packagePrefix = "sun.rmi.server";

  37. 

  38.     /**

  39.      * Invoke a method. This form of delegating method invocation

  40.      * to the reference allows the reference to take care of

  41.      * setting up the connection to the remote host, marshaling

  42.      * some representation for the method and parameters, then

  43.      * communicating the method invocation to the remote host.

  44.      * This method either returns the result of a method invocation

  45.      * on the remote object which resides on the remote host or

  46.      * throws a RemoteException if the call failed or an

  47.      * application-level exception if the remote invocation throws

  48.      * an exception.

  49.      *    

  50.      * @param obj the object that contains the RemoteRef (e.g., the

  51.      *            RemoteStub for the object.

  52.      * @param method the method to be invoked

  53.      * @param params the parameter list

  54.      * @param opnum  a hash that may be used to represent the method

  55.      * @return result of remote method invocation

  56.      * @exception Exception if any exception occurs during remote method

  57.      * invocation

  58.      * @since 1.2

  59.      */

  60.     Object invoke(Remote obj,

  61. 		  java.lang.reflect.Method method,

  62. 		  Object[] params,

  63. 		  long opnum)

  64. 	throws Exception;

  65.     

  66.     /**

  67.      * Creates an appropriate call object for a new remote method

  68.      * invocation on this object.  Passing operation array and index,

  69.      * allows the stubs generator to assign the operation indexes and

  70.      * interpret them. The remote reference may need the operation to

  71.      * encode in the call.

  72.      *

  73.      * @since JDK1.1

  74.      * @deprecated 1.2 style stubs no longer use this method. Instead of

  75.      * using a sequence of method calls on the stub's the remote reference

  76.      * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a

  77.      * stub uses a single method, <code>invoke(Remote, Method, Object[],

  78.      * int)</code>, on the remote reference to carry out parameter

  79.      * marshalling, remote method executing and unmarshalling of the return

  80.      * value.

  81.      *

  82.      * <p>1.2 stubs are generated using <code>rmic -v1.2</code>. By

  83.      * default, <code>rmic</code> generates stubs compatible with JDK1.1 and

  84.      * the Java 2 SDK. The compatible stubs can also be generated using

  85.      * <code>rmic -vcompat</code>.

  86.      * @param obj remote stub through which to make call

  87.      * @param op array of stub operations

  88.      * @param opnum operation number

  89.      * @param hash stub/skeleton interface hash

  90.      * @return call object representing remote call

  91.      * @throws RemoteException if failed to initiate new remote call

  92.      * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)

  93.      */

  94.     RemoteCall newCall(RemoteObject obj, Operation[] op, int opnum, long hash) 

  95. 	throws RemoteException;

  96.     

  97.     /**

  98.      * Executes the remote call.

  99.      * 

  100.      * Invoke will raise any "user" exceptions which

  101.      * should pass through and not be caught by the stub.  If any

  102.      * exception is raised during the remote invocation, invoke should

  103.      * take care of cleaning up the connection before raising the

  104.      * "user" or remote exception.

  105.      *

  106.      * @since JDK1.1

  107.      * @deprecated 1.2 style stubs no longer use this method. Instead of

  108.      * using a sequence of method calls to the remote reference

  109.      * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a

  110.      * stub uses a single method, <code>invoke(Remote, Method, Object[],

  111.      * int)</code>, on the remote reference to carry out parameter

  112.      * marshalling, remote method executing and unmarshalling of the return

  113.      * value.

  114.      *

  115.      * <p>1.2 stubs are generated using <code>rmic -v1.2</code>. By

  116.      * default, <code>rmic</code> generates stubs compatible with JDK1.1 and

  117.      * the Java 2 SDK. The compatible stubs can also be generated using

  118.      * <code>rmic -vcompat</code>.

  119.      * @param call object representing remote call

  120.      * @throws Exception if any exception occurs during remote method

  121.      * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)

  122.      */

  123.     void invoke(RemoteCall call) throws Exception;

  124.     

  125.     /**

  126.      * Allows the remote reference to clean up (or reuse) the connection.

  127.      * Done should only be called if the invoke returns successfully

  128.      * (non-exceptionally) to the stub.

  129.      *

  130.      * @since JDK1.1

  131.      * @deprecated 1.2 style stubs no longer use this method. Instead of

  132.      * using a sequence of method calls to the remote reference

  133.      * (<code>newCall</code>, <code>invoke</code>, and <code>done</code>), a

  134.      * stub uses a single method, <code>invoke(Remote, Method, Object[],

  135.      * int)</code>, on the remote reference to carry out parameter

  136.      * marshalling, remote method executing and unmarshalling of the return

  137.      * value.

  138.      *

  139.      * <p>1.2 stubs are generated using <code>rmic -v1.2</code>. By

  140.      * default, <code>rmic</code> generates stubs compatible with JDK1.1 and

  141.      * the Java 2 SDK. The compatible stubs can also be generated using <code>rmic

  142.      * -vcompat</code>.

  143.      * @param call object representing remote call

  144.      * @throws RemoteException if remote error occurs during call cleanup

  145.      * @see #invoke(Remote,java.lang.reflect.Method,Object[],long)

  146.      */

  147.     void done(RemoteCall call) throws RemoteException;

  148.     

  149.     /**

  150.      * Returns the class name of the ref type to be serialized onto

  151.      * the stream 'out'.

  152.      * @param out the output stream to which the reference will be serialized

  153.      * @return the class name (without package qualification) of the reference

  154.      * type

  155.      * @since JDK1.1

  156.      */

  157.     String getRefClass(java.io.ObjectOutput out);

  158.     

  159.     /**

  160.      * Returns a hashcode for a remote object.  Two remote object stubs

  161.      * that refer to the same remote object will have the same hash code

  162.      * (in order to support remote objects as keys in hash tables).

  163.      *

  164.      * @return remote object hashcode

  165.      * @see		java.util.Hashtable

  166.      * @since JDK1.1

  167.      */

  168.     int remoteHashCode();

  169. 

  170.     /**

  171.      * Compares two remote objects for equality.

  172.      * Returns a boolean that indicates whether this remote object is

  173.      * equivalent to the specified Object. This method is used when a

  174.      * remote object is stored in a hashtable.

  175.      * @param	obj	the Object to compare with

  176.      * @return	true if these Objects are equal; false otherwise.

  177.      * @see		java.util.Hashtable

  178.      * @since JDK1.1

  179.      */

  180.     boolean remoteEquals(RemoteRef obj);

  181. 

  182.     /**

  183.      * Returns a String that represents the reference of this remote

  184.      * object.

  185.      * @return string representing remote object reference

  186.      * @since JDK1.1

  187.      */

  188.     String remoteToString();

  189. 	

  190. }