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

Method Detail

### 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