[Ejtools-cvs] CVS: thirdparty/sun/jsr88/src/main/javax/enterprise/deploy/spi DConfigBean.java,NONE,1

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/ejtools/thirdparty/sun/jsr88/src/main/javax/enterprise/deploy/spi
In directory usw-pr-cvs1:/tmp/cvs-serv31212/sun/jsr88/src/main/javax/enterprise/deploy/spi

Added Files:
	DConfigBean.java DConfigBeanRoot.java 
	DeploymentConfiguration.java DeploymentManager.java 
	Target.java TargetModuleID.java 
Log Message:
Initial Import

--- NEW FILE: DConfigBean.java ---
package javax.enterprise.deploy.spi;

import java.beans.PropertyChangeListener;
import javax.enterprise.deploy.model.*;
import javax.enterprise.deploy.spi.exceptions.ConfigurationException;
import javax.enterprise.deploy.spi.exceptions.BeanNotFoundException;

/**
 * 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:
 * <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.
 */
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.
     *
     * A given server vendor will need to specify some 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 'null' 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.
     *
     * @return The DConfigBean to display the server-specific properties 
     *         for the standard bean.
     * @param bean The DDBean containing the XML data to be 
     *        evaluated.
     * @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.
     *
     * @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);

}

--- NEW FILE: DConfigBeanRoot.java ---
/*
 * DConfigBeanRoot.java
 *
 * Created on July 18, 2001, 12:45 PM
 */

package javax.enterprise.deploy.spi;

/**
 * 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 DeploymentConfigurator.
 *
 * @author  gfink
 * @version 
 */
public interface DConfigBeanRoot extends DConfigBean {

}

--- NEW FILE: DeploymentConfiguration.java ---
/*
 * Configurator.java
 *
 * Created on May 14, 2001, 4:25 PM
 */

package javax.enterprise.deploy.spi;

import javax.enterprise.deploy.model.*;
import javax.enterprise.deploy.spi.exceptions.ConfigurationException;
import javax.enterprise.deploy.spi.exceptions.BeanNotFoundException;
import java.io.InputStream;
import java.io.OutputStream;

/**
 * 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.
 *
 * @author gfink
 * @version 0.1
 */
public interface DeploymentConfiguration {

    /**
	 * Returns an object that provides access to
     * the deployment descriptor data and classes
     * of a J2EE module.
     * @return 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 provides 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 generating 
     *           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
     */    
    public void save(OutputStream outputArchive) throws 
            ConfigurationException;

}

--- NEW FILE: DeploymentManager.java ---

package javax.enterprise.deploy.spi;

import javax.enterprise.deploy.spi.status.*;
import javax.enterprise.deploy.spi.exceptions.*;
import javax.enterprise.deploy.model.DeployableObject;
import javax.enterprise.deploy.shared.DConfigBeanVersionType;
import java.io.File;
import java.io.InputStream;
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.
 */
public interface DeploymentManager
{

   /**
    * Retrieve the list of deployment targets supported by 
    * this DeploymentManager.
    *
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @return   A list of deployment Target designators the 
    *           user may select for application deployment or 'null'
    *           if there are none.
    */
	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 'null' if there
    *                   are none.
    *
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @throws TargetException An invalid Target designator
    *                   encountered.
    */
	public TargetModuleID[] getRunningModules(int 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 'null' if
    *                   there are none.
    *
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @throws TargetException An invalid Target designator
    *                   encountered.
    */
	public TargetModuleID[] getNonRunningModules(int 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
    *                   'null' if there are no deployed modules.
    *
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @throws TargetException An invalid Target designator
    *                   encountered.
    */
	public TargetModuleID[] getAvailableModules(int 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.
    * @throws InvalidModuleException The DeployableObject is an
    *                      unknown or unsupport 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 be deployed to. 
    * @param moduleArchive The file name of the application archive
    *                      to be disrtibuted.
    * @param deploymentPlan The XML file containing the runtime 
    *                       configuration information associated with
    *                       this application archive.
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @return ProgressObject an object that tracks and reports the 
    *                       status of the distribution process.
    */

	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 be deployed to. 
    * @param moduleArchive The input stream containing the application 
    *                      archive to be disrtibuted.
    * @param deploymentPlan The input stream containing the deployment
    *                       configuration information associated with
    *                       this application archive.
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @return ProgressObject an object that tracks and reports the 
    *                       status of the distribution process.
    *
    */

	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.
    *
    * @param moduleIDList  A array of TargetModuleID objects 
    *                    representing the modules to be started.
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @return ProgressObject an object that tracks and reports the 
    *                       status of the start operation.
    */

    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.
    *
    * @param moduleIDList  A array of TargetModuleID objects 
    *                    representing the modules to be stopped.
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @return ProgressObject an object that tracks and reports the 
    *                       status of the stop operation.
    */

	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 stopped.
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @return ProgressObject an object that tracks and reports the 
    *                       status of the stop operation.
    */

	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 disrtibuted.
    * @param deploymentPlan The deployment configuration information
    *                       associated with this application archive.
    * @return ProgressObject an object that tracks and reports the
    *                       status of the redeploy operation.
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @throws UnsupportedOperationException this optional command
    *         is not supported by this implementation.
    */

    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 input stream containing the application
    *                      archive to be disrtibuted.
    * @param deploymentPlan The input stream containing the runtime
    *                       configuration information associated with
    *                       this application archive.
    * @return ProgressObject an object that tracks and reports the
    *                       status of the redeploy operation.
    * @throws IllegalStateException is thrown when the method is
    *                    called when running in disconnected mode.
    * @throws UnsupportedOperationException this optional command
    *         is not supported by this implementation.
    */

    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 Locale the default locale for this implementation.
    */
    public Locale getDefaultLocale();

   /**
    * Returns the active locale this implementation of
    * javax.enterprise.deploy.spi subpackages is running.
    *
    * @return Locale the active locale of this implementation.
    */
    public Locale getCurrentLocale();

   /**
    * Set the active locale for this implementation of
    * javax.enterprise.deploy.spi subpackages to run.
    *
    * @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 Locale[] the list of supported locales.
    */
    public Locale[] getSupportedLocales();

   /**
    * Reports if this implementation supports the designated locale.
    *
    * @return  A value of 'true' means it is support and 'false' 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 'true' if the configuration beans support the J2EE platform
    * version specified.  It returns 'false' if the version is
    * not supported.
    *
    * @param version a DConfigBeanVersionType object representing the 
    *	J2EE platform version for which support is requested.
    * @return 'true' 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 specificed.
    *
    * @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;
}

--- NEW FILE: Target.java ---

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.
 */
public interface Target
{
   /**
    * Retrieve the name of the target server.
    */
   public String getName();

   /**
    * Retrieve other descriptive information
    * about the target.
    */
   public String getDescription();
}

--- NEW FILE: TargetModuleID.java ---

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 stand alone 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. 
 */
public interface TargetModuleID
{
   /**
    * Retrieve the name of the target server.
    * this module was deployed to.
    *
    * @return Target an object representing
    *         a server target.
    */
   public Target getTarget();

   /**
    * Retrieve the id assigned to represent
    * the deployed module.
    */
   public String getModuleID();

   /**
    * 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 childern
    */
   public TargetModuleID[] getChildTargetModuleID();
}

[Ejtools-cvs] CVS: thirdparty/sun/jsr88/src/main/javax/enterprise/deploy/spi DConfigBean.java,NONE,1

[Ejtools-cvs] CVS: thirdparty/sun/jsr88/src/main/javax/enterprise/deploy/spi DConfigBean.java,NONE,1.1 DConfigBeanRoot.java,NONE,1.1 DeploymentConfiguration.java,NONE,1.1 DeploymentManager.java,NONE,1.1 Target.java,NONE,1.1 TargetModuleID.java,NONE,1.1