org.eclipse.wst.server.core
Interface IRuntime

All Known Subinterfaces:

IRuntimeWorkingCopy

public interface IRuntime

Represents a runtime instance. Every runtime is an instance of a particular, fixed runtime type.

Servers have a runtime. The server runtime corresponds to the installed code base for the server. The main role played by the server runtime is in identifying code libraries to compile or build against. In the case of local servers, the server runtime may play a secondary role of being used to launch the server for testing. Having the server runtimes identified as an entity separate from the server itself facilitates sharing server runtimes between several servers.

IRuntime implements IAdaptable to allow users to obtain a runtime-type-specific class. By casting the runtime extension to the type prescribed in the API documentation for that particular runtime type, the client can access runtime-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 runtime instances (ServerCore.getRuntimes()).

All runtimes have a unique id. Two runtimes (or more likely a runtime and it's working copy) with the same id are equal, and two runtimes with different ids are never equal.

Two runtimes are identical if and only if they have the same id.

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

See Also:

IRuntimeWorkingCopy

Method Summary

IRuntimeWorkingCopy	createWorkingCopy() Returns a runtime working copy for modifying this runtime instance.
void	delete() Deletes the persistent representation of this runtime.
java.lang.Object	getAdapter(java.lang.Class adapter) Returns an object which is an instance of the given class associated with this object.
java.lang.String	getId() Returns the id of this runtime instance.
IPath	getLocation() Returns the absolute path in the local file system to the root of the runtime, typically the installation directory.
java.lang.String	getName() Returns the displayable name for this runtime.
IRuntimeType	getRuntimeType() Returns the type of this runtime instance.
boolean	isReadOnly() Returns whether this runtime is marked read only.
boolean	isStub() Returns whether this runtime is a stub (used for compilation only) or a full runtime.
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.
IStatus	validate(IProgressMonitor monitor) Validates this runtime instance.

Method Detail

getName

public java.lang.String getName()

Returns the displayable name for this runtime.

Note that this name is appropriate for the current locale.

Returns:

a displayable name

getId

public java.lang.String getId()

Returns the id of this runtime instance. Each runtime (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.

For the id of the runtime type, use IRuntimeType.getId()

Returns:

the runtime id

delete

public void delete()
            throws CoreException

Deletes the persistent representation of this runtime.

Throws:

CoreException - if there was any error received while deleting the runtime or if this method is called on a working copy

isReadOnly

public boolean isReadOnly()

Returns whether this runtime is marked read only. When a runtime is read only, working copies can be created but they cannot be saved.

Returns:

true if this runtime is marked as read only, and false otherwise

isWorkingCopy

public boolean isWorkingCopy()

Returns true if this is a working copy.

Returns:

true if this runtime is a working copy (can be cast to IRuntimeWorkingCopy), and false otherwise

getAdapter

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

This method will not check the delegate class for adapting unless it is already loaded. No plugin loading will occur when calling this method.

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

public 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 if no such object can be found.

This method will force a load of the delegate class and check it 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

getRuntimeType

public IRuntimeType getRuntimeType()

Returns the type of this runtime instance.

Returns:

the runtime type

createWorkingCopy

public IRuntimeWorkingCopy createWorkingCopy()

Returns a runtime working copy for modifying this runtime instance. If this instance is already a working copy, it is returned. If this instance is not a working copy, a new runtime 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 runtime working copy is related to this runtime instance in the following ways:

 this.getWorkingCopy().getId() == this.getId()
 this.getWorkingCopy().getOriginal() == this
 

[issue: IRuntimeWorkingCopy extends IRuntime. Runtime.getWorkingCopy() create a new working copy; RuntimeWorkingCopy.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

getLocation

public IPath getLocation()

Returns the absolute path in the local file system to the root of the runtime, typically the installation directory.

Returns:

the location of this runtime, or null if none

isStub

public boolean isStub()

Returns whether this runtime is a stub (used for compilation only) or a full runtime.

Returns:

true if this runtime is a stub, and false otherwise

validate

public IStatus validate(IProgressMonitor monitor)

Validates this runtime instance. This method returns an error if the runtime is pointing to a null or invalid location (e.g. not pointing to the correct installation directory), or if the runtime-type-specific properties are missing or invalid.

This method is not on the working copy so that the runtime can be validated at any time.

Parameters:

monitor - a progress monitor, or null if progress reporting and cancellation are not desired

Returns:

a status object with code IStatus.OK if this runtime is valid, otherwise a status object indicating what is wrong with it