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

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

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

public 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

public 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

public 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

public boolean isDirty()

Returns whether this working copy has unsaved changes.

Returns:

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

addPropertyChangeListener

public 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

public 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

public 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

public 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

public 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: 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:

CoreException - [missing]

See Also:

SAVE_CONFLICT

saveAll

public 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 - [missing]

See Also:

SAVE_CONFLICT

setRuntime

public 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

public 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

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

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

[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: The spec had also said: "...canModifyModules() should have returned true. The configuration must assume any default settings and add the module without any UI."]

[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 - [missing]