/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 * 
 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 * 
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License. You can obtain
 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
 * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 * 
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
 * Sun designates this particular file as subject to the "Classpath" exception
 * as provided by Sun in the GPL Version 2 section of the License file that
 * accompanied this code.  If applicable, add the following below the License
 * Header, with the fields enclosed by brackets [] replaced by your own
 * identifying information: "Portions Copyrighted [year]
 * [name of copyright owner]"
 * 
 * Contributor(s):
 * 
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

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 javax.enterprise.deploy.shared.ModuleType;
import java.io.File;
import java.io.InputStream;
import java.util.Locale;

import java.lang.Deprecated;

/**
 * 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(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 '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(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
     *                   '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(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.
     * @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.
     * @deprecated as of Java EE 5, replaced with {@link #distribute(Target[], ModuleType, InputStream, InputStream)}
     */
    
    public ProgressObject distribute(Target[] targetList,
            InputStream moduleArchive, InputStream 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 moduleType   The module type of this application archive.
     * @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, ModuleType type,
            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 java.lang.UnsupportedOperationException this optional command
     *         is not supported by this implementation.
     */
    
    public ProgressObject redeploy(TargetModuleID[] moduleIDList,
            File moduleArchive, File deploymentPlan)
            throws java.lang.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 java.lang.UnsupportedOperationException this optional command
     *         is not supported by this implementation.
     */
    
    public ProgressObject redeploy(TargetModuleID[] moduleIDList,
            InputStream moduleArchive, InputStream deploymentPlan)
            throws java.lang.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 java.lang.UnsupportedOperationException the provide locale is
     *      not supported.
     */
    public void setLocale(Locale locale)
        throws java.lang.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;
}
