## org.eclipse.wst.server.core
Interface IServer

All Superinterfaces:
  IServerAttributes

    public interface IServer

extends IServerAttributes

Represents a server instance. Every server is an instance of a particular, fixed server type.

Not surprisingly, the notion of server is central in the web tools server infrastructure. In this context, understand that a server is a web server of some ilk. It could be a simple web server lacking Java support, or an J2EE based server, or perhaps even some kind of database server. A more exact definition is not required for the purposes of this API. From a tool-centric point of view, a server is something that the developer is writing "content" for. The unit of content is termed a module. In a sense, the server exists, but lacks useful content. The development task is to provide that content. The content can include anything from simple, static HTML web pages to complex, highly dynamic web applications. In the course of writing and debugging this content, the developer will want to test their content on a web server, to see how it gets served up. For this they will need to launch a server process running on some host machine (often the local host on which the IDE is running), or attach to a server that's already running on a remote (or local) host. The newly developed content sitting in the developer's workspace needs to end up in a location and format that the running server can use for its serving purposes.

In this picture, an `IServer` object is a proxy for the real web server. Through this proxy, a client can configure the server, and start, stop, and restart it.

The server framework maintains a global list of all known server instances (`ServerCore.getServers()`).

[rough notes: Server has a state. Server can be started, stopped, and restarted. To modify server attributes, get a working copy, modify it, and then save it to commit the changes. Server attributes. Serialization. Chained working copies for runtime, server configuration. Server has a set of root modules. Modules have state wrt a server. Restarting modules. ]

Two servers are identical if and only if they have the same id.

This interface is not intended to be implemented by clients.

Since:
  1.0

Nested Class Summary
`static interface` `IServer.IOperationListener` An operation listener is used to receive notification back about a specific server operation, such as starting or stopping a server.

Field Summary
`static int` `PUBLISH_AUTO` Publish kind constant (value 3) indicating an automatic publish request.
`static int` `PUBLISH_CLEAN` Publish kind constant (value 4) indicating a publish clean request
`static int` `PUBLISH_FULL` Publish kind constant (value 2) indicating a full publish request.
`static int` `PUBLISH_INCREMENTAL` Publish kind constant (value 1) indicating an incremental publish request.
`static int` `PUBLISH_STATE_FULL` Publish state constant (value 3) indicating that a full publish is required.
`static int` `PUBLISH_STATE_INCREMENTAL` Publish state constant (value 2) indicating that an incremental publish is required.
`static int` `PUBLISH_STATE_NONE` Publish state constant (value 1) indicating that there is no publish required.
`static int` `PUBLISH_STATE_UNKNOWN` Publish state constant (value 0) indicating that it's in an unknown state.
`static int` `STATE_STARTED` Server state constant (value 2) indicating that the server is ready to serve content.
`static int` `STATE_STARTING` Server state constant (value 1) indicating that the server is starting, but not yet ready to serve content.
`static int` `STATE_STOPPED` Server state constant (value 4) indicating that the server is stopped.
`static int` `STATE_STOPPING` Server state constant (value 3) indicating that the server is shutting down.
`static int` `STATE_UNKNOWN` Server state constant (value 0) indicating that the server is in an unknown state.

Method Summary
`void` `addPublishListener(IPublishListener listener)` Adds a publish listener to this server.
`void` `addServerListener(IServerListener listener)` Adds the given server state listener to this server.
`void` `addServerListener(IServerListener listener, int eventMask)` Adds the given server state listener to this server.
`IStatus` `canControlModule(IModule[] module, IProgressMonitor monitor)` Returns whether the given module can be restarted.
`IStatus` `canPublish()` Returns whether this server is in a state that it can be published to.
`IStatus` `canRestart(java.lang.String mode)` Returns whether this server is in a state that it can be restarted in the given mode.
`IStatus` `canStart(java.lang.String launchMode)` Returns whether this server is in a state that it can be started in the given mode.
`IStatus` `canStop()` Returns whether this server is in a state that it can be stopped.
`ILaunch` `getLaunch()` Returns the launch that was used to start the server, if available.
`ILaunchConfiguration` `getLaunchConfiguration(boolean create, IProgressMonitor monitor)` Return the launch configuration for this server.
`java.lang.String` `getMode()` Returns the ILaunchManager mode that the server is in.
`int` `getModulePublishState(IModule[] module)` Returns the module's sync state.
`boolean` `getModuleRestartState(IModule[] module)` Check if the given module is in sync on the server.
`int` `getModuleState(IModule[] module)` Returns the current state of the given module on this server.
`int` `getServerPublishState()` Returns the server's sync state.
`boolean` `getServerRestartState()` Returns whether this server is out of sync and needs to be restarted.
`int` `getServerState()` Returns the current state of this server.
`int` `getStartTimeout()` Returns the start timeout in seconds.
`int` `getStopTimeout()` Returns the stop timeout in seconds.
`IStatus` `publish(int kind, IProgressMonitor monitor)` Publish to the server using the progress monitor.
`void` `publish(int kind, java.util.List<IModule[]> modules, IAdaptable info, IServer.IOperationListener listener)` Publish one or more modules to the server.
`void` `removePublishListener(IPublishListener listener)` Removes a publish listener from this server.
`void` `removeServerListener(IServerListener listener)` Removes the given server state listener from this server.
`void` `restart(java.lang.String launchMode, IProgressMonitor monitor)` Asynchronously restarts this server.
`void` `restartModule(IModule[] module, IServer.IOperationListener listener)` Asynchronously restarts the given module on the server.
`boolean` `shouldPublish()` Returns true if the server should be published to.
`boolean` `shouldRestart()` Returns true if the server should be restarted.
`void` `start(java.lang.String launchMode, IProgressMonitor monitor)` Asynchronously starts this server in the given launch mode.
`void` `startModule(IModule[] module, IServer.IOperationListener listener)` Asynchronously starts this server in the given launch mode.
`void` `stop(boolean force)` Asynchronously stops this server.
`void` `stop(boolean force, IServer.IOperationListener listener)` Asynchronously stops this server.
`void` `stopModule(IModule[] module, IServer.IOperationListener listener)` Asynchronously stops the given module.
`void` `synchronousRestart(java.lang.String launchMode, IProgressMonitor monitor)` Deprecated. use `#restart(String, IServer.IOperationListener)` instead
`void` `synchronousStart(java.lang.String launchMode, IProgressMonitor monitor)` Deprecated. use `#start(String, IServer.IOperationListener)` instead
`void` `synchronousStop(boolean force)` Deprecated. use `stop(boolean, IOperationListener)` instead

Methods inherited from interface org.eclipse.wst.server.core.IServerAttributes
`canModifyModules, createWorkingCopy, delete, getAdapter, getChildModules, getHost, getId, getModules, getName, getRootModules, getRuntime, getServerConfiguration, getServerPorts, getServerType, isReadOnly, isWorkingCopy, loadAdapter`

Field Detail

### STATE_UNKNOWN

    static final int STATE_UNKNOWN

  Server state constant (value 0) indicating that the server is in an unknown state.

  See Also:
    `getServerState()`, `getModuleState(IModule[])`, Constant Field Values

### STATE_STARTING

    static final int STATE_STARTING

  Server state constant (value 1) indicating that the server is starting, but not yet ready to serve content.

  See Also:
    `getServerState()`, `getModuleState(IModule[])`, Constant Field Values

### STATE_STARTED

    static final int STATE_STARTED

  Server state constant (value 2) indicating that the server is ready to serve content.

  See Also:
    `getServerState()`, `getModuleState(IModule[])`, Constant Field Values

### STATE_STOPPING

    static final int STATE_STOPPING

  Server state constant (value 3) indicating that the server is shutting down.

  See Also:
    `getServerState()`, `getModuleState(IModule[])`, Constant Field Values

### STATE_STOPPED

    static final int STATE_STOPPED

  Server state constant (value 4) indicating that the server is stopped.

  See Also:
    `getServerState()`, `getModuleState(IModule[])`, Constant Field Values

### PUBLISH_STATE_UNKNOWN

    static final int PUBLISH_STATE_UNKNOWN

  Publish state constant (value 0) indicating that it's in an unknown state.

  See Also:
    `getServerPublishState()`, `getModulePublishState(IModule[])`, Constant Field Values

### PUBLISH_STATE_NONE

    static final int PUBLISH_STATE_NONE

  Publish state constant (value 1) indicating that there is no publish required.

  See Also:
    `getServerPublishState()`, `getModulePublishState(IModule[])`, Constant Field Values

### PUBLISH_STATE_INCREMENTAL

    static final int PUBLISH_STATE_INCREMENTAL

  Publish state constant (value 2) indicating that an incremental publish is required.

  See Also:
    `getServerPublishState()`, `getModulePublishState(IModule[])`, Constant Field Values

### PUBLISH_STATE_FULL

    static final int PUBLISH_STATE_FULL

  Publish state constant (value 3) indicating that a full publish is required.

  See Also:
    `getServerPublishState()`, `getModulePublishState(IModule[])`, Constant Field Values

### PUBLISH_INCREMENTAL

    static final int PUBLISH_INCREMENTAL

  Publish kind constant (value 1) indicating an incremental publish request.

  See Also:
    `publish(int, IProgressMonitor)`, Constant Field Values

### PUBLISH_FULL

    static final int PUBLISH_FULL

  Publish kind constant (value 2) indicating a full publish request.

  See Also:
    `publish(int, IProgressMonitor)`, Constant Field Values

### PUBLISH_AUTO

    static final int PUBLISH_AUTO

  Publish kind constant (value 3) indicating an automatic publish request.

  See Also:
    `publish(int, IProgressMonitor)`, Constant Field Values

### PUBLISH_CLEAN

    static final int PUBLISH_CLEAN

  Publish kind constant (value 4) indicating a publish clean request

  See Also:
    `publish(int, IProgressMonitor)`, Constant Field Values

Method Detail

### getServerState

    int getServerState()

  Returns the current state of this server.

  Note that this operation is guaranteed to be fast (it does not actually communicate with any actual server).

  Returns:
    one of the server state (`STATE_XXX`) constants declared on `IServer`

### getMode

    java.lang.String getMode()

  Returns the ILaunchManager mode that the server is in. This method will return null if the server is not running.

  Returns:
    the mode in which a server is running, one of the mode constants defined by `org.eclipse.debug.core.ILaunchManager`, or `null` if the server is stopped.

### getServerPublishState

    int getServerPublishState()

  Returns the server's sync state.

  Returns:
    one of the PUBLISH_XXX state flags

### addServerListener

    void addServerListener(IServerListener listener)

  Adds the given server state listener to this server. Once registered, a listener starts receiving notification of state changes to this server. The listener continues to receive notifications until it is removed. Has no effect if an identical listener is already registered.

  Parameters:
    `listener` - the server listener
  See Also:
    `removeServerListener(IServerListener)`

### addServerListener

    void addServerListener(IServerListener listener,
                           int eventMask)

  Adds the given server state listener to this server. Once registered, a listener starts receiving notification of state changes to this server. The listener continues to receive notifications until it is removed. Has no effect if an identical listener is already registered.

  Parameters:
    `listener` - the server listener
    `eventMask` - the bit-wise OR of all event types of interest to the listener
  See Also:
    `removeServerListener(IServerListener)`

### removeServerListener

    void removeServerListener(IServerListener listener)

  Removes the given server state listener from this server. Has no effect if the listener is not registered.

  Parameters:
    `listener` - the listener
  See Also:
    `addServerListener(IServerListener)`

### addPublishListener

    void addPublishListener(IPublishListener listener)

  Adds a publish listener to this server. Has no effect if an identical listener is already registered.

  Parameters:
    `listener` - the publish listener
  See Also:
    `removePublishListener(IPublishListener)`

### removePublishListener

    void removePublishListener(IPublishListener listener)

  Removes a publish listener from this server. Has no effect if the listener is not registered.

  Parameters:
    `listener` - the publish listener
  See Also:
    `addPublishListener(IPublishListener)`

### canPublish

    IStatus canPublish()

  Returns whether this server is in a state that it can be published to.

  Returns:
    a status object with code `IStatus.OK` if the server can be published to, otherwise a status object indicating what is wrong

### shouldPublish

    boolean shouldPublish()

  Returns true if the server should be published to. This is `true` when the server can be published to and the server's publish state or any module's publish state is not PUBLISH_STATE_NONE.

  Returns:
    boolean
  Since:
    2.0

### publish

    IStatus publish(int kind,
                    IProgressMonitor monitor)

  Publish to the server using the progress monitor. The result of the publish operation is returned as an IStatus.

  This method should not be called from the UI thread. Publishing is long- running and may trigger resource change events or builds. Although this framework is safe, there is no guarantee that other bundles are UI-safe and the risk of UI deadlock is high.

  Parameters:
    `kind` - the kind of publish being requested. Valid values are:
    - `PUBLISH_FULL`- indicates a full publish.
    - `PUBLISH_INCREMENTAL`- indicates a incremental publish.
    - `PUBLISH_CLEAN`- indicates a clean request. Clean throws out all state and cleans up the module on the server before doing a full publish.
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Returns:
    status indicating what (if anything) went wrong
  See Also:
    `publish(int, List, IAdaptable, IOperationListener)`

### publish

    void publish(int kind,
                 java.util.List<IModule[]> modules,
                 IAdaptable info,
                 IServer.IOperationListener listener)

  Publish one or more modules to the server.

  The operation listener can be used to add a listener for notification of the publish result. The listener will be called with a single successful status (severity OK) when the server has finished publishing, or a single failure (severity ERROR) if there was an error publishing to the server.

  This method should not be called from the UI thread. Publishing is long- running and may trigger resource change events or builds. Although this framework is safe, there is no guarantee that other bundles are UI-safe and the risk of UI deadlock is high.

  Parameters:
    `kind` - the kind of publish being requested. Valid values are:
    - `PUBLISH_FULL`- indicates a full publish.
    - `PUBLISH_INCREMENTAL`- indicates a incremental publish.
    - `PUBLISH_CLEAN`- indicates a clean request. Clean throws out all state and cleans up the module on the server before doing a full publish.
    `modules` - a list of modules to publish, or `null` to publish all modules
    `info` - the IAdaptable (or `null`) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is not `null`, it should minimally contain an adapter for the Shell class.
    `listener` - an operation listener to receive notification when this operation is done, or `null` if notification is not required
  Since:
    3.0

### canStart

    IStatus canStart(java.lang.String launchMode)

  Returns whether this server is in a state that it can be started in the given mode.

  Parameters:
    `launchMode` - a mode in which a server can be launched, one of the mode constants defined by `org.eclipse.debug.core.ILaunchManager`
  Returns:
    a status object with code `IStatus.OK` if the server can be started, otherwise a status object indicating why it can't

### start

    void start(java.lang.String launchMode,
               IProgressMonitor monitor)
               throws CoreException

  Asynchronously starts this server in the given launch mode.

  If canStart(launchMode) is false, this method will throw an exception.

  If the caller wants to listen for failure or success of the server starting, it can add a server listener or use the version of this method that takes an operation listener as a parameter.

  Parameters:
    `launchMode` - a mode in which a server can be launched, one of the mode constants defined by `org.eclipse.debug.core.ILaunchManager`
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Throws:
    `CoreException` - if an error occurs while trying to start the server
  See Also:
    `#start(String, IServer.IOperationListener)`

### canRestart

    IStatus canRestart(java.lang.String mode)

  Returns whether this server is in a state that it can be restarted in the given mode. Note that only servers that are currently running can be restarted.

  Parameters:
    `mode` - a mode in which a server can be launched, one of the mode constants defined by `org.eclipse.debug.core.ILaunchManager`
  Returns:
    a status object with code `IStatus.OK` if the server can be restarted, otherwise a status object indicating why it can't

### shouldRestart

    boolean shouldRestart()

  Returns true if the server should be restarted. This is `true` when the server can be restarted and the server's restart state or any module's restart states is not false.

  Returns:
    boolean
  Since:
    2.0

### getServerRestartState

    boolean getServerRestartState()

  Returns whether this server is out of sync and needs to be restarted. This method will return false when the server is not running.

  [issue: Need to explain what is it that can get out of "out of sync" here, and how this can happen.]

  Returns:
    `true` if this server is out of sync and needs to be restarted, and `false` otherwise (e.g., if the contents have not been modified and the server process is still in sync); the result is unspecified if the server is not currently running

### restart

    void restart(java.lang.String launchMode,
                 IProgressMonitor monitor)

  Asynchronously restarts this server. This operation does nothing if this server cannot be stopped (`canRestart(String)` returns `false`. This method cannot be used to start the server from a stopped state.

  If the caller wants to listen for failure or success of the server restarting, it can add a server listener or use the version of this method that takes an operation listener as a parameter.

  Parameters:
    `launchMode` - a mode in which a server can be launched, one of the mode constants defined by `org.eclipse.debug.core.ILaunchManager`
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  See Also:
    `#restart(String, IServer.IOperationListener)`

### canStop

    IStatus canStop()

  Returns whether this server is in a state that it can be stopped. Servers can be stopped if they are not already stopped and if they belong to a state-set that can be stopped.

  Returns:
    a status object with code `IStatus.OK` if the server can be stopped, otherwise a status object indicating why it can't

### stop

    void stop(boolean force)

  Asynchronously stops this server. This operation does nothing if this server cannot be stopped (`canStop()` returns `false`.

  If force is `false`, it will attempt to stop the server normally/gracefully. If force is `true`, then the server process will be terminated any way that it can.

  If the caller wants to listen for success or failure of the server stopping, it can add a server listener or use the version of this method that takes an operation listener as a parameter.

  Parameters:
    `force` - `true` to kill the server, or `false` to stop normally
  See Also:
    `#start(String, IServer.IOperationListener)`

### stop

    void stop(boolean force,
              IServer.IOperationListener listener)

  Asynchronously stops this server. This operation does nothing if this server cannot be stopped (`canStop()` returns `false`.

  If force is `false`, it will attempt to stop the server normally/gracefully. If force is `true`, then the server process will be terminated any way that it can.

  The operation listener can be used to add a listener for notification of this specific server stop. The listener will be called with a single successful status (severity OK) when the server has finished stopping, or a single failure (severity ERROR) if there was an error stopping the server.

  Parameters:
    `force` - `true` to kill the server, or `false` to stop normally
    `listener` - an operation listener to receive notification when this operation is done, or `null` if notification is not required

### getModuleState

    int getModuleState(IModule[] module)

  Returns the current state of the given module on this server. Returns `STATE_UNKNOWN` if the module is not among the ones associated with this server.

  Parameters:
    `module` - the module
  Returns:
    one of the state (`STATE_XXX`) constants declared on `IServer`

### getModulePublishState

    int getModulePublishState(IModule[] module)

  Returns the module's sync state.

  Parameters:
    `module` - the module
  Returns:
    one of the PUBLISH_STATE_XXX state flags

### getModuleRestartState

    boolean getModuleRestartState(IModule[] module)

  Check if the given module is in sync on the server. It should return true if the module should be restarted (is out of sync) or false if the module does not need to be restarted.

  Parameters:
    `module` - the module
  Returns:
    boolean

### canControlModule

    IStatus canControlModule(IModule[] module,
                             IProgressMonitor monitor)

  Returns whether the given module can be restarted.

  This method has a progress monitor because it may involve plugin and class loading. No communication to the server will occur.

  Parameters:
    `module` - the module
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Returns:
    a status object with code `IStatus.OK` if the module can be restarted, otherwise a status object indicating why it can't

### startModule

    void startModule(IModule[] module,
                     IServer.IOperationListener listener)

  Asynchronously starts this server in the given launch mode.

  If canStart(launchMode) is false, this method will throw an exception.

  The operation listener can be used to add a listener for notification of this specific module start. The listener will be called with a single successful status (severity OK) when the module has finished starting, or a single failure (severity ERROR) if there was an error starting the module.

  Parameters:
    `module` - the module to be started
    `listener` - an operation listener to receive notification when this operation is done, or `null` if notification is not required

### stopModule

    void stopModule(IModule[] module,
                    IServer.IOperationListener listener)

  Asynchronously stops the given module. This operation does nothing if this module cannot be stopped.

  The operation listener can be used to add a listener for notification of this specific module stop. The listener will be called with a single successful status (severity OK) when the module has finished stopping, or a single failure (severity ERROR) if there was an error stopping the module.

  Parameters:
    `module` - the module to be stopped
    `listener` - an operation listener to receive notification when this operation is done, or `null` if notification is not required

### restartModule

    void restartModule(IModule[] module,
                       IServer.IOperationListener listener)

  Asynchronously restarts the given module on the server.

  The implementation should update the module sync state and fire an event for the module. If the module does not exist on the server, an exception will be thrown.

  [issue: If the module was just published to the server and had never been started, would is be ok to "start" the module using this method?]

  Parameters:
    `module` - the module to be started
    `listener` - an operation listener to receive notification when this operation is done, or `null` if notification is not required

### getLaunchConfiguration

    ILaunchConfiguration getLaunchConfiguration(boolean create,
                                                IProgressMonitor monitor)
                                                throws CoreException

  Return the launch configuration for this server. If one does not exist, it will be created if "create" is true, and otherwise will return `null`. Will return `null` if this server type is invalid or has no associated launch configuration type (i.e. this server type cannot be started).

  Parameters:
    `create` - `true` if a new launch configuration should be created if there are none already
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Returns:
    the launch configuration, or `null` if there was no existing launch configuration and `create` was false
  Throws:
    `CoreException`
  Since:
    2.0

### getLaunch

    ILaunch getLaunch()

  Returns the launch that was used to start the server, if available. If the server is not running, will return `null`.

  Returns:
    the launch used to start the currently running server, or `null` if the launch is unavailable or could not be found
  Since:
    3.0

### getStartTimeout

    int getStartTimeout()

  Returns the start timeout in seconds.

  Returns:
    the start timeout in seconds
  Since:
    3.0

### getStopTimeout

    int getStopTimeout()

  Returns the stop timeout in seconds.

  Returns:
    the stop timeout in seconds
  Since:
    3.0

### synchronousStart

    void synchronousStart(java.lang.String launchMode,
                          IProgressMonitor monitor)
                          throws CoreException

  Deprecated. use `#start(String, IServer.IOperationListener)` instead

  Starts this server in the given launch mode and waits until the server has finished starting.

  This convenience method uses `start(String, IProgressMonitor)` to start the server, and an internal thread and listener to detect when the server has finished starting.

  Parameters:
    `launchMode` - a mode in which a server can be launched, one of the mode constants defined by `org.eclipse.debug.core.ILaunchManager`
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Throws:
    `CoreException` - if an error occurs while trying to start the server

### synchronousStop

    void synchronousStop(boolean force)

  Deprecated. use `stop(boolean, IOperationListener)` instead

  Stops this server and waits until the server has completely stopped.

  This convenience method uses `stop(boolean)` to stop the server, and an internal thread and listener to detect when the server has complied.

  Parameters:
    `force` - `true` to kill the server, or `false` to stop normally

### synchronousRestart

    void synchronousRestart(java.lang.String launchMode,
                            IProgressMonitor monitor)
                            throws CoreException

  Deprecated. use `#restart(String, IServer.IOperationListener)` instead

  Synchronously restarts this server. This operation does nothing if this server cannot be stopped (`canRestart(String)` returns `false`.

  Parameters:
    `launchMode` - a mode in which a server can be launched, one of the mode constants defined by `org.eclipse.debug.core.ILaunchManager`
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Throws:
    `CoreException` - if there was an error