/*******************************************************************************
* Copyright (c) 2004, 2005 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - Initial API and implementation
*******************************************************************************/
package org.eclipse.wst.server.core;
import org.eclipse.core.runtime.*;
/**
* Represents a runtime instance. Every runtime is an instance of a
* particular, fixed runtime type.
* <p>
* 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.
* </p>
* <p>
* 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.
* </p>
* <p>
* The server framework maintains a global list of all known runtime instances
* ({@link ServerCore#getRuntimes()}).
* </p>
* <p>
* 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.
* </p>
* <p>
* Two runtimes are identical if and only if they have the same id.
* </p>
* <p>This interface is not intended to be implemented by clients.</p>
*
* @see IRuntimeWorkingCopy
* @since 1.0
*/
public interface IRuntime extends IAdaptable {
/**
* Returns the displayable name for this runtime.
* <p>
* Note that this name is appropriate for the current locale.
* </p>
*
* @return a displayable name
*/
public String getName();
/**
* 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.
* <p>
* For the id of the runtime type, use {@link IRuntimeType#getId()}
* </p>
*
* @return the runtime id
*/
public String getId();
/**
* 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
*/
public void delete() throws CoreException;
/**
* Returns whether this runtime is marked read only.
* When a runtime is read only, working copies can be created but
* they cannot be saved.
*
* @return <code>true</code> if this runtime is marked as read only,
* and <code>false</code> otherwise
*/
public boolean isReadOnly();
/**
* Returns true if this is a working copy.
*
* @return <code>true</code> if this runtime is a working copy
* (can be cast to IRuntimeWorkingCopy), and
* <code>false</code> otherwise
*/
public boolean isWorkingCopy();
/**
* Returns an object which is an instance of the given class
* associated with this object. Returns <code>null</code> if
* no such object can be found, or if the delegate is not
* loaded.
* <p>
* 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.
* </p>
*
* @param adapter the adapter class to look up
* @return a object castable to the given class,
* or <code>null</code> if this object does not
* have an adapter for the given class
* @see IAdaptable#getAdapter(Class)
* @see #loadAdapter(Class, IProgressMonitor)
*/
public Object getAdapter(Class adapter);
/**
* Returns an object which is an instance of the given class
* associated with this object. Returns <code>null</code> only if
* no such object can be found after loading and initializing
* delegates.
* <p>
* This method will force a load and initialization of all delegate
* classes and check them for adapting.
* </p>
*
* @param adapter the adapter class to look up
* @param monitor a progress monitor, or <code>null</code> if progress
* reporting and cancellation are not desired
* @return a object castable to the given class,
* or <code>null</code> if this object does not
* have an adapter for the given class
* @see #getAdapter(Class)
*/
public Object loadAdapter(Class adapter, IProgressMonitor monitor);
/**
* Returns the type of this runtime instance.
*
* @return the runtime type
*/
public IRuntimeType getRuntimeType();
/**
* 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.
* <p>
* The runtime working copy is related to this runtime instance
* in the following ways:
* <pre>
* this.getWorkingCopy().getId() == this.getId()
* this.getWorkingCopy().getOriginal() == this
* </pre>
* </p>
* <p>
* [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.
* </p>
*
* @return a new working copy
*/
public IRuntimeWorkingCopy createWorkingCopy();
/**
* Returns the absolute path in the local file system to the root of the runtime,
* typically the installation directory.
*
* @return the location of this runtime, or <code>null</code> if none
*/
public IPath getLocation();
/**
* Returns whether this runtime is a stub (used for compilation only)
* or a full runtime.
*
* @return <code>true</code> if this runtime is a stub, and
* <code>false</code> otherwise
*/
public boolean isStub();
/**
* 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.
* <p>
* This method is not on the working copy so that the runtime can be validated at
* any time.
* </p>
*
* @param monitor a progress monitor, or <code>null</code> if progress
* reporting and cancellation are not desired
* @return a status object with code <code>IStatus.OK</code> if this
* runtime is valid, otherwise a status object indicating what is
* wrong with it
*/
public IStatus validate(IProgressMonitor monitor);
}