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.
-
The deployment descriptor file format has moved from DTD to XML Schema.
Under this new format, multiple attributes on an XML element must
be supported, and XPath strings must include namespace designators.
-
The Web Services Specification, JSR-109, requires support for multiple
XML instance documents.
-
Optional Packages requires support for accessing the appropriate information
in a module's manifest file.
-
The method that returns the deployment descriptor version must be made
generic to support both DTD and XML Schema formats.
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:
-
The J2EE namespace is defined without a prefix:
xmlns="http://java.sun.com/xml/ns/j2ee".
-
The namespace, http://foobar.com is defined with prefix foobar,:
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.
-
Determine the J2EE namespace prefix from the root element.
-
Create the AbsoluteLocationPath /web-app/deployment-extension.
-
Evaluate each deployment-extension element for the foobar namespace
name.
-
Determine the prefix of the foobar namespace.
-
Create the RelativeLocationPath, extension-element/foobar:comment
/foobar:product/foobar:version.
<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.
|
