com.sun.javacard.spi.cardmgmt
Interface ApplicationGroup

All Superinterfaces:
DeploymentUnit

public interface ApplicationGroup
extends DeploymentUnit

An ApplicationGroup object encapsulates the runtime characteristics of a group of application modules or of a standalone application module.

Application groups are composite applications, that is applications assembled from one or more tightly inter-operating component applications of the same type (meaning implementing the same application model) that have been deployed together as one unit.

Standalone application modules are the units of distribution and deployment of individual applications. Standalone application modules are treated as single-component application groups.

Classic applet-based applications can only be packaged as single-component application groups.

Component applications are identified within an application group with their module name (See Runtime Environment Specification for the Java Card Platform, Connected Edition, chapter 8 for details regarding the Runtime descriptor).

The unnamed single modules of standalone application modules are identified by the default name DEFAULT_MODULE_NAME, which corresponds to the empty-string "". This default name also identifies the first module in an application group.

An application group once loaded can be initialized and bound to a dedicated execution context (group context). All instances of its component applications share that same context and can therefore very effectively intercommunicate. They also share the same security policy (protection domain).

ApplicationGroup objects are permanent Java Card runtime environment Entry Point Objects.

Some operations on application groups are subject to permission checks.

Since:
Java Card 3.0
See Also:
DeploymentUnit, Application, ProtectionDomain, CredentialManager, CredentialManager.SecurityRequirements, CardManagementPermission, JCREPermission

Field Summary
static String DEFAULT_MODULE_NAME
          The default module name.
static String REMOVED_PARAMETER
          Special runtime parameter value that indicates that the corresponding runtime descriptor parameter must be removed from the runtime configuration.
static byte TYPE_CLASSIC_APPLET
          Classic applet application type.
static byte TYPE_EXTENDED_APPLET
          Extended applet application type.
static byte TYPE_WEB
          Web application type.
 
Fields inherited from interface com.sun.javacard.spi.cardmgmt.DeploymentUnit
APP_TYPE, LIB_TYPE
 
Method Summary
 Enumeration<String> getApplicationModuleNames()
          Returns an enumeration of this application group's application module names.
 Enumeration<Application> getApplications()
          Returns an enumeration of all the registered instances of this application group's component applications.
 CredentialManager getCredentialManager()
          Returns the credential manager assigned at initialization time to this application group.
 ProtectionDomain getProtectionDomain()
          Returns the protection domain assigned at initialization time to this application group.
 CredentialManager.SecurityRequirements getSecurityRequirements()
          Returns the security requirements assigned at initialization time to this application group.
 void init(ProtectionDomain protectionDomain, CredentialManager credentialManager, CredentialManager.SecurityRequirements securityRequirements)
          Initializes this application group with a protection domain, a credential manager and security requirements.
 Application newApplication(String moduleName, String declaredAppURI, String requestedAppURI, Hashtable<String,String> runtimeConfig, Object initParams)
          Creates a new instance of one of this application group's component applications.
 boolean unload(boolean forced)
          Attempts to unload this application group.
 
Methods inherited from interface com.sun.javacard.spi.cardmgmt.DeploymentUnit
getType
 

Field Detail

TYPE_CLASSIC_APPLET

static final byte TYPE_CLASSIC_APPLET
Classic applet application type.

See Also:
Constant Field Values

TYPE_EXTENDED_APPLET

static final byte TYPE_EXTENDED_APPLET
Extended applet application type.

See Also:
Constant Field Values

TYPE_WEB

static final byte TYPE_WEB
Web application type.

See Also:
Constant Field Values

DEFAULT_MODULE_NAME

static final String DEFAULT_MODULE_NAME
The default module name.

See Also:
Constant Field Values

REMOVED_PARAMETER

static final String REMOVED_PARAMETER
Special runtime parameter value that indicates that the corresponding runtime descriptor parameter must be removed from the runtime configuration.

See Also:
Constant Field Values
Method Detail

getApplications

Enumeration<Application> getApplications()
Returns an enumeration of all the registered instances of this application group's component applications.

Returns:
an enumeration of all the registered instances of this application group's component applications.
Throws:
IllegalStateException - if this application group was loaded but not yet initialized.

getApplicationModuleNames

Enumeration<String> getApplicationModuleNames()
Returns an enumeration of this application group's application module names.

Returns:
an enumeration of this application group's application module names.

getCredentialManager

CredentialManager getCredentialManager()
Returns the credential manager assigned at initialization time to this application group.

Returns:
the credential manager assigned at initialization time to this application group.
Throws:
SecurityException - if retrieving the credential manager of this application group is not granted.
IllegalStateException - if this application group was loaded but not yet initialized.

getSecurityRequirements

CredentialManager.SecurityRequirements getSecurityRequirements()
Returns the security requirements assigned at initialization time to this application group.

Returns:
the security requirements assigned at initialization time to this application group.
Throws:
SecurityException - if retrieving the security requirements of this application group is not granted.
IllegalStateException - if this application group was loaded but not yet initialized.

getProtectionDomain

ProtectionDomain getProtectionDomain()
Returns the protection domain assigned at initialization time to this application group.

Returns:
the protection domain assigned at initialization time to this application group.
Throws:
SecurityException - if retrieving the protection domain of this application group is not granted.
IllegalStateException - if this application group was loaded but not yet initialized.

init

void init(ProtectionDomain protectionDomain,
          CredentialManager credentialManager,
          CredentialManager.SecurityRequirements securityRequirements)
Initializes this application group with a protection domain, a credential manager and security requirements. When initialized, this application group is bound to a group context and is assigned the provided protection domain, credential manager and security requirements.

This method must call the ProtectionDomain.setApplicationGroup() method to assign the protection domain object to this application group.

Parameters:
protectionDomain - the protection domain to be assigned to this application group.
credentialManager - the credential manager to be assigned to this application group (may be null).
securityRequirements - the security requirements to be assigned to this application group (may be null).
Throws:
NullPointerException - if protectionDomain is null.
SecurityException - if the provide protection domain is not bound to a platform policy protection domain defined for this application type.
IllegalStateException - if this application group was already initialized or if the protection domain object has already been assigned to another context.

newApplication

Application newApplication(String moduleName,
                           String declaredAppURI,
                           String requestedAppURI,
                           Hashtable<String,String> runtimeConfig,
                           Object initParams)
Creates a new instance of one of this application group's component applications. When created the application instance will be passed the provided initialization parameters and will be registered with the provided application URI. The way the application instance is actually created, passed the initialization parameters and registered is application model-specific and may be handled by the container implementing the corresponding application model.

The runtimeConfig parameter can be used to pass new runtime parameters (as a set of name/value pairs) or runtime parameters that override the parameters with the same names in the runtime descriptor information of the component application to be instantiated. If a runtime parameter defined in the runtime descriptor is mapped to the special String token "<<REMOVED>>" (see REMOVED_PARAMETER) that runtime parameter is not passed to the application.
Runtime parameters that correspond to application properties can be retrieved by the application using the JCSystem.getAppProperty(java.lang.String, java.lang.String) method.

The initParams parameter can be used to pass application model-specific initialization parameters:

Parameters:
moduleName - the module name of the component application to be instantiated.
declaredAppURI - the default web application URI of the specified web module as declared in the runtime descriptor or the AID URI of the applet class within the specified applet module as declared the applet application deployment descriptor; or null when the default is assumed.
requestedAppURI - the web application URI to be used for registration of the created web application instance instead of the default web application URI of the specified web module as declared in the runtime descriptor or the AID URI to be used for registration of the created applet application instance instead of the AID URI of the applet class within the specified applet module as declared the applet application deployment descriptor; or null when the default is assumed.
runtimeConfig - additional or overriding runtime parameters; or null when all the default parameter values from the runtime descriptor are assumed.
initParams - the initialization parameters; or null (for a web application, all the default parameter values from the web deployment descriptor are then assumed).
Throws:
NullPointerException - if moduleName is null.
SecurityException -
  • if creating an application instance is not granted,
  • if runtimeConfig is not null but runtime parameter overriding is not permitted.
IllegalArgumentException -
  • if moduleName is not recognized.
  • if declaredAppURI is not recognized.
  • if requestedAppURI is not a well-formed application URI.
  • if requestedAppURI was already assigned or overlaps or is overlapped by an already assigned application URI.
  • if requestedAppURI is illegal - that is: it is in the platform or standard namespace.
IllegalStateException -
  • if this application group was loaded but not yet initialized.
  • if this component application is a web application and it was already instantiated (multi-instantiation is not supported for web applications).

unload

boolean unload(boolean forced)
Attempts to unload this application group.

If all the application instances of this application group have not yet been deleted, the unload must be denied.

If the unload is forced, all the application instances of this application group and the application group itself will be atomically deleted and unloaded, respectively.

If classes or objects from this application group or any of its application instances are still being referenced by other deployment units or application instances the unload must be denied.

Any failed attempt must roll back any partially completed unloading steps.

Specified by:
unload in interface DeploymentUnit
Parameters:
forced - whether not yet deleted application instances must first be deleted.
Returns:
true if the unload succeeded, false otherwise.
Throws:
SecurityException - if unloading a deployment unit is not granted.


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