Java 2 Enterprise Edition Deployment API 1.1
Sept 26, 2002
Description
Maintenance version of the Java 2 Enterprise Edition Deployment API specification, version 1.1
 

Specification Lead
Rebecca Searls, Sun Microsystems, Inc.

Feedback
Comments should be sent to j2ee-deployment-comments@sun.com

Rationale for accepted changes
This maintenance release addresses the new requirements the J2EE 1.4 platform places on the deployment process and adds clarifications to several topics in the initial specification.


Accepted Changes
 

XML Schema
XML Schema supports the assigning of multiple attributes to an element.  Code will be added to the DDBean to support retrieval of attributes.
interface DDBean
{
    /**
       * Returns the list of attribute names associated with XML element.
     *
       * @return a list of attribute names on this element.  Null
       * is returned if there are no attributes.
       */
    String[] getAttributeNames();

    /**
      * Returns the string value of the named attribute.
    *
      * @return the value of the attribute.  Null is returned
      *   if there is no such attribute.
      */
    String getAttributeValue(String attrName);
}
 

Namespaces in Xpath Support
DTD-based and XML Schema-based deployment descriptors have different XPath naming requirements. This is due to the use of namespaces in XML Schema but not in DTD-based deployment descriptors.  The namespace feature requires the addition of a namespace prefix to each XML element in the XPath of a J2EE XMLSchema-based instance document. Each element in an XPath must be specifically qualified with the namespace prefix that is bound to the namespace's URI.   The format is:

                                                            < prefix>:<XML tag>

Prefix is a name associated with the namespace URI.  The  colon (:) is a separator between the prefix and the XML tag.

A namespace is uniquely identified using a URI.  A prefix may be associated with a namespace URI.  The reserved attribute xmlns is used to define a namespace without an associated prefix; the reserved attribute xmlns: is used to defined a namespace with an associated prefix.  A namespace defined without a prefix is treated as part of the default namespace.  The element in which this namespace is specified and all the contents within the element are associated with the XML Schema Namespace.  If there is no prefix defined for a namespace,  the <prefix>: is not used in the XPath element qualifier, only the <XML tag> is given.  Since namespaces are not supported in DTD-based deployment descriptors, the <prefix>:  is never used in the XPath element qualifier for deployment descriptors of this type.

The required namespace for J2EE XML Schema-based deployment descriptors is http://java.sun.com/xml/ns/j2ee.   There is no required prefix for this namespace.   The prefix  can either  be specified by the creator of the instance document or it can be  left unspecified and thus  part of the default namespace.

To build proper XPath strings, a J2EE Product Provider plugin will need to determine the active namespaces  for elements in a deployment descriptor instance document, by analyzing the attributes on the instance document elements.

In the example below, two active namespaces are defined in the root element of the instance document:
 

                xmlns="http://java.sun.com/xml/ns/j2ee".                 xmlns:foobar="http://foobar.com".

The AbsoluteLocationPath to element foobar:comment would be

                            /web-app/deployment-extension/extension-element/foobar:comment

    From the element above, the RelativeLocationPath to foobar:version would be:

                        foobar:product/foobar:version

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:foobar="http://foobar.com"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd http://foobar.com
        http://foobar.com/foobar.xsd"
        version="2.4">
    <servlet>
           <servlet-name>MyInventoryServlet</servlet-name>
            <servlet-class>com.acme.Inventory</servlet-class>
            <init-param>
                 <param-name>debug</param-name>
                  <param-value>0</param-value>
            </init-param>
            <init-param>
                 <param-name>defaultCompany</param-name>
                  <param-value>ToysRUs</param-value>
            </init-param>
            <load-on-startup>1</load-on-startup>
      </servlet>
            :
            :
            :
    <deployment-extension namespace="http://foobar.com"
                mustUnderstand="false">
        <extension-element xsi:type="foobar:mytype">
                <foobar:comment>This component is generated byFoobar company
                </foobar:comment>
                <foobar:product>Foobar Build Environment</foobar:product>
                            <foobar:version>100.5</foobar:version>
        </extension-element>
    </deployment-extension>
</web-app>


An alternative implementation of the previous example is to define the foobar namespace in the deployment-extension element.   The J2EE Product Provider plugin would have had to analyze the attributes on the root element and the deployment-extension element in order to generate the XPath strings.

A vendor plugin could get the foobar:version  data with the following steps.
 


 
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd
        version="2.4">
    <servlet>
           <servlet-name>MyInventoryServlet</servlet-name>
            <servlet-class>com.acme.Inventory</servlet-class>
            <init-param>
                 <param-name>debug</param-name>
                  <param-value>0</param-value>
            </init-param>
            <init-param>
                 <param-name>defaultCompany</param-name>
                  <param-value>ToysRUs</param-value>
            </init-param>
            <load-on-startup>1</load-on-startup>
      </servlet>
            :
            :
            :
    <deployment-extension namespace="http://foobar.com"
                xmlns:foobar="http://foobar.com"
                xsi:schemaLocation=http://foobar.com http://foobar.com/foobar.xsd"
                mustUnderstand="false">
        <extension-element xsi:type="foobar:mytype">
                <foobar:comment>This component is generated byFoobar company
                </foobar:comment>
                <foobar:product>Foobar Build Environment</foobar:product>
                            <foobar:version>100.5</foobar:version>
        </extension-element>
    </deployment-extension>
</web-app>
Web Services (JSR-109) Support
Web Services, JSR-109, adds new deployment descriptor files to the J2EE module package.  There are deployment descriptor files with defined names, webservices.xml and webservicesclient.xml, and WSDL documents whose names are identified by an XML tag in the web services deployment descriptor.  The following changes will be made to the interfaces in order to provide multiple deployment descriptor file support for these files.

The deployment characteristics for a web service are defined in both the module specific deployment descriptor and the web service deployment descriptor. The  DeploymentConfiguration.getDConfigBeanRoot method must be used to pass the module specific deployment descriptor.  See the corresponding component specification for the details.  The web services deployment descriptors, webservice.xml and webserviceclient.xml must be passed to the plugin by the method DConfigBeanRoot.getDConfigBean.

The DeployableObject.getDDBeanRoot is to be used to return a DDBeanRoot object for non deployment descriptor XML instance documents such as WSDL files.
 

interface DConfigBeanRoot
{
    /**
       * Return a DConfigBean for a deployment descriptor that is not the module's
       * primary deployment descriptor.   Web services provides a deployment descriptor
       * in addition to the module's primary deployment descriptor.  Only the DDBeanRoot
       * for this category of secondary deployment descriptors are to be passed as arguments
       * through this method.
       *
       * Web service has two deployment descriptor files, one that defines the web service
       * and one that defines a client of a web service.  See the Web Service specification for
       * the details.
     *
       * @param ddBeanRoot represents the root element of a deployment descriptor file.
     *
       *  @return a DConfigBean to be used for processing this deployment descriptor data. Null may be returned
       *    if no DConfigBean is required for this deployment descriptor.
       */
     DConfigBean  getDConfigBean(DDBeanRoot ddBeanRoot)
 }

interface DeployableObject
 {
     /**
        * Returns a DDBeanRoot object for the XML instance document named.
        * This method should be used to return DDBeanRoot objects for non deployment
        * descriptor XML instance documents such as WSDL files.
      *
        * @param filename the full path name from the root of the module of the xml
        *  instance document for which a DDBeanRoot object is to be returned.
        * @return a DDBeanRoot object for the XML data.
        * @throws java.io.FileNotFoundException, if the named file can not be found
        * @throws javax.enterprise.deploy.model.exceptions.DDBeanCreationException
        * if an error is encountered creating the DDBeanRoot object.
        */
     DDBeanRoot getDDBeanRoot(String filename) throws
       java.io.FileNotFoundException,
       javax.enterprise.deploy.model.exceptions.DDBeanCreationException;
 }

   interface DDBeanRoot extends DDBean
   {
       /**
          * Returns the filename relative to the root of the module of the XML instance document this
          *  DDBeanRoot represents.
        *
          *  @return String the filename relative to the root of the module
          */
       String getFilename();
   }

A new exceptions directory will be added to the javax.enterprise.deploy.model package.
The new class DDBeanCreateException will be added to this directory.
 
package javax.enterprise.deploy.model.exceptions;

  /**
    * This exception reports errors in generating a DDBean.
    *
    */
   public class DDBeanCreateException extends java.lang.Exception {

    /**
       * Creates new <code>DDBeanCreateException</code> without detail message.
       */
    public DDBeanCreateException() {
    }

    /**
       * Constructs an <code>DDBeanCreateException</code> with the
       * specified detail message.
       * @param msg the detail message.
       */
    public DDBeanCreateException(String msg) {
        super(msg);
    }
}
 


General Archive Access
The following changes will be added to support Optional Packages and web services and to provide
backward compatibility to pre-1.4 archives.

import java.util.Enumeration;
import java.io.InputStream;
import java.io.IOException;

public interface DeployableObject
{
  /**
    *  Returns an enumeration of the module file entries.  All elements in the
    *  enumeration are of type String.  Each String represents a file name relative
    *  to the root of the module.
   *
   * @return an enumeration of the archive file entries.
   */
  public Enumeration entries();

  /**
   * Returns the InputStream for the given entry name.
   * The file name must be relative to the root of the module.
   *
   * @param name the file name relative to the root of the module.
   *
   * @return the InputStream for the given entry name or null if not found.
   */
  public InputStream getEntry(String name);
}

Deployment Descriptor version support change
To support multiple deployment descriptor files, the placement of the method to return the instance document version must change.  Each DDBeanRoot is associated with a specific deployment descriptor document.  The method to retrieve the document version must reside in the DDBeanRoot object.
public interface DeployableObject
{
    /**
       * A convenience method to return the deployment descriptor
       * document version number of the primary deployment descriptor
       * for the module (e.g. web.xml, ejb-jar.xml, ra.xml, application.xml,
       * and  application-client.xml.)  The version number for documents
       * webservices.xml , webservicesclient.xml and the like are not returned
       * by this method.  DDBeanRoot.getDDBeanRootVersion should be used
       * instead.
       *
       * This method is being deprecated.  DDBeanRoot.getDDBeanRootVersion
       * should be used instead.
     *
       *   @deprecated As of version 1.1, replace by DDBeanRoot.getDDBeanRootVersion()
     *
       * @return a string that is the version number of the XML instance document.
       *  Null is returned if no version number can be found.
       */
    String getModuleDTDVersion()
}
 

Interface DDBeanRoot
{
    /* *
       *A convenience method to return the version number of an
       * XML instance document.  This method is replacing the
       * method DeployableObject.getModuleDTDVersion, because
       * it returns the version number of any J2EE XML instance document

        * @return a string that is the version number of the XML instance document.
        *  Null is returned if no version number can be found.
     */
    String getDDBeanRootVersion();
}


Document Clarifications

Invalid J2EE version designator, V1_3_1
The documentation will be changed to state that this constant should never be used.
getId Method clarification
The documentation for method getId will read:
 Returns a tool-specific reference for attribute ID on an element in the deployment descriptor.  This attribute is defined for J2EE 1.2 and 1.3 components.
Clarification of how a J2EE server vendor should package its plugin
The following section will be added to the specification to describe how a server vendor should package its javax.enterprise.deploy.spi package implementation.
A Server vendor plugin is packaged into one or more JAR files with a .jar extension.  The JAR file or files contain an implementation of the javax.enterprise.deploy.spi package and utility classes. The APIs must be implemented in the vendor's namespace.

The entry point class to the server plugin is an implementation of the DeploymentFactory interface.  There can be one or more DeploymentFactory implementation classes in the plugin.  Each implementation must be identified by a fully qualified class name in the JAR file's manifest file by the attribute, J2EE-DeploymentFactory-Implementation-Class.

The plugin should not assume that any packages other than the J2SE version required by the plugin's J2EE platform or higher and the javax.enterprise.deploy package will be available.  The plugin should not provide the J2EE APIs in the JAR files provided to the tool.  Plugins should not attempt to load application classes in the tool.  The plugin may send the application classes to the server and load them there for (e.g.) reflection, but the plugin should not try to use reflection on application classes in the plugin  because doing so is not portable.

The manner in which a vendor's plugin JAR file(s) are made available to the tool is not specified.  Some J2EE Product vendors may direct the user to download the plugin from a web site, others may require the user to copy it from their local server installation, and another may provide an initial JAR file whose DeploymentFactory implementation contains an automated mechanism that downloads the JAR file(s) on a tool's initial request for a DeploymentFactory.
 

Clarification of how a J2EE tool vendor should access server vendor's plugin
The following section will be added to the specification to describe how a deployment tool should load a server vendor's plugin.
The manner in which a tool makes a server plugin accessible in its classpath is not specified.  One tool vendor may designate a directory in which all plugin JAR file(s) are saved.  It could then process all the JAR files in the directory.   Another may retain a repository of plugin names and directory locations which it processes.  A third vendor may require the user to identify the location of the plugin whenever it runs.

The tool vendor is required to provide the J2SE version required by the plugin or higher and the javax.enterprise.deploy.  See getDConfigBeanVersion in Section 4.2 for information on how to get the plugin version.

The entry point to a server plugin is the implementation of the DeploymentFactory interface.  A server vendor must provide at least one implementation of the DeploymentFactory interface.  The fully qualified name of each DeploymentFactory implementation in a JAR file must be identified in the J2EE-DeploymentFactory-Implementation-Class attribute of the JAR file's manifest file.

   A description will be added to section 9.3 clarifying how the manifest key, J2EE-DeploymentFactory-Implementation-Class, is to be used.
Clarification of Target examples
In section 6.2 the example 2 comment will be changed to read as follows:
Example 2 illustrates a J2EE product that defines one Target  object.  Three servers use the same directory for the target's archive repository.  This example demonstrates a target functioning as a staging area from which multiple servers pull applications to install and run.


In section 6.2 the example 3 comment will be changed to read as follows:

Example 3 shows one J2EE product vendor that define a unique server to be defined by a server paired with a database. In this example a single server is paired with two separate databases: thus there are two separate servers by this vendor's definition.  A unique target has been defined for each server in this example.
Clarification of distribute/start and stop/undeploy
The following clarification as to the initialization and shutdown of an application's running environment will be added to Chapter 4.
The time at which an application's running environment is initialized or shut down is not specified.  A vendor may choose to initialize an application's running environment when the archive is distributed to the system or wait until the start action is called.  The only requirement is that the application is not available to clients until the start action is called.  Similarly a vendor may choose to shut down a running application's environment when stop is called or wait until undeploy is called. The only requirement is that the application is made unavailable to clients when the stop action is called.
Clarification of DDBean.getXpath
The documentation will be changed to read:
Returns the original xpath string provided by the DConfigBean.
Correct API documentation
Correct the documentation in file DConfigBean.java that refers to DeploymentConfigurator to read DeploymentConfiguration.
Clarification of ClientConfiguration
Clarify that the Serializable nature of the ClientConfiguration is limited across VM activations of the AppClientContainer.
Web Services support
Documentation will be added at appropriate places in the specification and API documentation to address the issues of web service support.

XML Schema support
Documentation will be added at appropriate places throughout the document to address the issues of XML  Schema support.  See Namespaces in Xpath Support above for the description of namespace support.

Clarification UI Contract between Tool and Plugin
The following clarification will be added to the specification.

JavaBean components present the dynamic deployment configuration information for a J2EE plugin to the deployer.  The JavaBeans architecture was chosen because of its versatility in providing both simple and complex components.  JavaBeans also enable the development of property sheets and property editors, as well as sophisticated customization wizards.

The JavaBean GUI mechanism, that a plugin provider implements in order to enable their DConfigBeans to be displayed by a deploy tool, is not specified.  The plugin provider may choose to provide a Customizer for one DConfigBean, a Property Editor for a complex datatype for the Property Sheet of another DConfigBean, and to use the default Property Editors for the Property Sheet of yet a third DConfigBean. See the JavaBeans API Specification version 1.01.

The manner in which a tool analyzes a DConfigBean and displays it is not specified.  It is recommended that any Customizer or Property Editor provided by the plugin vendor take precedence over similar functionality provided by the tool vendor.

It is expected that a Property Editor will be provided by a plugin vendor for any complex datatype in a DConfigBean that is to be edited by the Deployer.  The Property Editor should be implemented and made
available to a tool according to the guidelines defined in the JavaBeans API Specification version 1.01.
 
 

DConfigBean API documentation change
The DConfigBean API documentation header will be changed to the following:

The DConfigBean is a deployment configuration bean (DConfigBean) that is associated with one or more deployment descriptor beans, (DDBean).   A DConfigBean represents a logical grouping of deployment configuration data to be presented to the Deployer. A DConfigBean provides zero or more XPaths that identifies the XML information it requires. A DConfigBean may contain other DConfigBeans and regular JavaBeans. The topmost DConfigBean is a DConfigBeanRoot object which represents a single XML instance document.

A DConfigBean is created by calling DConfigBean.getDConfigBean(DDBean), where DConfigBean is the object that provided the XPath which the DDBean represents.

A DConfigBean is a JavaBean component that presents the dynamic deployment configuration information for a J2EE plugin to the deployer.  The JavaBean architecture was chosen because of its versatility in providing both simple and complex components. JavaBeans also enable the development of property sheets and property editors, as well as sophisticated customization wizards.

It is expected that a plugin vendor will provide a Property Editor for any complex datatype in a DConfigBean that a deployer needs to be edit through a property sheet. The Property Editor should be implemented and made available to a tool according to the guidelines defined in the JavaBeans API Specification version 1.01.

DConfigBeanRoot API documentation change
The DConfigBeanRoot API documentation header will be changed to the following:

A J2EE component module consists of one or more deployment descriptor files and zero or more non-deployment descriptor XML instance documents.  A module must contain a component-specific deployment descriptor file (see the component specification for details). It may contain one or more secondary deployment descriptor files that define extra functionality on the component and zero or more non-deployment descriptor XML instance documents (see the Web Services specification).

The DConfigBeanRoot object is a deployment configuration bean (DConfigBean) that is associated with the root of the component's deployment descriptor. It must be created by calling the DeploymentConfiguration.getDConfigBean(DDBeanRoot) method where DDBeanRoot represents the  component's deployment descriptor.

A DConfigBean object is associated with a deployment descriptor that  extends a component's functionality.  It must be created by calling the DConfigBeanRoot.getDConfigBean(DDBeanRoot) method. This DConfigBean object  is a child of the compontent's DConfigBeanRoot object.  The DDBeanRoot  argument represents the  secondary deployment descriptor.  Deployment  descriptor files  such as  webservice.xml and webserviceclient.xml are examples of secondary deployment descriptor files.

The server plugin must request a DDBeanRoot object for any non-deployment descriptor XML instance document data it requires.  The plugin must call method DeployableObject.getDDBeanRoot(String) where String is the full path name from the root of the module to the file to be represented. A WSDL file is an example of a non-deployment descriptor XML instance document.