JSR 88 (Maintenance Release)


    1. Introduction

This JSR 88 Maintenance release document outlines the changes necessary to support tools and application server integration with Java EE 5 features.

    2. Proposed Changes

      Annotations impact

As Java EE applications can now express their nature or their dependencies through standard java annotations, the existence of xml deployment descriptors is now optional in deployment archives. The possibility of providing partial XML deployment descriptors which completes or overrides annotations also complicates how deployment information can be represented in Java EE 5.

Moreover, when using the current JSR88 APIs, standard deployment information was mainly described by the interfaces in the javax.enterprise.deploy.model package. These interfaces (mainly DeployableObject and DDBean) closely bind deployment descriptors to XML by the use of XPath to identify them. Deployment information changes are represented with events containing XPath values identifying the changed descriptors.

In Java EE 5, annotations cannot be represented with such XPath values, hence the necessity for the tools to either translate such annotations so the current SPI between tools and application servers can be used as it is or come up with new interfaces all together. To keep the plugins as simple as possible, we would like to push the complexity on the hosting tool. We therefore require that tools merge the java annotations and optional partial or complete deployment descriptors into a model which will support XPath queries.

Some tools may choose to translate the annotations into XML then process the optional xml deployment descriptors to have what is called in the Java EE platform specification a "full" XML deployment descriptor. Once this "full" XML deployment descriptors is calculated, current APIs can be used as is. Other tools may choose a more dynamic approach of translating annotation into XPath when necessary.

Update to paragraph 3.1 of the JSR88 specification 1.1 : javax.enterprise.deploy.model interfaces implementation provided by the Tool MUST provide access to the full deployment descriptors irrespective of their initial representation : annotations, xml or a combination of both.

      API changes


With the introduction of descriptor-less archives, the following API on javax.enterprise.deploy.spi.DeploymentManager

public ProgressObject distribute(Target[] targetList,
                                 InputStream moduleArchive,
                                 InputStream deploymentPlan)
                          throws IllegalStateException

will not allow the implementation to successfully determine the type of the archive. For instance, it is impossible to differentiate an .ear file from a .jar file (with some libraries at the top level). Therefore we propose to deprecate the above API for the following new API :

public ProgressObject distribute(Target[] targetList,
                                 ModuleType type,
                                 InputStream moduleArchive,
                                 InputStream deploymentPlan)
                          throws IllegalStateException

Please note that the java.io.File version does not carry the same issues since the extension of the file is available to the implementation and can be used to successfully determine the archive type. All Java EE 5 product provider MUST implement the new distribute method with the same responsibilities as described in paragraph 4.1 of the JSR88 Specification Version 1.1

    3. Contact Info


Contact jerome.dochez@sun.com for comments.

    4. Changed javadocs


javax.enterprise.deploy.spi
Interface DeploymentManager

public interface DeploymentManager

The DeploymentManager object provides the core set of functions a J2EE platform must provide for J2EE application deployment. It provides server related information, such as, a list of deployment targets, and vendor unique runtime configuration information.

Method Summary
 DeploymentConfiguration createConfiguration(javax.enterprise.deploy.model.DeployableObject dObj)
          Retrieve the object that provides server-specific deployment configuration information for the J2EE deployable component.
 javax.enterprise.deploy.spi.status.ProgressObject distribute(Target[] targetList, java.io.File moduleArchive, java.io.File deploymentPlan)
          The distribute method performs three tasks; it validates the deployment configuration data, generates all container specific classes and interfaces, and moves the fully baked archive to the designated deployment targets.
 javax.enterprise.deploy.spi.status.ProgressObject distribute(Target[] targetList, java.io.InputStream moduleArchive, java.io.InputStream deploymentPlan)
          Deprecated. as of Java EE 5, replaced with distribute(Target[], ModuleType, InputStream, InputStream)
 javax.enterprise.deploy.spi.status.ProgressObject distribute(Target[] targetList, javax.enterprise.deploy.shared.ModuleType type, java.io.InputStream moduleArchive, java.io.InputStream deploymentPlan)
          The distribute method performs three tasks; it validates the deployment configuration data, generates all container specific classes and interfaces, and moves the fully baked archive to the designated deployment targets.
 TargetModuleID[] getAvailableModules(javax.enterprise.deploy.shared.ModuleType moduleType, Target[] targetList)
          Retrieve the list of all J2EE application modules running or not running on the identified targets.
 java.util.Locale getCurrentLocale()
          Returns the active locale this implementation of javax.enterprise.deploy.spi subpackages is running.
 javax.enterprise.deploy.shared.DConfigBeanVersionType getDConfigBeanVersion()
          Returns the J2EE platform version number for which the configuration beans are provided.
 java.util.Locale getDefaultLocale()
          Returns the default locale supported by this implementation of javax.enterprise.deploy.spi subpackages.
 TargetModuleID[] getNonRunningModules(javax.enterprise.deploy.shared.ModuleType moduleType, Target[] targetList)
          Retrieve the list of J2EE application modules distributed to the identified targets and that are currently not running on the associated server or servers.
 TargetModuleID[] getRunningModules(javax.enterprise.deploy.shared.ModuleType moduleType, Target[] targetList)
          Retrieve the list of J2EE application modules distributed to the identified targets and that are currently running on the associated server or servers.
 java.util.Locale[] getSupportedLocales()
          Returns an array of supported locales for this implementation.
 Target[] getTargets()
          Retrieve the list of deployment targets supported by this DeploymentManager.
 boolean isDConfigBeanVersionSupported(javax.enterprise.deploy.shared.DConfigBeanVersionType version)
          Returns 'true' if the configuration beans support the J2EE platform version specified.
 boolean isLocaleSupported(java.util.Locale locale)
          Reports if this implementation supports the designated locale.
 boolean isRedeploySupported()
          This method designates whether this platform vendor provides application redeployment functionality.
 javax.enterprise.deploy.spi.status.ProgressObject redeploy(TargetModuleID[] moduleIDList, java.io.File moduleArchive, java.io.File deploymentPlan)
          (optional) The redeploy method provides a means for updating currently deployed J2EE applications.
 javax.enterprise.deploy.spi.status.ProgressObject redeploy(TargetModuleID[] moduleIDList, java.io.InputStream moduleArchive, java.io.InputStream deploymentPlan)
          (optional) The redeploy method provides a means for updating currently deployed J2EE applications.
 void release()
          The release method is the mechanism by which the tool signals to the DeploymentManager that the tool does not need it to continue running connected to the platform.
 void setDConfigBeanVersion(javax.enterprise.deploy.shared.DConfigBeanVersionType version)
          Set the configuration beans to be used to the J2EE platform version specificed.
 void setLocale(java.util.Locale locale)
          Set the active locale for this implementation of javax.enterprise.deploy.spi subpackages to run.
 javax.enterprise.deploy.spi.status.ProgressObject start(TargetModuleID[] moduleIDList)
          Start the application running.
 javax.enterprise.deploy.spi.status.ProgressObject stop(TargetModuleID[] moduleIDList)
          Stop the application running.
 javax.enterprise.deploy.spi.status.ProgressObject undeploy(TargetModuleID[] moduleIDList)
          Remove the application from the target server.
 

Method Detail

getTargets

Target[] getTargets()
                    throws java.lang.IllegalStateException
Retrieve the list of deployment targets supported by this DeploymentManager.

Returns:
A list of deployment Target designators the user may select for application deployment or 'null' if there are none.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.

getRunningModules

TargetModuleID[] getRunningModules(javax.enterprise.deploy.shared.ModuleType moduleType,
                                   Target[] targetList)
                                   throws javax.enterprise.deploy.spi.exceptions.TargetException,
                                          java.lang.IllegalStateException
Retrieve the list of J2EE application modules distributed to the identified targets and that are currently running on the associated server or servers.

Parameters:
moduleType - A predefined designator for a J2EE module type.
targetList - A list of deployment Target designators the user wants checked for module run status.
Returns:
An array of TargetModuleID objects representing the running modules or 'null' if there are none.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.
javax.enterprise.deploy.spi.exceptions.TargetException - An invalid Target designator encountered.

getNonRunningModules

TargetModuleID[] getNonRunningModules(javax.enterprise.deploy.shared.ModuleType moduleType,
                                      Target[] targetList)
                                      throws javax.enterprise.deploy.spi.exceptions.TargetException,
                                             java.lang.IllegalStateException
Retrieve the list of J2EE application modules distributed to the identified targets and that are currently not running on the associated server or servers.

Parameters:
moduleType - A predefined designator for a J2EE module type.
targetList - A list of deployment Target designators the user wants checked for module not running status.
Returns:
An array of TargetModuleID objects representing the non-running modules or 'null' if there are none.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.
javax.enterprise.deploy.spi.exceptions.TargetException - An invalid Target designator encountered.

getAvailableModules

TargetModuleID[] getAvailableModules(javax.enterprise.deploy.shared.ModuleType moduleType,
                                     Target[] targetList)
                                     throws javax.enterprise.deploy.spi.exceptions.TargetException,
                                            java.lang.IllegalStateException
Retrieve the list of all J2EE application modules running or not running on the identified targets.

Parameters:
moduleType - A predefined designator for a J2EE module type.
targetList - A list of deployment Target designators the user wants checked for module not running status.
Returns:
An array of TargetModuleID objects representing all deployed modules running or not or 'null' if there are no deployed modules.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.
javax.enterprise.deploy.spi.exceptions.TargetException - An invalid Target designator encountered.

createConfiguration

DeploymentConfiguration createConfiguration(javax.enterprise.deploy.model.DeployableObject dObj)
                                            throws javax.enterprise.deploy.spi.exceptions.InvalidModuleException
Retrieve the object that provides server-specific deployment configuration information for the J2EE deployable component.

Parameters:
dObj - An object representing a J2EE deployable component.
Throws:
javax.enterprise.deploy.spi.exceptions.InvalidModuleException - The DeployableObject is an unknown or unsupport component for this configuration tool.

distribute

javax.enterprise.deploy.spi.status.ProgressObject distribute(Target[] targetList,
                                                             java.io.File moduleArchive,
                                                             java.io.File deploymentPlan)
                                                             throws java.lang.IllegalStateException
The distribute method performs three tasks; it validates the deployment configuration data, generates all container specific classes and interfaces, and moves the fully baked archive to the designated deployment targets.

Parameters:
targetList - A list of server targets the user is specifying this application be deployed to.
moduleArchive - The file name of the application archive to be disrtibuted.
deploymentPlan - The XML file containing the runtime configuration information associated with this application archive.
Returns:
ProgressObject an object that tracks and reports the status of the distribution process.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.

distribute

javax.enterprise.deploy.spi.status.ProgressObject distribute(Target[] targetList,
                                                             java.io.InputStream moduleArchive,
                                                             java.io.InputStream deploymentPlan)
                                                             throws java.lang.IllegalStateException
Deprecated. as of Java EE 5, replaced with distribute(Target[], ModuleType, InputStream, InputStream)

The distribute method performs three tasks; it validates the deployment configuration data, generates all container specific classes and interfaces, and moves the fully baked archive to the designated deployment targets.

Parameters:
targetList - A list of server targets the user is specifying this application be deployed to.
moduleArchive - The input stream containing the application archive to be disrtibuted.
deploymentPlan - The input stream containing the deployment configuration information associated with this application archive.
Returns:
ProgressObject an object that tracks and reports the status of the distribution process.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.

distribute

javax.enterprise.deploy.spi.status.ProgressObject distribute(Target[] targetList,
                                                             javax.enterprise.deploy.shared.ModuleType type,
                                                             java.io.InputStream moduleArchive,
                                                             java.io.InputStream deploymentPlan)
                                                             throws java.lang.IllegalStateException
The distribute method performs three tasks; it validates the deployment configuration data, generates all container specific classes and interfaces, and moves the fully baked archive to the designated deployment targets.

Parameters:
targetList - A list of server targets the user is specifying this application be deployed to.
moduleType - The module type of this application archive.
moduleArchive - The input stream containing the application archive to be disrtibuted.
deploymentPlan - The input stream containing the deployment configuration information associated with this application archive.
Returns:
ProgressObject an object that tracks and reports the status of the distribution process.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.

start

javax.enterprise.deploy.spi.status.ProgressObject start(TargetModuleID[] moduleIDList)
                                                        throws java.lang.IllegalStateException
Start the application running.

Only the TargetModuleIDs which represent a root module are valid for being started. A root TargetModuleID has no parent. A TargetModuleID with a parent can not be individually started. A root TargetModuleID module and all its child modules will be started.

Parameters:
moduleIDList - A array of TargetModuleID objects representing the modules to be started.
Returns:
ProgressObject an object that tracks and reports the status of the start operation.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.

stop

javax.enterprise.deploy.spi.status.ProgressObject stop(TargetModuleID[] moduleIDList)
                                                       throws java.lang.IllegalStateException
Stop the application running.

Only the TargetModuleIDs which represent a root module are valid for being stopped. A root TargetModuleID has no parent. A TargetModuleID with a parent can not be individually stopped. A root TargetModuleID module and all its child modules will be stopped.

Parameters:
moduleIDList - A array of TargetModuleID objects representing the modules to be stopped.
Returns:
ProgressObject an object that tracks and reports the status of the stop operation.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.

undeploy

javax.enterprise.deploy.spi.status.ProgressObject undeploy(TargetModuleID[] moduleIDList)
                                                           throws java.lang.IllegalStateException
Remove the application from the target server.

Only the TargetModuleIDs which represent a root module are valid for undeployment. A root TargetModuleID has no parent. A TargetModuleID with a parent can not be undeployed. A root TargetModuleID module and all its child modules will be undeployed. The root TargetModuleID module and all its child modules must stopped before they can be undeployed.

Parameters:
moduleIDList - An array of TargetModuleID objects representing the root modules to be stopped.
Returns:
ProgressObject an object that tracks and reports the status of the stop operation.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.

isRedeploySupported

boolean isRedeploySupported()
This method designates whether this platform vendor provides application redeployment functionality. A value of true means it is supported. False means it is not.

Returns:
A value of true means redeployment is supported by this vendor's DeploymentManager. False means it is not.

redeploy

javax.enterprise.deploy.spi.status.ProgressObject redeploy(TargetModuleID[] moduleIDList,
                                                           java.io.File moduleArchive,
                                                           java.io.File deploymentPlan)
                                                           throws java.lang.UnsupportedOperationException,
                                                                  java.lang.IllegalStateException
(optional) The redeploy method provides a means for updating currently deployed J2EE applications. This is an optional method for vendor implementation. Redeploy replaces a currently deployed application with an updated version. The runtime configuration information for the updated application must remain identical to the application it is updating. When an application update is redeployed, all existing client connections to the original running application must not be disrupted; new clients will connect to the application update. This operation is valid for TargetModuleIDs that represent a root module. A root TargetModuleID has no parent. A root TargetModuleID module and all its child modules will be redeployed. A child TargetModuleID module cannot be individually redeployed. The redeploy operation is complete only when this action for all the modules has completed.

Parameters:
moduleIDList - An array of designators of the applications to be updated.
moduleArchive - The file name of the application archive to be disrtibuted.
deploymentPlan - The deployment configuration information associated with this application archive.
Returns:
ProgressObject an object that tracks and reports the status of the redeploy operation.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.
java.lang.UnsupportedOperationException - this optional command is not supported by this implementation.

redeploy

javax.enterprise.deploy.spi.status.ProgressObject redeploy(TargetModuleID[] moduleIDList,
                                                           java.io.InputStream moduleArchive,
                                                           java.io.InputStream deploymentPlan)
                                                           throws java.lang.UnsupportedOperationException,
                                                                  java.lang.IllegalStateException
(optional) The redeploy method provides a means for updating currently deployed J2EE applications. This is an optional method for vendor implementation. Redeploy replaces a currently deployed application with an updated version. The runtime configuration information for the updated application must remain identical to the application it is updating. When an application update is redeployed, all existing client connections to the original running application must not be disrupted; new clients will connect to the application update. This operation is valid for TargetModuleIDs that represent a root module. A root TargetModuleID has no parent. A root TargetModuleID module and all its child modules will be redeployed. A child TargetModuleID module cannot be individually redeployed. The redeploy operation is complete only when this action for all the modules has completed.

Parameters:
moduleIDList - An array of designators of the applications to be updated.
moduleArchive - The input stream containing the application archive to be disrtibuted.
deploymentPlan - The input stream containing the runtime configuration information associated with this application archive.
Returns:
ProgressObject an object that tracks and reports the status of the redeploy operation.
Throws:
java.lang.IllegalStateException - is thrown when the method is called when running in disconnected mode.
java.lang.UnsupportedOperationException - this optional command is not supported by this implementation.

release

void release()
The release method is the mechanism by which the tool signals to the DeploymentManager that the tool does not need it to continue running connected to the platform. The tool may be signaling it wants to run in a disconnected mode or it is planning to shutdown. When release is called the DeploymentManager may close any J2EE resource connections it had for deployment configuration and perform other related resource cleanup. It should not accept any new operation requests (i.e., distribute, start stop, undeploy, redeploy. It should finish any operations that are currently in process. Each ProgressObject associated with a running operation should be marked as released (see the ProgressObject).

getDefaultLocale

java.util.Locale getDefaultLocale()
Returns the default locale supported by this implementation of javax.enterprise.deploy.spi subpackages.

Returns:
Locale the default locale for this implementation.

getCurrentLocale

java.util.Locale getCurrentLocale()
Returns the active locale this implementation of javax.enterprise.deploy.spi subpackages is running.

Returns:
Locale the active locale of this implementation.

setLocale

void setLocale(java.util.Locale locale)
               throws java.lang.UnsupportedOperationException
Set the active locale for this implementation of javax.enterprise.deploy.spi subpackages to run.

Throws:
java.lang.UnsupportedOperationException - the provide locale is not supported.

getSupportedLocales

java.util.Locale[] getSupportedLocales()
Returns an array of supported locales for this implementation.

Returns:
Locale[] the list of supported locales.

isLocaleSupported

boolean isLocaleSupported(java.util.Locale locale)
Reports if this implementation supports the designated locale.

Returns:
A value of 'true' means it is support and 'false' it is not.

getDConfigBeanVersion

javax.enterprise.deploy.shared.DConfigBeanVersionType getDConfigBeanVersion()
Returns the J2EE platform version number for which the configuration beans are provided. The beans must have been compiled with the J2SE version required by the J2EE platform.

Returns:
a DConfigBeanVersionType object representing the platform version number for which these beans are provided.

isDConfigBeanVersionSupported

boolean isDConfigBeanVersionSupported(javax.enterprise.deploy.shared.DConfigBeanVersionType version)
Returns 'true' if the configuration beans support the J2EE platform version specified. It returns 'false' if the version is not supported.

Parameters:
version - a DConfigBeanVersionType object representing the J2EE platform version for which support is requested.
Returns:
'true' if the version is supported and 'false if not.

setDConfigBeanVersion

void setDConfigBeanVersion(javax.enterprise.deploy.shared.DConfigBeanVersionType version)
                           throws javax.enterprise.deploy.spi.exceptions.DConfigBeanVersionUnsupportedException
Set the configuration beans to be used to the J2EE platform version specificed.

Parameters:
version - a DConfigBeanVersionType object representing the J2EE platform version for which support is requested.
Throws:
javax.enterprise.deploy.spi.exceptions.DConfigBeanVersionUnsupportedException - when the requested bean version is not supported.