ApplicationGroup (Java Card SPI, 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

## 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:

  - If the application being instantiated is an applet application, `initParams` must be of type `byte[]`. It will be passed as applet data in the `bArray` parameter of the `Applet.install(byte[], short, byte)` method.
  - If the application being instantiated is a web application, `initParams` must be of type `Hashtable<String, String>`. The name/value pairs it contains will be set as `ServletContext` init parameters. These parameters can be retrieved by the application using the `ServletContext.getInitParameter(java.lang.String)` method. The new set of init parameters, if defined, overrides the complete set of init parameters defined in the web application descriptor.

  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.

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.