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.

Caveat: The server core API is still in an early form, and is likely to change significantly before the initial release.

Since:

1.0

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	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	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	canRestartModule(IModule[] module, IProgressMonitor monitor) Returns whether the given module can be restarted.
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.
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.
IStatus	publish(int kind, IProgressMonitor monitor) Publish to the server using the progress monitor.
void	removeServerListener(IServerListener listener) Removes the given server state listener from this server.
void	restart(java.lang.String launchMode) Asynchronously restarts this server.
void	restartModule(IModule[] module, IProgressMonitor monitor) Asynchronously restarts the given module on the server.
ILaunch	start(java.lang.String launchMode, IProgressMonitor monitor) Asynchronously starts this server in the given launch mode.
void	stop(boolean force) Asynchronously stops this server.
void	synchronousRestart(java.lang.String launchMode, IProgressMonitor monitor) Synchronously restarts this server.
void	synchronousRestartModule(IModule[] module, IProgressMonitor monitor) Restarts the given module and waits until it has finished restarting.
ILaunch	synchronousStart(java.lang.String launchMode, IProgressMonitor monitor) Starts this server in the given launch mode and waits until the server has finished starting.
void	synchronousStop(boolean force) Stops this server and waits until the server has completely stopped.

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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public int getServerPublishState()

Returns the server's sync state.

Returns:

one of the PUBLISH_XXX state flags

getModulePublishState

public int getModulePublishState(IModule[] module)

Returns the module's sync state.

Parameters:

module - the module

Returns:

one of the PUBLISH_XXX state flags

addServerListener

public 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

public 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

public 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)

canPublish

public 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

publish

public 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.

Parameters:

kind - the kind of publish being requested. Valid values are

• PUBLSIH_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

canStart

public 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

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

Asynchronously starts this server in the given launch mode. Returns the debug launch object that can be used in a debug session.

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

[issue: There is no way to communicate failure to the client for the async portion of this operation. Given that this operation can go awry, there probably should be a mechanism that allows failing asynch operations to be diagnosed.]

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

Returns:

a debug launch object

Throws:

CoreException - if an error occurs while trying to start the server

synchronousStart

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

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

Returns:

the launch

Throws:

CoreException - if an error occurs while trying to start the server

canRestart

public 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

getServerRestartState

public 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

public void restart(java.lang.String launchMode)

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.

[issue: There is no way to communicate failure to the client. Given that this operation can go awry, there probably should be a mechanism that allows failing asynch operations to be diagnosed.]

Parameters:

launchMode - a mode in which a server can be launched, one of the mode constants defined by org.eclipse.debug.core.ILaunchManager

synchronousRestart

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

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

[issue: There is no way to communicate failure to the client. Given that this operation can go awry, there probably should be a mechanism that allows failing asynch operations to be diagnosed.]

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

canStop

public 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

public 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.

[issue: There is no way to communicate failure to the client. Given that this operation can go awry, there probably should be a mechanism that allows failing asynch operations to be diagnosed.]

Parameters:

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

synchronousStop

public void synchronousStop(boolean force)

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

canRestartModule

public IStatus canRestartModule(IModule[] module,
                                IProgressMonitor monitor)

Returns whether the given module can be restarted.

[issue: It's unclear whether this operations is guaranteed to be fast or whether it could involve communication with any actual server. If it is not fast, the method should take a progress monitor.]

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

getModuleRestartState

public 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

restartModule

public void restartModule(IModule[] module,
                          IProgressMonitor monitor)
                   throws CoreException

Asynchronously restarts the given module on the server. See the specification of synchronousRestartModule(IModule[], IProgressMonitor) for further details.

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: Since this method is ascynchronous, is there any need for the progress monitor?]

[issue: Since this method is ascynchronous, how can it return a meaningful IStatus? And IServer.synchronousModuleRestart throws CoreException if anything goes wrong.]

[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

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if an error occurs while trying to restart the module

synchronousRestartModule

public void synchronousRestartModule(IModule[] module,
                                     IProgressMonitor monitor)
                              throws CoreException

Restarts the given module and waits until it has finished restarting. If the module does not exist on the server, an exception will be thrown.

This method may not be used to initially start a module.

Parameters:

module - the module to be restarted

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Throws:

CoreException - if an error occurs while trying to restart the module

getModuleState

public 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