You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by db...@apache.org on 2003/08/30 04:16:58 UTC
cvs commit: incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi DConfigBean.java DConfigBeanRoot.java DeploymentConfiguration.java DeploymentManager.java Target.java TargetModuleID.java
dblevins 2003/08/29 19:16:58
Modified: specs/j2ee-deployment/src/java/javax/enterprise/deploy/model
DDBean.java DDBeanRoot.java DeployableObject.java
J2eeApplicationObject.java XpathEvent.java
XpathListener.java
specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/exceptions
DDBeanCreateException.java
specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi
DConfigBean.java DConfigBeanRoot.java
DeploymentConfiguration.java DeploymentManager.java
Target.java TargetModuleID.java
Log:
Obtained from: Aaron Mulder
Submitted by: Aaron Mulder
Reviewed by: David Blevins
Patch: [GERONIMO-3] JavaDoc for JSR-88
From: Aaron Mulder
Description: Added JavaDoc to some of the JSR-88 spec packages
Revision Changes Path
1.2 +65 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/DDBean.java
Index: DDBean.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/DDBean.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DDBean.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DDBean.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -60,27 +60,91 @@
package javax.enterprise.deploy.model;
/**
+ * An interface for beans that represent a fragment of a standard deployment
+ * descriptor. A link is provided to the J2EE application that includes this bean.
*
* @version $Revision$ $Date$
*/
public interface DDBean {
+ /**
+ * Returns the location in the deployment descriptor from which this bean is derived.
+ *
+ * @return The XPath of this Bean.
+ */
public String getXpath();
+ /**
+ * Returns the XML text for by this bean.
+ *
+ * @return The XML text for this Bean.
+ */
public String getText();
+ /**
+ * Returns the ATTLIST ID value for the XML tag defined by the Xpath for this bean.
+ *
+ * @return The XML text for this Bean or 'null' if no attribute was specifed with the tag.
+ */
public String getId();
+ /**
+ * Return the root element for this DDBean.
+ *
+ * @return The DDBeanRoot at the root of this DDBean tree.
+ */
public DDBeanRoot getRoot();
+ /**
+ * Return a list of DDBeans based upon the XPath.
+ *
+ * @param xpath An XPath string referring to a location in the same deployment descriptor as this standard bean.
+ *
+ * @return a list of DDBeans or 'null' if no matching XML data is found.
+ */
public DDBean[] getChildBean(String xpath);
+ /**
+ * Return a list of text values for a given XPath in the deployment descriptor.
+ *
+ * @param xpath An XPath.
+ *
+ * @return The list text values for this XPath or 'null' if no matching XML data is found.
+ */
public String[] getText(String xpath);
+ /**
+ * Register a listener for a specific XPath.
+ *
+ * @param xpath The XPath this listener is to be registered for.
+ * @param xpl The listener object.
+ */
public void addXpathListener(String xpath, XpathListener xpl);
+ /**
+ * Unregister a listener for a specific XPath.
+ *
+ * @param xpath The XPath this listener is to be registered for.
+ * @param xpl The listener object.
+ */
public void removeXpathListener(String xpath, XpathListener xpl);
+ /**
+ * Returns the list of attribute names associated with XML element.
+ *
+ * @since 1.1
+ *
+ * @return a list of attribute names on this element. Null
+ * is returned if there are no attributes.
+ */
public String[] getAttributeNames();
+ /**
+ * Returns the string value of the named attribute.
+ *
+ * @since 1.1
+ *
+ * @return the value of the attribute. Null is returned
+ * if there is no such attribute.
+ */
public String getAttributeValue(String attrName);
}
1.2 +65 -2 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/DDBeanRoot.java
Index: DDBeanRoot.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/DDBeanRoot.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DDBeanRoot.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DDBeanRoot.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -62,22 +62,85 @@
import javax.enterprise.deploy.shared.ModuleType;
/**
+ * An interface that represents the root of a standard deployment descriptor.
+ * A DDBeanRoot is a type of DDBean.
*
* @version $Revision$ $Date$
*/
public interface DDBeanRoot extends DDBean {
+ /**
+ * Return the ModuleType of deployment descriptor.
+ *
+ * @return The ModuleType of deployment descriptor
+ */
public ModuleType getType();
+ /**
+ * Return the containing DeployableObject
+ *
+ * @return The DeployableObject that contains this deployment descriptor
+ */
public DeployableObject getDeployableObject();
/**
- * @deprecated
+ * A convenience method to return the DTD version number. The DeployableObject has this information.
+ *
+ * Note: the method getDDBeanRootVersion() is preferred to this method.
+ * @see #getDDBeanRootVersion
+ *
+ * @return a string containing the DTD version number
*/
public String getModuleDTDVersion();
+ /**
+ * 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 <p>a string that is the version number of the XML instance document.
+ * Null is returned if no version number can be found.</p>
+ * <p>A module's deployment descriptor file always contains
+ * a document type identifier, DOCTYPE. The DOCTYPE statement
+ * contains the module DTD version number in the label of the
+ * statement.</p>
+ * <p>The format of the DOCTYPE statement is:</p>
+ * <pre><!DOCTYPE root_element PUBLIC "-//organization//label//language" "location"></pre>
+ * <dl>
+ * <dt>root_element</dt><dd>is the name of the root document in the DTD.</dd>
+ * <dt>organization</dt><dd>is the name of the organization responsible
+ * for the creation and maintenance of the DTD
+ * being referenced.</dd>
+ * <dt>label</dt><dd>is a unique descriptive name for the public text being
+ * referenced. </dd>
+ * <dt>language</dt><dd>is the ISO 639 language id representing the natural
+ * language encoding of th DTD.</dd>
+ * <dt>location</dt><dd>is the URL of the DTD.</dd>
+ * </dl>
+ * <p>An example J2EE deployment descriptor DOCTYPE statement is:</p>
+ * <pre><!DOCTYPE application-client PUBLIC
+ * "-//Sun Microsystems, Inc.//DTD J2EE Application Client 1.3//EN"
+ * "http://java.sun.com/dtd/application-client_1_3.dtd"></pre>
+ * <p>In this example the label is, "DTD J2EE Application Client 1.3",
+ * and the DTD version number is 1.3. A call to getModuleDTDVersion
+ * would return a string containing, "1.3".</p>
+ */
public String getDDBeanRootVersion();
+ /**
+ * Return the XPath for this standard bean. The root XPath is "/".
+ *
+ * @return "/" this is the root standard bean.
+ */
public String getXpath();
+ /**
+ * Returns the filename relative to the root of the module of the XML instance document this
+ * DDBeanRoot represents.
+ *
+ * @since 1.1
+ *
+ * @return String the filename relative to the root of the module
+ */
public String getFilename();
}
1.2 +88 -2 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/DeployableObject.java
Index: DeployableObject.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/DeployableObject.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DeployableObject.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DeployableObject.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -66,28 +66,114 @@
import javax.enterprise.deploy.shared.ModuleType;
/**
+ * The DeployableObject interface is an abstract representation of a J2EE deployable
+ * module (JAR, WAR, RAR, EAR). A DeployableObject provides access to the module's
+ * deployment descriptor and class files.
*
* @version $Revision$ $Date$
*/
public interface DeployableObject {
+ /**
+ * Return the ModuleType of deployment descriptor (i.e., EAR, JAR, WAR, RAR)
+ * this deployable object represents. Values are found in DeploymentManager.
+ *
+ * @return The ModuleType of deployable object
+ */
public ModuleType getType();
+ /**
+ * Return the top level standard bean representing the root of the deployment descriptor.
+ *
+ * @return A standard bean representing the deployment descriptor.
+ */
public DDBeanRoot getDDBeanRoot();
+ /**
+ * Return an array of standard beans representing the XML content returned based upon the XPath.
+ *
+ * @param xpath AAn XPath string identifying the data to be extracted from the deployment descriptor.
+ *
+ * @return an array of DDBeans or <code>null</code> if no matching data is found.
+ */
public DDBean[] getChildBean(String xpath);
+ /**
+ *
+ * @param xpath An xpath string referring to a location in the deployment descriptor
+ *
+ * @return a list XML content or <code>null</code> if no matching data is found.
+ */
public String[] getText(String xpath);
+ /**
+ * Retrieve the specified class from this deployable module.
+ * <p>One use: to get all finder methods from an EJB. If the tool is attempting to package a
+ * module and retrieve a class from the package, the class request may fail. The class may
+ * not yet be available. The tool should respect the manifest Class-Path entries.</p>
+ *
+ * @param className Class to retrieve.
+ *
+ * @return Class representation of the class
+ */
public Class getClassFromScope(String className);
/**
- * @deprecated
+ * 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.
*/
public String getModuleDTDVersion();
+ /**
+ * 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.
+ *
+ * @since 1.1
+ *
+ * @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.DDBeanCreateException
+ * if an error is encountered creating the DDBeanRoot object.
+ */
public DDBeanRoot getDDBeanRoot(String filename) throws FileNotFoundException, DDBeanCreateException;
+ /**
+ * 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.
+ *
+ * @since 1.1
+ *
+ * @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.
+ *
+ * @since 1.1
+ *
+ * @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);
}
1.2 +70 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/J2eeApplicationObject.java
Index: J2eeApplicationObject.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/J2eeApplicationObject.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- J2eeApplicationObject.java 16 Aug 2003 12:28:26 -0000 1.1
+++ J2eeApplicationObject.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -62,25 +62,94 @@
import javax.enterprise.deploy.shared.ModuleType;
/**
+ * J2eeApplicationObject is an interface that represents a J2EE application (EAR);
+ * it maintains a DeployableObject for each module in the archive.
*
* @version $Revision$ $Date$
*/
public interface J2eeApplicationObject extends DeployableObject {
+ /**
+ * Return the DeployableObject of the specified URI designator.
+ *
+ * @param uri Describes where to get the module from.
+ *
+ * @return the DeployableObject describing the j2ee module at this uri
+ * or <code>null</code> if there is not match.
+ */
public DeployableObject getDeployableObject(String uri);
+ /**
+ * Return the all DeployableObjects of the specified type.
+ *
+ * @param type The type of module to return.
+ *
+ * @return the list of DeployableObjects describing the j2ee modules of
+ * this type or <code>null</code> if there are no matches.
+ */
public DeployableObject[] getDeployableObjects(ModuleType type);
+ /**
+ * Return the all DeployableObjects in this application.
+ *
+ * @return the DeployableObject instances describing the j2ee modules in
+ * this application or <code>null</code> if there are none available.
+ */
public DeployableObject[] getDeployableObjects();
+ /**
+ * Return the list of URIs of the designated module type.
+ *
+ * @param type The type of module to return.
+ *
+ * @return the Uris of the contained modules or <code>null</code> if there
+ * are no matches.
+ */
public String[] getModuleUris(ModuleType type);
+ /**
+ * Return the list of URIs for all modules in the application.
+ *
+ * @return the Uris of the contained modules or <code>null</code> if
+ * the application is completely empty.
+ */
public String[] getModuleUris();
+ /**
+ * Return a list of DDBean instances based upon an XPath; all deployment
+ * descriptors of the specified type are searched.
+ *
+ * @param type The type of deployment descriptor to query.
+ * @param xpath An XPath string referring to a location in the deployment descriptor
+ *
+ * @return The list of DDBeans or <code>null</code> if there are no matches.
+ */
public DDBean[] getChildBean(ModuleType type, String xpath);
+ /**
+ * Return the text value from the XPath; search only the deployment descriptors
+ * of the specified type.
+ *
+ * @param type The type of deployment descriptor to query.
+ * @param xpath The xpath to query for.
+ *
+ * @return The text values of this xpath or <code>null</code> if there are no matches.
+ */
public String[] getText(ModuleType type, String xpath);
+ /**
+ * Register a listener for changes in XPath that are related to this deployableObject.
+ *
+ * @param type The type of deployment descriptor to query.
+ * @param xpath The xpath to listen for.
+ * @param xpl The listener.
+ */
public void addXpathListener(ModuleType type, String xpath, XpathListener xpl);
+ /**
+ * Unregister the listener for an XPath.
+ * @param type The type of deployment descriptor to query.
+ * @param xpath The xpath to listen for.
+ * @param xpl The listener.
+ */
public void removeXpathListener(ModuleType type, String xpath, XpathListener xpl);
}
1.2 +52 -2 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/XpathEvent.java
Index: XpathEvent.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/XpathEvent.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XpathEvent.java 16 Aug 2003 12:28:26 -0000 1.1
+++ XpathEvent.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -62,44 +62,94 @@
import java.beans.PropertyChangeEvent;
/**
+ * An Event class describing DDBeans being added to or removed from a J2EE
+ * application, or updated in place.
*
* @version $Revision$ $Date$
*/
public class XpathEvent {
- /**@todo is this the right ? */
+ /**
+ * Adding a DDBean
+ */
public static final Object BEAN_ADDED = new Object();
+ /**
+ * Removing a DDBean
+ */
public static final Object BEAN_REMOVED = new Object();
+ /**
+ * Changing a DDBean
+ */
public static final Object BEAN_CHANGED = new Object();
private PropertyChangeEvent pce;
private DDBean bean;
private Object type;
+ /**
+ * A description of a change in the DDBean tree.
+ *
+ * @param bean The DDBean being added, removed, or updated.
+ * @param type Indicates whether this is an add, remove, or update event.
+ */
public XpathEvent(DDBean bean, Object type) {
this.bean = bean;
this.type = type;
}
+ /**
+ * Gets the underlying property change event, with new and
+ * old values. This is typically used for change events.
+ * It is not in the public API, but is included in the
+ * downloadable JSR-88 classes.
+ */
public PropertyChangeEvent getChangeEvent() {
return pce;
}
+ /**
+ * Sets the underlying property change event, with new and
+ * old values. This is typically used for change events.
+ * It is not in the public API, but is included in the
+ * downloadable JSR-88 classes.
+ *
+ * @param pce The property change event that triggered this XpathEvent.
+ */
public void setChangeEvent(PropertyChangeEvent pce) {
this.pce = pce;
}
+ /**
+ * The bean being added/removed/changed.
+ *
+ * @return The bean being added/removed/changed.
+ */
public DDBean getBean() {
return bean;
}
+ /**
+ * Is this an add event?
+ *
+ * @return <code>true</code> if this is an add event.
+ */
public boolean isAddEvent() {
return BEAN_ADDED == type;
}
+ /**
+ * Is this a remove event?
+ *
+ * @return <code>true</code> if this is a remove event.
+ */
public boolean isRemoveEvent() {
return BEAN_REMOVED == type;
}
+ /**
+ * Is this a change event?
+ *
+ * @return <code>true</code> if this is a change event.
+ */
public boolean isChangeEvent() {
return BEAN_CHANGED == type;
}
1.2 +7 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/XpathListener.java
Index: XpathListener.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/XpathListener.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XpathListener.java 16 Aug 2003 12:28:26 -0000 1.1
+++ XpathListener.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -60,9 +60,15 @@
package javax.enterprise.deploy.model;
/**
+ * The listener interface for receiving XpathEvents
*
* @version $Revision$ $Date$
*/
public interface XpathListener {
+ /**
+ * Invoked when an XpathEvent is generated for this listener
+ *
+ * @param xpe The XpathEvent
+ */
public void fireXpathEvent(XpathEvent xpe);
}
1.2 +13 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/exceptions/DDBeanCreateException.java
Index: DDBeanCreateException.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/model/exceptions/DDBeanCreateException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DDBeanCreateException.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DDBeanCreateException.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -60,14 +60,26 @@
package javax.enterprise.deploy.model.exceptions;
/**
+ * This exception reports errors in generating a DDBean.
+ *
+ * @since 1.1
*
* @version $Revision$ $Date$
*/
public class DDBeanCreateException extends Exception {
+ /**
+ * Creates new <code>DDBeanCreateException</code> without detail message.
+ */
public DDBeanCreateException() {
super();
}
+ /**
+ * Constructs an <code>DDBeanCreateException</code> with the
+ * specified detail message.
+ *
+ * @param msg the detail message.
+ */
public DDBeanCreateException(String msg) {
super(msg);
}
1.2 +81 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DConfigBean.java
Index: DConfigBean.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DConfigBean.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DConfigBean.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DConfigBean.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -66,21 +66,101 @@
import java.beans.PropertyChangeListener;
/**
+ * The interface for configuring a server-specific deployment descriptor, or subset of same.
+ * A DConfigBean corresponds to a specific location in a standard deployment descriptor,
+ * typically where values (such as names and roles) are used.
+ *
+ * <p>There are three different ways that DConfigBeans are created:</p>
+ *
+ * <ul>
+ * <li><code>DeploymentConfigurator.getDConfigBean(DDBeanRoot)</code> is called by the
+ * deployment tool to create a DConfigBeanRoot for each deployment descriptor in
+ * the J2EE application.</li>
+ * <li><code>DConfigBean.getDConfigBean(DDBean)</code> is called by the deployment
+ * tool for each DDBean that corresponds to a relative XPath pattern given to the
+ * deployment tool by the method <code>DConfigBean.getXpaths()</code>.</li>
+ * <li>Each DConfigBean can structure its configurations as a tree-structure of
+ * DConfigBeans; a DConfigBean can have properties of type DConfigBean or
+ * DConfigBean[].</li>
+ * <ul>
+ *
+ * <p>The properties of DConfigBeans are displayed and edited by the deployment tool by
+ * using the JavaBean Property classes.</p>
*
* @version $Revision$ $Date$
*/
public interface DConfigBean {
+ /**
+ * Return the JavaBean containing the deployment descriptor XML text associated with this DConfigBean.
+ *
+ * @return The bean class containing the XML text for this DConfigBean.
+ */
public DDBean getDDBean();
+ /**
+ * Return a list of XPaths designating the deployment descriptor information this
+ * DConfigBean requires. Each server vendor may need to specify different
+ * server-specific information. Each String returned by this method is an XPath
+ * describing a certain portion of the standard deployment descriptor for which
+ * there is corresponding server-specific configuration.
+ *
+ * @return a list of XPath Strings representing XML data to be retrieved or
+ * <code>null</code> if there are none.
+ */
public String[] getXpaths();
+ /**
+ * Return the JavaBean containing the server-specific deployment configuration
+ * information based upon the XML data provided by the DDBean.
+ *
+ * @param bean The DDBean containing the XML data to be evaluated.
+ *
+ * @return The DConfigBean to display the server-specific properties for the standard bean.
+ *
+ * @throws ConfigurationException reports errors in generating a configuration bean.
+ * This DDBean is considered undeployable to this server until this exception is
+ * resolved. A suitably descriptive message is required so the user can diagnose
+ * the error.
+ */
public DConfigBean getDConfigBean(DDBean bean) throws ConfigurationException;
+ /**
+ * Remove a child DConfigBean from this bean.
+ *
+ * @param bean The child DConfigBean to be removed.
+ *
+ * @throws BeanNotFoundException the bean provided is not in the child list of this bean.
+ */
public void removeDConfigBean(DConfigBean bean) throws BeanNotFoundException;
+ /**
+ * A notification that the DDBean provided in the event has changed and this bean
+ * or its child beans need to reevaluate themselves.
+ *
+ * <p><i>It is advisable, though not declared explicitly in the specification, for a
+ * DConfigBean to receive change events for itself, and add or remove events for
+ * its direct children. The DConfigBean implementation should not add or remove
+ * beans here if it will add or remove those beans again in response to a call to
+ * getDConfigBean or removeDConfigBean.</i></p>
+ *
+ * @see #getDConfigBean
+ * @see #removeDConfigBean
+ *
+ * @param event an event containing a reference to the DDBean which has changed.
+ */
public void notifyDDChange(XpathEvent event);
+ /**
+ * Register a property listener for this bean.
+ *
+ * @param pcl PropertyChangeListener to add
+ */
public void addPropertyChangeListener(PropertyChangeListener pcl);
+ /**
+ * Unregister a property listener for this bean.
+ *
+ * @param pcl Listener to remove.
+ */
public void removePropertyChangeListener(PropertyChangeListener pcl);
}
1.2 +27 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DConfigBeanRoot.java
Index: DConfigBeanRoot.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DConfigBeanRoot.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DConfigBeanRoot.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DConfigBeanRoot.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -62,9 +62,35 @@
import javax.enterprise.deploy.model.DDBeanRoot;
/**
+ * The DConfigBeanRoot interface represent the root of a deployment descriptor.
+ * A DConfigBeanRoot is associated with a DDRoot object which in turn is associated
+ * with a specific deployment descriptor file.
+ *
+ * <p>Only DConfigBeanRoots are saved or restored by methods in
+ * DeploymentConfiguration.</p>
+ *
+ * @see DeploymentConfiguration
*
* @version $Revision$ $Date$
*/
public interface DConfigBeanRoot extends DConfigBean {
+ /**
+ * 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.
+ *
+ * @since 1.1
+ *
+ * @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.
+ */
public DConfigBean getDConfigBean(DDBeanRoot ddBeanRoot);
}
1.2 +65 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DeploymentConfiguration.java
Index: DeploymentConfiguration.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DeploymentConfiguration.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DeploymentConfiguration.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DeploymentConfiguration.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -67,21 +67,85 @@
import java.io.InputStream;
/**
+ * An interface that defines a container for all the server-specific configuration
+ * information for a single top-level J2EE module. The DeploymentConfiguration
+ * object could represent a single stand alone module or an EAR file that contains
+ * several sub-modules.
*
* @version $Revision$ $Date$
*/
public interface DeploymentConfiguration {
+ /**
+ * Returns an object that provides access to the deployment descriptor data
+ * and classes of a J2EE module.
+ *
+ * @return A DeployableObject
+ */
public DeployableObject getDeployableObject();
+ /**
+ * Returns the top level configuration bean, DConfigBeanRoot, associated with
+ * the deployment descriptor represented by the designated DDBeanRoot bean.
+ *
+ * @param bean The top level bean that represents the associated deployment descriptor.
+ *
+ * @return the DConfigBeanRoot for editing the server-specific properties required by the module.
+ *
+ * @throws ConfigurationException reports errors in generating a configuration bean
+ */
public DConfigBeanRoot getDConfigBeanRoot(DDBeanRoot bean) throws ConfigurationException;
+ /**
+ * Remove the root DConfigBean and all its children.
+ *
+ * @param bean the top leve DConfigBean to remove.
+ *
+ * @throws BeanNotFoundException the bean provided is not in this beans child list.
+ */
public void removeDConfigBean(DConfigBeanRoot bean) throws BeanNotFoundException;
+ /**
+ * Restore from disk to instantated objects all the DConfigBeans associated with a
+ * specific deployment descriptor. The beans may be fully or partially configured.
+ *
+ * @param inputArchive The input stream for the file from which the DConfigBeans
+ * should be restored.
+ * @param bean The DDBeanRoot bean associated with the deployment descriptor file.
+ *
+ * @return The top most parent configuration bean, DConfigBeanRoot
+ *
+ * @throws ConfigurationException reports errors in generating a configuration bean
+ */
public DConfigBeanRoot restoreDConfigBean(InputStream inputArchive, DDBeanRoot bean) throws ConfigurationException;
+ /**
+ * Save to disk all the configuration beans associated with a particular deployment
+ * descriptor file. The saved data may be fully or partially configured DConfigBeans.
+ * The output file format is recommended to be XML.
+ *
+ * @param outputArchive The output stream to which the DConfigBeans should be saved.
+ * @param bean The top level bean, DConfigBeanRoot, from which to be save.
+ *
+ * @throws ConfigurationException reports errors in storing a configuration bean
+ */
public void saveDConfigBean(OutputStream outputArchive, DConfigBeanRoot bean) throws ConfigurationException;
+ /**
+ * Restore from disk to a full set of configuration beans previously stored.
+ *
+ * @param inputArchive The input stream from which to restore the Configuration.
+ *
+ * @throws ConfigurationException reports errors in generating a configuration bean
+ */
public void restore(InputStream inputArchive) throws ConfigurationException;
+ /**
+ * Save to disk the current set configuration beans created for this deployable
+ * module. It is recommended the file format be XML.
+ *
+ * @param outputArchive The output stream to which to save the Configuration.
+ *
+ * @throws ConfigurationException reports errors in storing a configuration bean
+ */
public void save(OutputStream outputArchive) throws ConfigurationException;
}
1.2 +274 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DeploymentManager.java
Index: DeploymentManager.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/DeploymentManager.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DeploymentManager.java 16 Aug 2003 12:28:26 -0000 1.1
+++ DeploymentManager.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -71,51 +71,324 @@
import java.util.Locale;
/**
+ * 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.
*
* @version $Revision$ $Date$
*/
public interface DeploymentManager {
+ /**
+ * Retrieve the list of deployment targets supported by this DeploymentManager.
+ *
+ * @return A list of deployment Target designators the user may select for
+ * application deployment or <code>null</code> if there are none.
+ *
+ * @throws IllegalStateException is thrown when the method is called when
+ * running in disconnected mode.
+ */
public Target[] getTargets() throws IllegalStateException;
+ /**
+ * Retrieve the list of J2EE application modules distributed to the identified
+ * targets and that are currently running on the associated server or servers.
+ *
+ * @param moduleType A predefined designator for a J2EE module type.
+ * @param targetList A list of deployment Target designators the user wants
+ * checked for module run status.
+ *
+ * @return An array of TargetModuleID objects representing the running modules
+ * or <code>null</code> if there are none.
+ *
+ * @throws TargetException occurs when an invalid Target was provided.
+ * @throws IllegalStateException is thrown when the method is called when running
+ * in disconnected mode.
+ */
public TargetModuleID[] getRunningModules(ModuleType moduleType, Target[] targetList) throws TargetException, 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.
+ *
+ * @param moduleType A predefined designator for a J2EE module type.
+ * @param targetList A list of deployment Target designators the user wants checked
+ * for module not running status.
+ *
+ * @return An array of TargetModuleID objects representing the non-running modules
+ * or <code>null</code> if there are none.
+ *
+ * @throws TargetException occurs when an invalid Target was provided.
+ * @throws IllegalStateException is thrown when the method is called when running
+ * in disconnected mode.
+ */
public TargetModuleID[] getNonRunningModules(ModuleType moduleType, Target[] targetList) throws TargetException, IllegalStateException;
+ /**
+ * Retrieve the list of all J2EE application modules running or not running on the
+ * identified targets.
+ *
+ * @param moduleType A predefined designator for a J2EE module type.
+ * @param targetList A list of deployment Target designators the user wants checked
+ * for module not running status.
+ *
+ * @return An array of TargetModuleID objects representing all deployed modules
+ * running or not or <code>null</code> if there are no deployed modules.
+ *
+ * @throws TargetException occurs when an invalid Target was provided.
+ * @throws IllegalStateException is thrown when the method is called when running
+ * in disconnected mode.
+ */
public TargetModuleID[] getAvailableModules(ModuleType moduleType, Target[] targetList) throws TargetException, IllegalStateException;
+ /**
+ * Retrieve the object that provides server-specific deployment configuration
+ * information for the J2EE deployable component.
+ *
+ * @param dObj An object representing a J2EE deployable component.
+ *
+ * @return An object used to configure server-specific deployment information
+ *
+ * @throws InvalidModuleException The DeployableObject is an unknown or unsupported
+ * component for this configuration tool.
+ */
public DeploymentConfiguration createConfiguration(DeployableObject dObj) throws InvalidModuleException;
+ /**
+ * 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.
+ *
+ * @param targetList A list of server targets the user is specifying this application
+ * should be deployed to.
+ * @param moduleArchive The file name of the application archive to be distributed.
+ * @param deploymentPlan The file containing the runtime configuration information
+ * associated with this application archive.
+ *
+ * @return an object that tracks and reports the status of the distribution process.
+ *
+ * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
+ */
public ProgressObject distribute(Target[] targetList, File moduleArchive, File deploymentPlan) throws 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.
+ *
+ * @param targetList A list of server targets the user is specifying this application
+ * should be deployed to.
+ * @param moduleArchive The stream containing the application archive to be distributed.
+ * @param deploymentPlan The stream containing the runtime configuration information
+ * associated with this application archive.
+ *
+ * @return an object that tracks and reports the status of the distribution process.
+ *
+ * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
+ */
public ProgressObject distribute(Target[] targetList, InputStream moduleArchive, InputStream deploymentPlan) throws IllegalStateException;
+ /**
+ * Start the application running.
+ *
+ * <p>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.</p>
+ *
+ * @param moduleIDList An array of TargetModuleID objects representing the modules to be started.
+ *
+ * @return An object that tracks and reports the status of the start operation.
+ *
+ * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
+ */
public ProgressObject start(TargetModuleID[] moduleIDList) throws IllegalStateException;
+ /**
+ * Stop the application running.
+ *
+ * <p>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.</p>
+ *
+ * @param moduleIDList An array of TargetModuleID objects representing the modules to be stopped.
+ *
+ * @return An object that tracks and reports the status of the stop operation.
+ *
+ * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
+ */
public ProgressObject stop(TargetModuleID[] moduleIDList) throws IllegalStateException;
+ /**
+ * Remove the application from the target server.
+ *
+ * <p>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.
+ *
+ * @param moduleIDList An array of TargetModuleID objects representing the root
+ * modules to be undeployed.
+ *
+ * @return An object that tracks and reports the status of the stop operation.
+ *
+ * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
+ */
public ProgressObject undeploy(TargetModuleID[] moduleIDList) throws IllegalStateException;
+ /**
+ * This method designates whether this platform vendor provides application
+ * redeployment functionality. A value of true means it is supported. False
+ * means it is not.
+ *
+ * @return A value of true means redeployment is supported by this vendor's
+ * DeploymentManager. False means it is not.
+ */
public boolean isRedeploySupported();
+ /**
+ * (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.
+ *
+ * @param moduleIDList An array of designators of the applications to be updated.
+ * @param moduleArchive The file name of the application archive to be redeployed.
+ * @param deploymentPlan The deployment configuration information associated with
+ * this application archive.
+ *
+ * @return An object that tracks and reports the status of the redeploy operation.
+ *
+ * @throws UnsupportedOperationException this optional command is not supported by
+ * this implementation.
+ * @throws IllegalStateException is thrown when the method is called when running
+ * in disconnected mode.
+ */
public ProgressObject redeploy(TargetModuleID[] moduleIDList, File moduleArchive, File deploymentPlan) throws UnsupportedOperationException, 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.
+ *
+ * @param moduleIDList An array of designators of the applications to be updated.
+ * @param moduleArchive The stream containing the application archive to be redeployed.
+ * @param deploymentPlan The streeam containing the deployment configuration information
+ * associated with this application archive.
+ *
+ * @return An object that tracks and reports the status of the redeploy operation.
+ *
+ * @throws UnsupportedOperationException this optional command is not supported by
+ * this implementation.
+ * @throws IllegalStateException is thrown when the method is called when running
+ * in disconnected mode.
+ */
public ProgressObject redeploy(TargetModuleID[] moduleIDList, InputStream moduleArchive, InputStream deploymentPlan) throws UnsupportedOperationException, IllegalStateException;
+ /**
+ * 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).
+ */
public void release();
+ /**
+ * Returns the default locale supported by this implementation of
+ * javax.enterprise.deploy.spi subpackages.
+ *
+ * @return the default locale for this implementation.
+ */
public Locale getDefaultLocale();
+ /**
+ * Returns the active locale this implementation of
+ * javax.enterprise.deploy.spi subpackages is running.
+ *
+ * @return the active locale of this implementation.
+ */
public Locale getCurrentLocale();
+ /**
+ * Set the active locale for this implementation of
+ * javax.enterprise.deploy.spi subpackages to run.
+ *
+ * @param locale the locale to set
+ *
+ * @throws UnsupportedOperationException the provide locale is not supported.
+ */
public void setLocale(Locale locale) throws UnsupportedOperationException;
+ /**
+ * Returns an array of supported locales for this implementation.
+ *
+ * @return the list of supported locales.
+ */
public Locale[] getSupportedLocales();
+ /**
+ * Reports if this implementation supports the designated locale.
+ *
+ * @param locale the locale to check
+ *
+ * @return A value of <code>true</code> means it is supported and <code>false</code> it is not.
+ */
public boolean isLocaleSupported(Locale locale);
+ /**
+ * 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.
+ *
+ * @return a DConfigBeanVersionType object representing the platform
+ * version number for which these beans are provided.
+ */
public DConfigBeanVersionType getDConfigBeanVersion();
+ /**
+ * Returns <code>true</code> if the configuration beans support the J2EE platform
+ * version specified. It returns <code>false</code> if the version is not supported.
+ *
+ * @param version a DConfigBeanVersionType object representing the J2EE
+ * platform version for which support is requested.
+ *
+ * @return <code>true</code> if the version is supported and 'false if not.
+ */
public boolean isDConfigBeanVersionSupported(DConfigBeanVersionType version);
+ /**
+ * Set the configuration beans to be used to the J2EE platform version specified.
+ *
+ * @param version a DConfigBeanVersionType object representing the J2EE
+ * platform version for which support is requested.
+ *
+ * @throws DConfigBeanVersionUnsupportedException when the requested bean
+ * version is not supported.
+ */
public void setDConfigBeanVersion(DConfigBeanVersionType version) throws DConfigBeanVersionUnsupportedException;
}
1.2 +10 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/Target.java
Index: Target.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/Target.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Target.java 16 Aug 2003 12:28:26 -0000 1.1
+++ Target.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -60,11 +60,20 @@
package javax.enterprise.deploy.spi;
/**
+ * A Target interface represents a single logical core server of one instance of a
+ * J2EE platform product. It is a designator for a server and the implied location
+ * to copy a configured application for the server to access.
*
* @version $Revision$ $Date$
*/
public interface Target {
+ /**
+ * Retrieve the name of the target server.
+ */
public String getName();
+ /**
+ * Retrieve other descriptive information about the target.
+ */
public String getDescription();
}
1.2 +39 -1 incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/TargetModuleID.java
Index: TargetModuleID.java
===================================================================
RCS file: /home/cvs/incubator-geronimo/specs/j2ee-deployment/src/java/javax/enterprise/deploy/spi/TargetModuleID.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- TargetModuleID.java 16 Aug 2003 12:28:26 -0000 1.1
+++ TargetModuleID.java 30 Aug 2003 02:16:58 -0000 1.2
@@ -60,19 +60,57 @@
package javax.enterprise.deploy.spi;
/**
+ * A TargetModuleID interface represents a unique identifier for a deployed
+ * application module. A deployable application module can be an EAR, JAR, WAR or
+ * RAR file. A TargetModuleID can represent a root module or a child module. A
+ * root module TargetModuleID has no parent. It represents a deployed EAR file or
+ * standalone module. A child module TargetModuleID represents a deployed sub
+ * module of a J2EE application. A child TargetModuleID has only one parent, the
+ * super module it was bundled and deployed with. The identifier consists of the
+ * target name and the unique identifier for the deployed application module.
*
* @version $Revision$ $Date$
*/
public interface TargetModuleID {
+ /**
+ * Retrieve the target server that this module was deployed to.
+ *
+ * @return an object representing a server target.
+ */
public Target getTarget();
+ /**
+ * Retrieve the id assigned to represent the deployed module.
+ */
public String getModuleID();
+ /**
+ * If this TargetModulID represents a web module retrieve the URL for it.
+ *
+ * @return the URL of a web module or null if the module is not a web module.
+ */
public String getWebURL();
+ /**
+ * Retrieve the identifier representing the deployed module.
+ */
public String toString();
+ /**
+ * Retrieve the identifier of the parent object of this deployed module. If
+ * there is no parent then this is the root object deployed. The root could
+ * represent an EAR file or it could be a stand alone module that was deployed.
+ *
+ * @return the TargetModuleID of the parent of this object. A <code>null</code>
+ * value means this module is the root object deployed.
+ */
public TargetModuleID getParentTargetModuleID();
+ /**
+ * Retrieve a list of identifiers of the children of this deployed module.
+ *
+ * @return a list of TargetModuleIDs identifying the childern of this object.
+ * A <code>null</code> value means this module has no children
+ */
public TargetModuleID[] getChildTargetModuleID();
}