/*
 *                 Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 *
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2004 Sun
 * Microsystems, Inc. All Rights Reserved.
 */


package org.netbeans.modules.j2ee.deployment.plugins.api;

import javax.enterprise.deploy.spi.Target;
import javax.enterprise.deploy.spi.status.ProgressObject;

/**
 * Server lifecycle services from the IDE.  J2eeserver will use these  
 * services to automatically start or stop admin server and managed (virtual) 
 * target servers (in debug mode) during deployment or debugging execution.
 *
 * @see OptionalDeploymentManagerFactory
 * @author George FinKlang
 * @author  nn136682
 * @version 1.0
 */
public abstract class StartServer {
    
    /**
     * Returns true if the admin server is also the given target server (share the same vm).
     * Start/stopping/debug apply to both servers.  When the given target server is null,
     * service should return true when admin server is also some target.
     * @param target the target server in question; could be null.
     * @return true when admin is also target server
     */
    public abstract boolean isAlsoTargetServer(Target target);
    
    /**
     * Returns true if the admin server can be started through this spi.
     */
    public abstract boolean supportsStartDeploymentManager();
    
    
    /**
     * Starts the admin server. Note that this means that the DeploymentManager
     * was originally created disconnected. After calling this, the DeploymentManager
     * will be connected, so any old cached DeploymentManager will be discarded.
     * All diagnostics should be communicated through ProgressObject without exceptions thrown.
     *
     * @return ProgressObject object used to monitor start server progress
     */
    public abstract ProgressObject startDeploymentManager();
    
    /**
     * Stops the admin server. The DeploymentManager object will be disconnected.
     * All diagnostic should be communicated through ServerProgres with no
     * exceptions thrown.
     * @return ServerProgress object used to monitor start server progress
     */
    public abstract ProgressObject stopDeploymentManager();
    
    
    /**
     * Returns true if the admin server should be started before server deployment configuration.
     */
    public abstract boolean needsStartForConfigure();
    
    /**
     * Returns true if the admin server should be started before asking for
     * target list.
     */
    public abstract boolean needsStartForTargetList();
    
    /**
     * Returns true if the admin server should be started before admininistrative configuration.
     */
    public abstract boolean needsStartForAdminConfig();
    
    /**
     * Returns true if this admin server is running.
     */
    public abstract boolean isRunning();
    
    /**
     * Returns true if the given target is in debug mode.
     */
    public abstract boolean isDebuggable(Target target);
    
    /**
     * Start or restart the target in debug mode.
     * If target is also domain admin, the amdin is restarted in debug mode.
     * All diagnostic should be communicated through ServerProgres with no exceptions thrown.
     * @param target the target server
     * @return ServerProgress object to monitor progress on start operation
     */
    public abstract ProgressObject startDebugging(Target target);
    
    /**
     * Returns the host/port necessary for connecting to the server's debug information.
     */
    public abstract ServerDebugInfo getDebugInfo(Target target);
}