javacardx.framework
Class ClassicSIOProxy

java.lang.Object
  extended by 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


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