ClassicSIOProxy (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

## javacardx.framework
Class ClassicSIOProxy

    java.lang.Object
      javacardx.framework.ClassicSIOProxy

    @TransactionType(value=NOT_SUPPORTED)
    public abstract class ClassicSIOProxy

extends Object

This class must be subclassed by all Classic applet SIO synchronization proxies.

The Java Card RE uses SIO synchronization proxy classes to ensure that only one application thread is executing any classic application or classic library. An SIO synchronization proxy instance is substituted in place of the actual SIO instance of the classic application whenever it becomes accessible to an extended applet or a web application. This SIO synchronization proxy instance for an SIO instance of a classic application synchronizes with the singleton classic applet container mutex object (CLASSIC_APPLET_CONTAINER_MUTEX) before entering the SIO instance of the classic application.

Additionally, an SIO synchronization proxy instance is substituted in place of the actual SIO instance of the extended or web application whenever it becomes accessible to a classic application. This SIO synchronization proxy instance for an SIO instance of an extended applet or a web application ensures that any SIO instances of a classic application that are passed as a parameters to the extended applet or web application are subsitituted with suitable SIO synchronization proxy instances.

See Runtime Environment Specification for the Java Card Platform, Connected Edition, chapter 4 for details regarding SIO synchronization proxy classes.

Since:
  Java Card 3.0

Field Summary
`static Object` | `CLASSIC_APPLET_CONTAINER_MUTEX` Mutual exclusion lock object to be used to synchronize access to classic applications.

Constructor Summary
`ClassicSIOProxy()`

Method Summary
`Shareable` | `getSIO()` Returns the actual SIO instance associated with this SIO proxy object.
`protected Object` | `processParam(Object obj)` Process the object before passing as a parameter to the actual SIO method.
`protected Object` | `processReturn(Object obj)` Process the object returned from the actual SIO.
`void` | `setSIO(Shareable sio)` Sets the actual SIO instance to associate with this SIO proxy object.

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

Field Detail

### CLASSIC_APPLET_CONTAINER_MUTEX

    public static final Object CLASSIC_APPLET_CONTAINER_MUTEX

  Mutual exclusion lock object to be used to synchronize access to classic applications.

Constructor Detail

### ClassicSIOProxy

    public ClassicSIOProxy()

Method Detail

### getSIO

    public final Shareable getSIO()

  Returns the actual SIO instance associated with this SIO proxy object.

  Returns:
    the actual SIO instance
  Throws:
    `SecurityException` - if called from if called from the context of an extended applet or web application

### setSIO

    public final void setSIO(Shareable sio)

  Sets the actual SIO instance to associate with this SIO proxy object. The actual SIO instance can only be set once.

  Parameters:
    `sio` - the SIO instance
  Throws:
    `IllegalArgumentException` - if the parameter is null
    `IllegalStateException` - if the actual SIO instance has already been set
    `SecurityException` - if called from if called from the context of an extended applet or web application

### processParam

    protected final Object processParam(Object obj)
                                 throws ClassNotFoundException,
                                        InstantiationException

  Process the object before passing as a parameter to the actual SIO method. If the object is a classic SIO synchronization proxy then unwrap the actual SIO instance. If the object is an SIO instance but not an SIO synchronization proxy, then create a classic SIO synchronization proxy object. This method returns `null` if the input parameter is `null`. This method throws a `SecurityException` if the input parameter is an array of SIO instances. All other objects are returned unchanged.

  This method must be called by the proxy class to process each object parameter prior to delegating to the actual SIO instance method.

  To create a classic SIO synchronization proxy object, the Java Card RE must search for a suitable SIO proxy class for the specified SIO instance in the package of the class of the calling method. In that package, the Java Card RE must search for classes named Proxy1, Proxy2 .. It must pick the first proxy class which implements exactly the same set of Shareable interfaces that are implemented by the SIO instance. If an exact match is not found, it must pick the first proxy class which implements all the Shareable interfaces that are implemented by the SIO instance. The SIO synchronization proxy instance must be owned by the caller application context.

  Parameters:
    `obj` - the object that is being passed as a parameter to the actual SIO method
  Returns:
    the processed object suitable for passing as a parameter to the SIO method
  Throws:
    `ClassNotFoundException` - if classic proxy instantiation is required and no proxy class matches the set of Shareable interfaces implemented by the specified SIO instance
    `InstantiationException` - if classic proxy instantiation is required and an exception occured while instantiating the SIO Proxy
    `SecurityException` - if called from the context of an extended applet or web application or if the input parameter is an array of SIO instances

### processReturn

    protected final Object processReturn(Object obj)
                                  throws ClassNotFoundException,
                                         InstantiationException

  Process the object returned from the actual SIO. If the object is a classic SIO synchronization proxy then unwrap the actual SIO instance. If the object is an SIO instance but not an SIO synchronization proxy, then create a classic SIO synchronization proxy object. This method returns `null` if the input parameter is `null`. This method throws a `SecurityException` if the input parameter is an array of SIO instances. All other objects are returned unchanged.

  This method must be called by the proxy class to process each object returned from the delegated actual SIO instance method.

  To create a classic SIO synchronization proxy object, the Java Card RE must search for a suitable SIO proxy class for the specified SIO instance in the package of the class of the calling method. In that package, the Java Card RE must search for classes named Proxy1, Proxy2 .. It must pick the first proxy class which implements exactly the same set of Shareable interfaces that are implemented by the SIO instance. If an exact match is not found, it must pick the first proxy class which implements all the Shareable interfaces that are implemented by the SIO instance. The SIO synchronization proxy instance must be owned by the caller application context.

  Parameters:
    `obj` - the object that is being returned from the actual SIO method
  Returns:
    the processed object suitable for returning from the SIO method
  Throws:
    `ClassNotFoundException` - if classic proxy instantiation is required and no proxy class matches the set of Shareable interfaces implemented by the specified SIO instance
    `InstantiationException` - if classic proxy instantiation is required and an exception occured while instantiating the SIO Proxy
    `SecurityException` - if called from the context of an extended applet or web application or if the input parameter is an array of SIO instances

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.