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.
-
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 modules that are currently configured on
the 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. |
getName
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
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
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
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
boolean isWorkingCopy()
- Returns true if this is a working copy.
-
-
Returns:
-
true if this server is a working copy,
and false otherwise
getAdapter
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, or if the delegate is not
loaded.
This method will not check the delegate classes for adapting
unless they are already loaded. No plugin loading will occur
when calling this method. It is suitable for popup menus and
other UI artifacts where performance is a concern.
-
-
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(Class, IProgressMonitor)
loadAdapter
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 only if
no such object can be found after loading and initializing
delegates.
This method will force a load and initialization 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 -
See Also:
-
getAdapter(Class)
getHost
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
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
IServerType getServerType()
- Returns the type of this server.
-
-
Returns:
- the server type
-
See Also:
-
IServerType
getServerConfiguration
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
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
IModule[] getModules()
- Returns an array of modules that are currently configured on
the server. When the server is published, these are the modules
that will be configured on the server. This method may not return
the list of modules that are currently on the server if a module
has been added or removed since the last publish.
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
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
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
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 server supports running a module
directly, the returned array should contain the module.
If the module type is not supported, this method will return null or
an empty array. 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 hierarchy) 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
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
