org.eclipse.wst.server.core
Interface IServerAttributes

All Known Subinterfaces:

IServer, IServerWorkingCopy

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

IServerAttributes implements IAdaptable to allow users to obtain a server-type-specific class. By casting the runtime extension to the type prescribed in the API documentation for that particular server type, the client can access server-type-specific properties and methods. getAdapter() may involve plugin loading, and should not be called from popup menus, etc.

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

Method Summary

IStatus	canModifyModules(IModule[] add, IModule[] remove, IProgressMonitor monitor) Returns whether the specified module modifications could be made to this server at this time.
IServerWorkingCopy	createWorkingCopy() Returns a server working copy for modifying this server instance.
void	delete() Deletes the persistent representation of this server.
java.lang.Object	getAdapter(java.lang.Class adapter) Returns an object which is an instance of the given class associated with this object.
IModule[]	getChildModules(IModule[] module, IProgressMonitor monitor) Returns the child module(s) of this module.
java.lang.String	getHost() Returns the host for the server.
java.lang.String	getId() Returns the id of this server.
IModule[]	getModules() Returns an array of user modules that are currently being published to this server.
java.lang.String	getName() Returns the displayable name for this server.
IModule[]	getRootModules(IModule module, IProgressMonitor monitor) Returns the parent module(s) of this module.
IRuntime	getRuntime() Returns the runtime associated with this server.
IFolder	getServerConfiguration() Returns the server configuration associated with this server.
ServerPort[]	getServerPorts(IProgressMonitor monitor) Returns an array of ServerPorts that this server has.
IServerType	getServerType() Returns the type of this server.
boolean	isReadOnly() Returns whether this server is marked read only.
boolean	isWorkingCopy() Returns true if this is a working copy.
java.lang.Object	loadAdapter(java.lang.Class adapter, IProgressMonitor monitor) Returns an object which is an instance of the given class associated with this object.

Method Detail

getName

public java.lang.String getName()

Returns the displayable name for this server.

Note that this name is appropriate for the current locale.

Returns:

a displayable name

getId

public java.lang.String getId()

Returns the id of this server. Each server (of a given type) has a distinct id, fixed for its lifetime. Ids are intended to be used internally as keys; they are not intended to be shown to end users.

Returns:

the server id

delete

public void delete()
            throws CoreException

Deletes the persistent representation of this server.

Throws:

CoreException - if there was any error received while deleting the server or if this method is called on a working copy

isReadOnly

public boolean isReadOnly()

Returns whether this server is marked read only. When a server is read only, working copies can be created but they cannot be saved.

Returns:

true if this server is marked as read only, and false otherwise

isWorkingCopy

public boolean isWorkingCopy()

Returns true if this is a working copy.

Returns:

true if this server is a working copy, and false otherwise

getAdapter

public java.lang.Object getAdapter(java.lang.Class adapter)

Returns an object which is an instance of the given class associated with this object. Returns null if no such object can be found.

This method will not check the delegate classes for adapting unless they are already loaded. No plugin loading will occur when calling this method.

Parameters:

adapter - the adapter class to look up

Returns:

a object castable to the given class, or null if this object does not have an adapter for the given class

See Also:

IAdaptable#getAdapter(Class)

loadAdapter

public java.lang.Object loadAdapter(java.lang.Class adapter,
                                    IProgressMonitor monitor)

Returns an object which is an instance of the given class associated with this object. Returns null if no such object can be found.

This method will force a load of all delegate classes and check them for adapting.

Parameters:

adapter - the adapter class to look up

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

Returns:

a object castable to the given class, or null if this object does not have an adapter for the given class

getHost

public java.lang.String getHost()

Returns the host for the server. The format of the host can be either a qualified or unqualified hostname, or an IP address and must conform to RFC 2732.

Returns:

a host string conforming to RFC 2732

See Also:

URL.getHost()

getRuntime

public IRuntime getRuntime()

Returns the runtime associated with this server.

Note: The runtime of a server working copy may or may not be a working copy. For a server instance that is not a working copy, the runtime instance is not a working copy either.

[issue: According to serverType extension point, runtimeTypeId is a mandatory attribute. It seems odd then to have server runtime instance being an optional property of server instance. What does it mean for a server to not have a runtime?]

Returns:

the runtime, or null if none

getServerType

public IServerType getServerType()

Returns the type of this server.

Returns:

the server type

See Also:

IServerType

getServerConfiguration

public IFolder getServerConfiguration()

Returns the server configuration associated with this server.

Note: The server configuration of a server working copy may or may not be a working copy. For a server instance that is not a working copy, the server configuration instance is not a working copy either.

[issue: According to serverType extension point, configurationTypeId is an optional attribute. If a server type has no server configuration type, then it seems reasonable to expect this method to return null for all instances of that server type. But what about a server type that explicitly specifies a server configuration type. Does that mean that all server instances of that server type must have a server configuration instance of that server configuration type, and that this method never returns null in those cases?]

Returns:

the server configuration, or null if none

createWorkingCopy

public IServerWorkingCopy createWorkingCopy()

Returns a server working copy for modifying this server instance. If this instance is already a working copy, it is returned. If this instance is not a working copy, a new server working copy is created with the same id and attributes. Clients are responsible for saving or releasing the working copy when they are done with it.

The server working copy is related to this server instance in the following ways:

 this.getWorkingCopy().getId() == this.getId()
 this.getWorkingCopy().getFile() == this.getFile()
 this.getWorkingCopy().getOriginal() == this
 this.getWorkingCopy().getRuntime() == this.getRuntime()
 this.getWorkingCopy().getServerConfiguration() == this.getServerConfiguration()
 

[issue: IServerWorkingCopy extends IServer. Server.getWorkingCopy() create a new working copy; ServerWorkingCopy.getWorkingCopy() returns this. This may be convenient in code that is ignorant of whether they are dealing with a working copy or not. However, it is hard for clients to manage working copies with this design.]

Returns:

a new working copy

getModules

public IModule[] getModules()

Returns an array of user modules that are currently being published to this server.

This method returns the root modules, which are not parented within another modules. Each of these may contain child modules, which are also deployed to this server.

Returns:

a possibly-empty array of modules

canModifyModules

public IStatus canModifyModules(IModule[] add,
                                IModule[] remove,
                                IProgressMonitor monitor)

Returns whether the specified module modifications could be made to this server at this time.

This method may decide based on the type of module or refuse simply due to reaching a maximum number of modules or other criteria.

[issue: This seems odd to have a pre-flight method. I should expect that the client can propose making any set of module changes they desire (via a server working copy). If the server doesn't like it, the operation should fail.]

Parameters:

add - a possibly-empty list of modules to add

remove - a possibly-empty list of modules to remove

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

Returns:

true if the proposed modifications look feasible, and false otherwise

getChildModules

public IModule[] getChildModules(IModule[] module,
                                 IProgressMonitor monitor)

Returns the child module(s) of this module. If this module contains other modules, it should list those modules. If not, it should return an empty list.

This method should only return the direct children. To obtain the full module tree, this method may be recursively called on the children.

Parameters:

module - a module

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

Returns:

an array of direct module children

getRootModules

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

Returns the parent module(s) of this module. When determining if a given project can run on a server, this method will be used to find the actual module(s) that may be run on the server. For instance, a Web module may return a list of EAR modules that it is contained in if the server only supports configuring EAR modules.

If the module type is not supported, this method will return null. If the type is normally supported but there is a configuration problem or missing parent, etc., this method will fire a CoreException that may then be presented to the user.

If it does return valid parent(s), this method will always return the topmost parent module(s), even if there are a few levels (a heirarchy) of modules.

Parameters:

module - a module

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

Returns:

an array of possible root modules

Throws:

CoreException - if there is a problem

getServerPorts

public ServerPort[] getServerPorts(IProgressMonitor monitor)

Returns an array of ServerPorts that this server has.

Parameters:

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

Returns:

a possibly empty array of servers ports