/*
*
*
* Copyright 1990-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program 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.
*
* This program 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 at /legal/license.txt).
*
* 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 Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
package javax.microedition.jcrmi;
import java.rmi.RemoteException;
/**
* The interface <code>RemoteRef</code> represents the handle for
* a remote object. Each stub contains an instance of
* <code>RemoteRef</code>. <code>RemoteRef</code> contains the concrete
* representation
* of a reference. This remote reference is used to carry out remote
* calls on the remote object for which it is a reference.
*
*/
public interface RemoteRef {
/**
* Invokes a remote method.
* <p>A remote method invocation consists of three steps:</p>
* <ol>
* <li>Marshall the representation for the method and parameters.</li>
* <li>Communicate the method invocation to the host and unmarshall the
* return value or exception returned.</li>
* <li>Return the result of the method invocation to the caller.</li>
* </ol>
*
* The remote method invoked on the card can throw an exception to
* signal that an unexpected condition has been detected.<p>
*
* If the exception thrown on the card is an exception defined in
* the Java Card 2.2 API, then the same exception is thrown to the
* stub method. The client can access the reason code associated
* with Java Card-specific exceptions using the standard
* <code>getReason()</code> method.<p>
*
* If the exception thrown on the card is a subclass of an exception
* defined in the Java Card 2.2 API, then the closest exception defined
* in the API (along with the reason code, if applicable) is
* thrown to the stub method. The detail message string of the
* exception object may indicate that exception subclass was thrown
* on the card.<p>
*
* Apart from the exceptions thrown by the remote method itself,
* errors during communication, marshalling, protocol handling,
* unmarshalling, stub object instantiation, and so on, related
* to the JCRMI method invocation, results in a
* <code>RemoteException</code> being thrown to the stub method.
*
* @param method simple (not fully qualified) name of the method
* followed by the method descriptor. Representation of a
* method descriptor is the same as that described in The
* Java Virtual Machine Specification (section 4.3.3)
* @param params the parameter list
* @return result of remote method invocation
* @exception java.lang.Exception if any exception occurs during
* the remote method invocation
*/
public Object invoke(String method, Object[] params) throws Exception;
/**
* Compares two remote references. Two remote references are equal
* if they refer to the same remote object.
* @param obj the Object to compare with
* @return true if these Objects are equal; false otherwise
*/
public boolean remoteEquals(RemoteRef obj);
/**
* Returns a hashcode for a remote object. Two remote object stubs
* that refer to the same remote object will have the same hash code.
*
* @return the remote object hashcode
*/
public int remoteHashCode();
}