001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.jcrmi;
028:
029: import java.rmi.RemoteException;
030:
031: /**
032: * The interface <code>RemoteRef</code> represents the handle for
033: * a remote object. Each stub contains an instance of
034: * <code>RemoteRef</code>. <code>RemoteRef</code> contains the concrete
035: * representation
036: * of a reference. This remote reference is used to carry out remote
037: * calls on the remote object for which it is a reference.
038: *
039: */
040:
041: public interface RemoteRef {
042:
043: /**
044: * Invokes a remote method.
045: * <p>A remote method invocation consists of three steps:</p>
046: * <ol>
047: * <li>Marshall the representation for the method and parameters.</li>
048: * <li>Communicate the method invocation to the host and unmarshall the
049: * return value or exception returned.</li>
050: * <li>Return the result of the method invocation to the caller.</li>
051: * </ol>
052: *
053: * The remote method invoked on the card can throw an exception to
054: * signal that an unexpected condition has been detected.<p>
055: *
056: * If the exception thrown on the card is an exception defined in
057: * the Java Card 2.2 API, then the same exception is thrown to the
058: * stub method. The client can access the reason code associated
059: * with Java Card-specific exceptions using the standard
060: * <code>getReason()</code> method.<p>
061: *
062: * If the exception thrown on the card is a subclass of an exception
063: * defined in the Java Card 2.2 API, then the closest exception defined
064: * in the API (along with the reason code, if applicable) is
065: * thrown to the stub method. The detail message string of the
066: * exception object may indicate that exception subclass was thrown
067: * on the card.<p>
068: *
069: * Apart from the exceptions thrown by the remote method itself,
070: * errors during communication, marshalling, protocol handling,
071: * unmarshalling, stub object instantiation, and so on, related
072: * to the JCRMI method invocation, results in a
073: * <code>RemoteException</code> being thrown to the stub method.
074: *
075: * @param method simple (not fully qualified) name of the method
076: * followed by the method descriptor. Representation of a
077: * method descriptor is the same as that described in The
078: * Java Virtual Machine Specification (section 4.3.3)
079: * @param params the parameter list
080: * @return result of remote method invocation
081: * @exception java.lang.Exception if any exception occurs during
082: * the remote method invocation
083: */
084:
085: public Object invoke(String method, Object[] params)
086: throws Exception;
087:
088: /**
089: * Compares two remote references. Two remote references are equal
090: * if they refer to the same remote object.
091: * @param obj the Object to compare with
092: * @return true if these Objects are equal; false otherwise
093: */
094:
095: public boolean remoteEquals(RemoteRef obj);
096:
097: /**
098: * Returns a hashcode for a remote object. Two remote object stubs
099: * that refer to the same remote object will have the same hash code.
100: *
101: * @return the remote object hashcode
102: */
103: public int remoteHashCode();
104: }
|