Eclipse Web Tools Guide (Galileo)

Overview

Package

Class

Use

Tree

Serialized

Deprecated

Index

Help

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.wst.server.core
Interface IServer

All Superinterfaces:: IServerAttributes

public interface IServer
extends IServerAttributes
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)

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

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.

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

Overview

Package

Class

Use

Tree

Serialized

Deprecated

Index

Help

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.wst.server.core Interface IServer

STATE_UNKNOWN

STATE_STARTING

STATE_STARTED

STATE_STOPPING

STATE_STOPPED

PUBLISH_STATE_UNKNOWN

PUBLISH_STATE_NONE

PUBLISH_STATE_INCREMENTAL

PUBLISH_STATE_FULL

PUBLISH_INCREMENTAL

PUBLISH_FULL

PUBLISH_AUTO

PUBLISH_CLEAN

getServerState

getMode

getServerPublishState

addServerListener

addServerListener

removeServerListener

addPublishListener

removePublishListener

canPublish

shouldPublish

publish

publish

canStart

start

canRestart

shouldRestart

getServerRestartState

restart

canStop

stop

stop

getModuleState

getModulePublishState

getModuleRestartState

canControlModule

startModule

stopModule

restartModule

getLaunchConfiguration

getLaunch

getStartTimeout

getStopTimeout

synchronousStart

synchronousStop

synchronousRestart

org.eclipse.wst.server.core
Interface IServer