javacard.framework.service
Class RMIService

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

All Implemented Interfaces:

RemoteService, Service

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

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 for the Java Card Platform.

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 package 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 for the Java Card Platform) 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