| /******************************************************************************* |
| * Copyright (c) 2005, 2008 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v2.0 |
| * which accompanies this distribution, and is available at |
| * https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| /** |
| * |
| */ |
| package org.eclipse.wst.jsdt.core; |
| |
| import java.net.URI; |
| |
| import org.eclipse.core.runtime.CoreException; |
| import org.eclipse.core.runtime.IPath; |
| import org.eclipse.wst.jsdt.core.compiler.libraries.LibraryLocation; |
| |
| /** |
| * |
| * Provisional API: This class/interface is part of an interim API that is still under development and expected to |
| * change significantly before reaching stability. It is being made available at this early stage to solicit feedback |
| * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken |
| * (repeatedly) as the API evolves. |
| */ |
| public interface IJsGlobalScopeContainerInitializer { |
| /** |
| * Binds a includepath container to a <code>IJsGlobalScopeContainer</code> for a given project, |
| * or silently fails if unable to do so. |
| * <p> |
| * A container is identified by a container path, which must be formed of two segments. |
| * The first segment is used as a unique identifier (which this initializer did register onto), and |
| * the second segment can be used as an additional hint when performing the resolution. |
| * <p> |
| * The initializer is invoked if a container path needs to be resolved for a given project, and no |
| * value for it was recorded so far. The implementation of the initializer would typically set the |
| * corresponding container using <code>JavaScriptCore#setJsGlobalScopeContainer</code>. |
| * <p> |
| * A container initialization can be indirectly performed while attempting to resolve a project |
| * includepath using <code>IJavaScriptProject#getResolvedClasspath(</code>; or directly when using |
| * <code>JavaScriptCore#getJsGlobalScopeContainer</code>. During the initialization process, any attempt |
| * to further obtain the same container will simply return <code>null</code> so as to avoid an |
| * infinite regression of initializations. |
| * <p> |
| * A container initialization may also occur indirectly when setting a project includepath, as the operation |
| * needs to resolve the includepath for validation purpose. While the operation is in progress, a referenced |
| * container initializer may be invoked. If the initializer further tries to access the referring project includepath, |
| * it will not see the new assigned includepath until the operation has completed. Note that once the JavaScript |
| * change notification occurs (at the end of the operation), the model has been updated, and the project |
| * includepath can be queried normally. |
| * <p> |
| * This method is called by the JavaScript model to give the party that defined |
| * this particular kind of includepath container the chance to install |
| * includepath container objects that will be used to convert includepath |
| * container entries into simpler includepath entries. The method is typically |
| * called exactly once for a given JavaScript project and includepath container |
| * entry. This method must not be called by other clients. |
| * <p> |
| * There are a wide variety of conditions under which this method may be |
| * invoked. To ensure that the implementation does not interfere with |
| * correct functioning of the JavaScript model, the implementation should use |
| * only the following JavaScript model APIs: |
| * <ul> |
| * <li>{@link JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], org.eclipse.core.runtime.IProgressMonitor)}</li> |
| * <li>{@link JavaScriptCore#getJsGlobalScopeContainer(IPath, IJavaScriptProject)}</li> |
| * <li>{@link JavaScriptCore#create(org.eclipse.core.resources.IWorkspaceRoot)}</li> |
| * <li>{@link JavaScriptCore#create(org.eclipse.core.resources.IProject)}</li> |
| * <li>{@link IJavaScriptModel#getJavaScriptProjects()}</li> |
| * <li>JavaScript element operations marked as "handle-only"</li> |
| * </ul> |
| * The effects of using other JavaScript model APIs are unspecified. |
| * </p> |
| * |
| * @param containerPath a two-segment path (ID/hint) identifying the container that needs |
| * to be resolved |
| * @param project the JavaScript project in which context the container is to be resolved. |
| * This allows generic containers to be bound with project specific values. |
| * @throws CoreException if an exception occurs during the initialization |
| * |
| * @see JavaScriptCore#getJsGlobalScopeContainer(IPath, IJavaScriptProject) |
| * @see JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], org.eclipse.core.runtime.IProgressMonitor) |
| * @see IJsGlobalScopeContainer |
| */ |
| public abstract void initialize(IPath containerPath, IJavaScriptProject project) throws CoreException; |
| |
| /** |
| * Returns <code>true</code> if this container initializer can be requested to perform updates |
| * on its own container values. If so, then an update request will be performed using |
| * <code>JsGlobalScopeContainerInitializer#requestJsGlobalScopeContainerUpdate</code>/ |
| * <p> |
| * @param containerPath the path of the container which requires to be updated |
| * @param project the project for which the container is to be updated |
| * @return returns <code>true</code> if the container can be updated |
| */ |
| public abstract boolean canUpdateJsGlobalScopeContainer(IPath containerPath, IJavaScriptProject project); |
| |
| /** |
| * Request a registered container definition to be updated according to a container suggestion. The container suggestion |
| * only acts as a place-holder to pass along the information to update the matching container definition(s) held by the |
| * container initializer. In particular, it is not expected to store the container suggestion as is, but rather adjust |
| * the actual container definition based on suggested changes. |
| * <p> |
| * IMPORTANT: In reaction to receiving an update request, a container initializer will update the corresponding |
| * container definition (after reconciling changes) at its earliest convenience, using |
| * <code>JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], IProgressMonitor)</code>. |
| * Until it does so, the update will not be reflected in the JavaScript Model. |
| * <p> |
| * In order to anticipate whether the container initializer allows to update its containers, the predicate |
| * <code>JavaScriptCore#canUpdateJsGlobalScopeContainer</code> should be used. |
| * <p> |
| * @param containerPath the path of the container which requires to be updated |
| * @param project the project for which the container is to be updated |
| * @param containerSuggestion a suggestion to update the corresponding container definition |
| * @throws CoreException when <code>JavaScriptCore#setJsGlobalScopeContainer</code> would throw any. |
| * @see JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], org.eclipse.core.runtime.IProgressMonitor) |
| * @see JsGlobalScopeContainerInitializer#canUpdateJsGlobalScopeContainer(IPath, IJavaScriptProject) |
| */ |
| public abstract void requestJsGlobalScopeContainerUpdate(IPath containerPath, IJavaScriptProject project, IJsGlobalScopeContainer containerSuggestion) |
| throws CoreException; |
| |
| /** |
| * Returns a readable description for a container path. A readable description for a container path can be |
| * used for improving the display of references to container, without actually needing to resolve them. |
| * A good implementation should answer a description consistent with the description of the associated |
| * target container (see <code>IJsGlobalScopeContainer.getDescription()</code>). |
| * |
| * @param containerPath the path of the container which requires a readable description |
| * @param project the project from which the container is referenced |
| * @return a string description of the container |
| */ |
| public abstract String getDescription(IPath containerPath, IJavaScriptProject project); |
| |
| /** |
| * Returns a includepath container that is used after this initializer failed to bind a includepath container |
| * to a <code>IJsGlobalScopeContainer</code> for the given project. A non-<code>null</code> |
| * failure container indicates that there will be no more request to initialize the given container |
| * for the given project. |
| * <p> |
| * By default a non-<code>null</code> failure container with no includepath entries is returned. |
| * Clients wishing to get a chance to run the initializer again should override this method |
| * and return <code>null</code>. |
| * </p> |
| * |
| * @param containerPath the path of the container which failed to initialize |
| * @param project the project from which the container is referenced |
| * @return the default failure container, or <code>null</code> if wishing to run the initializer again |
| */ |
| public abstract IJsGlobalScopeContainer getFailureContainer(final IPath containerPath, IJavaScriptProject project); |
| |
| /** |
| * Returns an object which identifies a container for comparison purpose. This allows |
| * to eliminate redundant containers when accumulating includepath entries (e.g. |
| * runtime includepath computation). When requesting a container comparison ID, one |
| * should ensure using its corresponding container initializer. Indeed, a random container |
| * initializer cannot be held responsible for determining comparison IDs for arbitrary |
| * containers. |
| * <p> |
| * @param containerPath the path of the container which is being checked |
| * @param project the project for which the container is to being checked |
| * @return returns an Object identifying the container for comparison |
| */ |
| public abstract Object getComparisonID(IPath containerPath, IJavaScriptProject project); |
| |
| public abstract URI getHostPath(IPath path, IJavaScriptProject project); |
| |
| LibraryLocation getLibraryLocation(); |
| /* |
| * Returns if this library allows attachment of external JsDoc |
| */ |
| boolean allowAttachJsDoc(); |
| /** |
| * returns a String of all SuperTypes provided by this library. |
| */ |
| String[] containerSuperTypes(); |
| |
| /** |
| * Get the id of the inference provider for this library |
| * @return inference provider id |
| */ |
| String getInferenceID(); |
| |
| void removeFromProject(IJavaScriptProject project); |
| } |
