## org.eclipse.wst.server.core
Interface IServerWorkingCopy

All Superinterfaces:
  IServerAttributes

    public interface IServerWorkingCopy

extends IServerAttributes

A working copy server object used for formulating changes to a server instance (`IServer`). Changes made on a working copy do not occur (and are not persisted) until a save() is performed.

If the client of this working copy calls loadAdapter(), a new instance of the delegate (ServerDelegate) will be created to help this working copy. This delegate instance will be used as long as this working copy exists.

This interface is not intended to be implemented by clients.

Since:
  1.0

Field Summary
`static int` `SAVE_CONFLICT` Status code (value 1) returned from the save() method when the save failed with force set to `false` because the runtime has been modified and saved since this working copy was created.

Method Summary
`void` `addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Adds a property change listener to this server.
`IServer` `getOriginal()` Returns the server instance that this working copy is associated with.
`boolean` `isDirty()` Returns whether this working copy has unsaved changes.
`void` `modifyModules(IModule[] add, IModule[] remove, IProgressMonitor monitor)` Modifies the list of modules associated with the server.
`void` `removePropertyChangeListener(java.beans.PropertyChangeListener listener)` Removes a property change listener from this server.
`IServer` `save(boolean force, IProgressMonitor monitor)` Commits the changes made in this working copy.
`IServer` `saveAll(boolean force, IProgressMonitor monitor)` Commits the changes made in this server working copy after first committing any associated server configuration or server runtime working copies.
`void` `setHost(java.lang.String host)` Changes the host for the server.
`void` `setName(java.lang.String name)` Sets the displayable name for this server.
`void` `setReadOnly(boolean readOnly)` Sets or unsets whether this server is marked as read only.
`void` `setRuntime(IRuntime runtime)` Sets the runtime associated with this server working copy.
`void` `setServerConfiguration(IFolder configuration)` Sets the server configuration associated with this server working copy.

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

### SAVE_CONFLICT

    static final int SAVE_CONFLICT

  Status code (value 1) returned from the save() method when the save failed with force set to `false` because the runtime has been modified and saved since this working copy was created.

  See Also:
    `save(boolean, IProgressMonitor)`, Constant Field Values

Method Detail

### setName

    void setName(java.lang.String name)

  Sets the displayable name for this server.

  The name should be appropriate for the current locale.

  Parameters:
    `name` - a displayable name
  See Also:
    `IServerAttributes.getName()`

### setReadOnly

    void setReadOnly(boolean readOnly)

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

  Parameters:
    `readOnly` - `true` to set this server to be marked read only, and `false` to unset

### isDirty

    boolean isDirty()

  Returns whether this working copy has unsaved changes.

  Returns:
    `true` if this working copy has unsaved changes, and `false` otherwise

### addPropertyChangeListener

    void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

  Adds a property change listener to this server.

  Once registered, a listener starts receiving notification of property 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` - a property change listener
  See Also:
    `removePropertyChangeListener(PropertyChangeListener)`

### removePropertyChangeListener

    void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

  Removes a property change listener from this server. Has no effect if the listener is not registered.

  Parameters:
    `listener` - a property change listener
  See Also:
    `addPropertyChangeListener(PropertyChangeListener)`

### setServerConfiguration

    void setServerConfiguration(IFolder configuration)

  Sets the server configuration associated with this server working copy.

  Note: The server configuration of a server working copy may or may not be a working copy.

  [issue: According to serverType extension point, configurationTypeId is an optional attribute. What happens if the server configuration passed is null but the server must have a server configuration? What happens of the server configuration has the wrong type? Do the errors get detected and reported now, or upon save()?]

  Parameters:
    `configuration` - the server configuration, or `null` if none

### getOriginal

    IServer getOriginal()

  Returns the server instance that this working copy is associated with.

  For a server working copy created by a call to `IServerAttributes.createWorkingCopy()`, `this.getOriginal()` returns the original server object. For a server working copy just created by a call to `IServerType#createServer(String, org.eclipse.core.resources.IFile, IProgressMonitor)`, `this.getOriginal()` returns `null`.

  Returns:
    the associated server instance, or `null` if none

### save

    IServer save(boolean force,
                 IProgressMonitor monitor)
                 throws CoreException

  Commits the changes made in this working copy. If there is no extant server instance with a matching id and server type, this will create a server instance with attributes taken from this working copy. If there an existing server instance with a matching id and server type, this will change the server instance accordingly.

  If there an existing server instance with a matching id and server type, this will change the server instance accordingly. The returned server will be the same server this is returned from getOriginal(), after the changes have been applied. Otherwise, this method will return a newly created server.

  Servers can be saved even when they have invalid properties. It is the clients responsibility to validate or check the properties before saving.

  This method does not apply changes to the server. A publish() must be completed to push out after the save to push out any changes to the server.

  [issue: Since it does not make sense to commit a server working copy without first committing any associated runtime and server config working copies, the semantics of saveAll should be part and parcel of the normal save, and the saveAll method eliminated.]

  Parameters:
    `force` - `true` to force the save, or `false` otherwise
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Returns:
    a new server instance
  Throws:
    `CoreException` - if there is an error saving the server
  See Also:
    `SAVE_CONFLICT`

### saveAll

    IServer saveAll(boolean force,
                    IProgressMonitor monitor)
                    throws CoreException

  Commits the changes made in this server working copy after first committing any associated server configuration or server runtime working copies.

  This convenience method is equivalent to:

       IRuntime rt = this.getRuntime();
       if (rt != null && rt.isWorkingCopy()) {
          ((IRuntimeWorkingCopy) rt).save(monitor);
       }
       IServerConfiguration cf = this.getServerConfiguration();
       if (cf != null && cf.isWorkingCopy()) {
          ((IServerConfigurationWorkingCopy) cf).save(monitor);
       }
       return save(monitor);

  [issue: Since it does not make sense to commit a server working copy without first committing any associated runtime and server config working copies, the semantics of this operation should be part and parcel of the normal save, and the saveAll method eliminated.]

  Parameters:
    `force` - `true` to force the save, or `false` otherwise
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Returns:
    a new server instance
  Throws:
    `CoreException` - if there is an error saving the server, runtime, or server configuration
  See Also:
    `SAVE_CONFLICT`

### setRuntime

    void setRuntime(IRuntime runtime)

  Sets the runtime associated with this server working copy.

  Note: The runtime of a server working copy may or may not be a working copy.

  [issue: According to serverType extension point, runtimeTypeId is a mandatory attribute. But IServer.getRuntime() is allowed to return null, suggesting that it is optional for instances. What happens if the runtime passed is null but the server must have a runtime? What happens if the runtime has the wrong type? Do the errors get detected and reported now, or upon save()?]

  Parameters:
    `runtime` - the runtime, or `null` if none

### setHost

    void setHost(java.lang.String host)

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

  [issue: This is a questionable operation if there is a running server associated with the original. When a host name change is committed, the server instance loses contact with the running server because of the host name change.]

  Parameters:
    `host` - a host string conforming to RFC 2732
  See Also:
    `IServerAttributes.getHost()`, `URL.getHost()`

### modifyModules

    void modifyModules(IModule[] add,
                       IModule[] remove,
                       IProgressMonitor monitor)
                       throws CoreException

  Modifies the list of modules associated with the server. The modules included in the `add` list must exist in the workspace and must not already be associated with the server. The modules included in the `remove` list must be associated with the server, but may or may not exist in the workspace. Entries in the add or remove lists may not be null.

  This method will not communicate with the server. After saving, publish() can be used to sync up with the server.

  This method is guaranteed to fail with the same status exception if the result of canModifyModules() is an error status.

  [issue: How to formulate what it means to say "the module must exist in the workspace"?]

  [issue: The spec should be more lax. Attempting to add a module that's already include should be quietly ignore; ditto removing a module that's not on this list. This simplifies the handling of various other wacko cases such as duplication within and between the add and remove lists.]

  [issue: What error checking should be performed by this operation, and what needs to be performed by save() if the client tries to commit these hypothetisized changes?]

  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
  Throws:
    `CoreException` - if the changes are not allowed or could not be processed
  See Also:
    `IServerAttributes.canModifyModules(IModule[], IModule[], IProgressMonitor)`