org.eclipse.wst.server.core
Interface IServerWorkingCopy

All Superinterfaces:
org.eclipse.core.runtime.IAdaptable, IServerAttributes

public interface IServerWorkingCopy
extends IServerAttributes

A working copy server object used for formulating changes to a server instance (IServer).

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, org.eclipse.core.runtime.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, org.eclipse.core.runtime.IProgressMonitor monitor)
          Commits the changes made in this working copy.
 IServer saveAll(boolean force, org.eclipse.core.runtime.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(org.eclipse.core.resources.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(org.eclipse.core.resources.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,
             org.eclipse.core.runtime.IProgressMonitor monitor)
             throws org.eclipse.core.runtime.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: What is lifecycle for ServerWorkingCopyDelegate associated with this working copy?]

[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:
org.eclipse.core.runtime.CoreException - if there is an error saving the server
See Also:
SAVE_CONFLICT

saveAll

IServer saveAll(boolean force,
                org.eclipse.core.runtime.IProgressMonitor monitor)
                throws org.eclipse.core.runtime.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:
org.eclipse.core.runtime.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,
                   org.eclipse.core.runtime.IProgressMonitor monitor)
                   throws org.eclipse.core.runtime.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:
org.eclipse.core.runtime.CoreException - if the changes are not allowed or could not be processed
See Also:
IServerAttributes.canModifyModules(IModule[], IModule[], IProgressMonitor)