RMIService (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.framework.service
Class RMIService

    java.lang.Object
      javacard.framework.service.BasicService
          javacard.framework.service.RMIService

All Implemented Interfaces:
  RemoteService, Service

    @TransactionType(value=SUPPORTS)
    public class RMIService

extends BasicService
implements RemoteService

An implementation of a service that is used to process Java Card platform RMI requests for remotely accessible objects.

Field Summary
`static byte` | `DEFAULT_RMI_INVOKE_INSTRUCTION` The default INS value (0x38) used for the remote method invocation command (INVOKE) in the Java Card platform RMI protocol.

Constructor Summary
`RMIService(Remote initialObject)` Creates a new `RMIService` and sets the specified remote object as the initial reference for the applet.

Method Summary
`boolean` | `processCommand(APDU apdu)` Processes the command within the `APDU` object.
`void` | `setInvokeInstructionByte(byte ins)` Defines the instruction byte to be used in place of `DEFAULT_RMI_INVOKE_INSTRUCTION` in the Java Card platform RMI protocol for the INVOKE commands used to access the `RMIService` for remote method invocations.

Methods inherited from class javacard.framework.service.BasicService
`fail, getCLA, getINS, getOutputLength, getP1, getP2, getStatusWord, isProcessed, processDataIn, processDataOut, receiveInData, selectingApplet, setOutputLength, setProcessed, setStatusWord, succeed, succeedWithStatusWord`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface javacard.framework.service.Service
`processDataIn, processDataOut`

Field Detail

### DEFAULT_RMI_INVOKE_INSTRUCTION

    public static final byte DEFAULT_RMI_INVOKE_INSTRUCTION

  The default INS value (0x38) used for the remote method invocation command (INVOKE) in the Java Card platform RMI protocol.

  See Also:
    Constant Field Values

Constructor Detail

### RMIService

    public RMIService(Remote initialObject)
               throws NullPointerException

  Creates a new `RMIService` and sets the specified remote object as the initial reference for the applet. The initial reference will be published to the client in response to the SELECT APDU command processed by this object.

  The `RMIService` instance may create session data to manage exported remote objects for the current applet session in `CLEAR_ON_DESELECT` transient space.

  Parameters:
    `initialObject` - the remotely accessible initial object
  Throws:
    `NullPointerException` - if the `initialObject` parameter is `null`

Method Detail

### setInvokeInstructionByte

    public void setInvokeInstructionByte(byte ins)

  Defines the instruction byte to be used in place of `DEFAULT_RMI_INVOKE_INSTRUCTION` in the Java Card platform RMI protocol for the INVOKE commands used to access the `RMIService` for remote method invocations.

  Note:

  - The new instruction byte goes into effect next time this `RMIService` instance processes an applet SELECT command. The Java Card platform RMI protocol until then is unchanged.

  Parameters:
    `ins` - the instruction byte

### processCommand

    public boolean processCommand(APDU apdu)

  Processes the command within the `APDU` object. When invoked, the APDU object should either be in `STATE_INITIAL` with the APDU buffer in the Init format or in `STATE_FULL_INCOMING` with the APDU buffer in the Input Ready format defined in `BasicService`.

  This method first checks if the command in the `APDU` object is a Java Card platform RMI access command. The Java Card platform RMI access commands currently defined are: Applet SELECT and INVOKE. If it is not a Java Card platform RMI access command, this method does nothing and returns false.

  If the command is a Java Card platform RMI access command, this method processes the command and generates the response to be returned to the terminal. For a detailed description of the APDU protocol used in Java Card platform RMI access commands please see the Remote Method Invocation Service chapter of Runtime Environment Specification, Java Card Platform, Classic Edition.

  Java Card platform RMI access commands are processed as follows:

  - An applet SELECT command results in a Java Card platform RMI information structure in FCI format containing the initial reference object as the response to be returned to the terminal.
  - An INVOKE command results in the following sequence -
  1. The remote object is located. A remote object is accessible only if it was returned by this `RMIService` instance and since that time some applet instance or the other from within the applet application group has been an active applet instance.
  2. The method of the object is identified
  3. Primitive input parameters are unmarshalled onto the stack. Array type input parameters are created as global arrays(See Runtime Environment Specification, Java Card Platform, Classic Edition) and references to these are pushed onto the stack.
  4. An INVOKEVIRTUAL bytecode to the remote method is simulated
  5. Upon return from the method, method return or exception information is marshalled from the stack as the response to be returned to the terminal

  After normal completion, this method returns `true` and the APDU object is in `STATE_OUTGOING` and the output response is in the APDU buffer in the Output Ready format defined in `BasicService`.

  Specified by:
    `processCommand` in interface `Service`
  Overrides:
    `processCommand` in class `BasicService`
  Parameters:
    `apdu` - the APDU object containing the command being processed.
  Returns:
    `true` if the command has been processed, `false` otherwise
  Throws:
    `ServiceException` - with the following reason codes:
    - `ServiceException.CANNOT_ACCESS_IN_COMMAND` if this is a Java Card platform RMI access command and the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING
    - `ServiceException.REMOTE_OBJECT_NOT_EXPORTED` if the remote method returned a remote object which has not been exported.
    `TransactionException` - with the following reason code:
    - `TransactionException.IN_PROGRESS` if this is a Java Card platform RMI INVOKE command and the remote method returned a remote object which has been exported within a transaction which is still in progress or if this is an applet SELECT command and the response information in the APDU buffer includes an initial reference object which has been exported within a transaction which is still in progress.
    `SecurityException` - if one of the following conditions is met:
    - if this is a Java Card platform RMI INVOKE command and a firewall security violation occurred while trying to simulate an INVOKEVIRTUAL bytecode on the remote object.
    - if internal storage in `CLEAR_ON_DESELECT` transient space is accessed when the currently active context is not the context of the currently selected applet.
    - if this is a Java Card platform RMI INVOKE command and the invoked remote method returns an object or throws an exception object which is not accessible in the context of the currently selected applet.
  See Also:
    `CardRemoteObject`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.