org.eclipse.wst.jsdt.core
Class JsGlobalScopeContainerInitializer

java.lang.Object
  extended by org.eclipse.wst.jsdt.core.JsGlobalScopeContainerInitializer
All Implemented Interfaces:
IJsGlobalScopeContainer, IJsGlobalScopeContainerInitializer
Direct Known Subclasses:
BasicBrowserLibraryJsGlobalScopeContainerInitializer, FireFoxLibInitializer, InternetExplorerLibInitializer

public abstract class JsGlobalScopeContainerInitializer
extends java.lang.Object
implements IJsGlobalScopeContainerInitializer, IJsGlobalScopeContainer

Abstract base implementation of all includepath container initializer. Includepath variable containers are used in conjunction with the "org.eclipse.wst.jsdt.core.JsGlobalScopeContainerInitializer" extension point.

Clients should subclass this class to implement a specific includepath container initializer. The subclass must have a public 0-argument constructor and a concrete implementation of initialize.

Multiple includepath containers can be registered, each of them declares the container ID they can handle, so as to narrow the set of containers they can resolve, in other words, a container initializer is guaranteed to only be activated to resolve containers which match the ID they registered onto.

In case multiple container initializers collide on the same container ID, the first registered one will be invoked.

See Also:
IIncludePathEntry, 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.

Field Summary
static int ATTRIBUTE_NOT_SUPPORTED
          Status code indicating that an attribute is not supported.
static int ATTRIBUTE_READ_ONLY
          Status code indicating that an attribute is not modifiable.
 
Fields inherited from interface org.eclipse.wst.jsdt.core.IJsGlobalScopeContainer
K_APPLICATION, K_DEFAULT_SYSTEM, K_SYSTEM
 
Constructor Summary
JsGlobalScopeContainerInitializer()
          Creates a new includepath container initializer.
 
Method Summary
 boolean allowAttachJsDoc()
           
 boolean canUpdateJsGlobalScopeContainer(IPath containerPath, IJavaScriptProject project)
          Returns true if this container initializer can be requested to perform updates on its own container values.
 java.lang.String[] containerSuperTypes()
          returns a String of all SuperTypes provided by this library.
 IStatus getAccessRulesStatus(IPath containerPath, IJavaScriptProject project)
          Returns the access rules attribute status according to this initializer.
 IStatus getAttributeStatus(IPath containerPath, IJavaScriptProject project, java.lang.String attributeKey)
          Returns the extra attribute status according to this initializer.
 IIncludePathEntry[] getClasspathEntries()
          Deprecated. Use getIncludepathEntries() instead
 java.lang.Object getComparisonID(IPath containerPath, IJavaScriptProject project)
          Returns an object which identifies a container for comparison purpose.
 java.lang.String getDescription()
          Answers a readable description of this container
 java.lang.String getDescription(IPath containerPath, IJavaScriptProject project)
          Returns a readable description for a container path.
 IJsGlobalScopeContainer getFailureContainer(IPath containerPath, IJavaScriptProject project)
          Returns a includepath container that is used after this initializer failed to bind a includepath container to a IJsGlobalScopeContainer for the given project.
 java.net.URI getHostPath(IPath path, IJavaScriptProject project)
           
 IIncludePathEntry[] getIncludepathEntries()
          Answers the set of includepath entries this container is mapping to.
 java.lang.String getInferenceID()
          Get the id of the inference provider for this library
 int getKind()
          Answers the kind of this container.
 IPath getPath()
          Answers the container path identifying this container.
 IStatus getSourceAttachmentStatus(IPath containerPath, IJavaScriptProject project)
          Returns the source attachment attribute status according to this initializer.
 void initialize(IPath containerPath, IJavaScriptProject project)
          Binds a includepath container to a IJsGlobalScopeContainer for a given project, or silently fails if unable to do so.
 void removeFromProject(IJavaScriptProject project)
           
 void requestJsGlobalScopeContainerUpdate(IPath containerPath, IJavaScriptProject project, IJsGlobalScopeContainer containerSuggestion)
          Request a registered container definition to be updated according to a container suggestion.
 java.lang.String[] resolvedLibraryImport(java.lang.String realImport)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.eclipse.wst.jsdt.core.IJsGlobalScopeContainerInitializer
getLibraryLocation
 

Field Detail

ATTRIBUTE_NOT_SUPPORTED

public static final int ATTRIBUTE_NOT_SUPPORTED
Status code indicating that an attribute is not supported.

See Also:
getAccessRulesStatus(IPath, IJavaScriptProject), getAttributeStatus(IPath, IJavaScriptProject, String), getSourceAttachmentStatus(IPath, IJavaScriptProject), Constant Field Values

ATTRIBUTE_READ_ONLY

public static final int ATTRIBUTE_READ_ONLY
Status code indicating that an attribute is not modifiable.

See Also:
getAccessRulesStatus(IPath, IJavaScriptProject), getAttributeStatus(IPath, IJavaScriptProject, String), getSourceAttachmentStatus(IPath, IJavaScriptProject), Constant Field Values
Constructor Detail

JsGlobalScopeContainerInitializer

public JsGlobalScopeContainerInitializer()
Creates a new includepath container initializer.

Method Detail

initialize

public void initialize(IPath containerPath,
                       IJavaScriptProject project)
                throws CoreException
Description copied from interface: IJsGlobalScopeContainerInitializer
Binds a includepath container to a IJsGlobalScopeContainer for a given project, or silently fails if unable to do so.

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.

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 JavaScriptCore#setJsGlobalScopeContainer.

A container initialization can be indirectly performed while attempting to resolve a project includepath using IJavaScriptProject#getResolvedClasspath(; or directly when using JavaScriptCore#getJsGlobalScopeContainer. During the initialization process, any attempt to further obtain the same container will simply return null so as to avoid an infinite regression of initializations.

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.

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.

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:

The effects of using other JavaScript model APIs are unspecified.

Specified by:
initialize in interface IJsGlobalScopeContainerInitializer
Parameters:
containerPath - a two-segment path (ID/hint) identifying the container that needs to be resolved
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 Also:
JavaScriptCore.getJsGlobalScopeContainer(IPath, IJavaScriptProject), JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], org.eclipse.core.runtime.IProgressMonitor), IJsGlobalScopeContainer

canUpdateJsGlobalScopeContainer

public boolean canUpdateJsGlobalScopeContainer(IPath containerPath,
                                               IJavaScriptProject project)
Description copied from interface: IJsGlobalScopeContainerInitializer
Returns true 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 JsGlobalScopeContainerInitializer#requestJsGlobalScopeContainerUpdate/

Specified by:
canUpdateJsGlobalScopeContainer in interface IJsGlobalScopeContainerInitializer
Parameters:
containerPath - the path of the container which requires to be updated
project - the project for which the container is to be updated
Returns:
returns true if the container can be updated

requestJsGlobalScopeContainerUpdate

public void requestJsGlobalScopeContainerUpdate(IPath containerPath,
                                                IJavaScriptProject project,
                                                IJsGlobalScopeContainer containerSuggestion)
                                         throws CoreException
Description copied from interface: IJsGlobalScopeContainerInitializer
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.

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 JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], IProgressMonitor). Until it does so, the update will not be reflected in the JavaScript Model.

In order to anticipate whether the container initializer allows to update its containers, the predicate JavaScriptCore#canUpdateJsGlobalScopeContainer should be used.

Specified by:
requestJsGlobalScopeContainerUpdate in interface IJsGlobalScopeContainerInitializer
Parameters:
containerPath - the path of the container which requires to be updated
project - the project for which the container is to be updated
containerSuggestion - a suggestion to update the corresponding container definition
Throws:
CoreException - when JavaScriptCore#setJsGlobalScopeContainer would throw any.
See Also:
JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], org.eclipse.core.runtime.IProgressMonitor), canUpdateJsGlobalScopeContainer(IPath, IJavaScriptProject)

getDescription

public java.lang.String getDescription(IPath containerPath,
                                       IJavaScriptProject project)
Description copied from interface: IJsGlobalScopeContainerInitializer
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 IJsGlobalScopeContainer.getDescription()).

Specified by:
getDescription in interface IJsGlobalScopeContainerInitializer
Parameters:
containerPath - the path of the container which requires a readable description
project - the project from which the container is referenced
Returns:
a string description of the container

getFailureContainer

public IJsGlobalScopeContainer getFailureContainer(IPath containerPath,
                                                   IJavaScriptProject project)
Description copied from interface: IJsGlobalScopeContainerInitializer
Returns a includepath container that is used after this initializer failed to bind a includepath container to a IJsGlobalScopeContainer for the given project. A non-null failure container indicates that there will be no more request to initialize the given container for the given project.

By default a non-null 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 null.

Specified by:
getFailureContainer in interface IJsGlobalScopeContainerInitializer
Parameters:
containerPath - the path of the container which failed to initialize
project - the project from which the container is referenced
Returns:
the default failure container, or null if wishing to run the initializer again

getComparisonID

public java.lang.Object getComparisonID(IPath containerPath,
                                        IJavaScriptProject project)
Description copied from interface: IJsGlobalScopeContainerInitializer
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.

Specified by:
getComparisonID in interface IJsGlobalScopeContainerInitializer
Parameters:
containerPath - the path of the container which is being checked
project - the project for which the container is to being checked
Returns:
returns an Object identifying the container for comparison

getHostPath

public java.net.URI getHostPath(IPath path,
                                IJavaScriptProject project)
Specified by:
getHostPath in interface IJsGlobalScopeContainerInitializer

allowAttachJsDoc

public boolean allowAttachJsDoc()
Specified by:
allowAttachJsDoc in interface IJsGlobalScopeContainerInitializer

containerSuperTypes

public java.lang.String[] containerSuperTypes()
Description copied from interface: IJsGlobalScopeContainerInitializer
returns a String of all SuperTypes provided by this library.

Specified by:
containerSuperTypes in interface IJsGlobalScopeContainerInitializer

resolvedLibraryImport

public java.lang.String[] resolvedLibraryImport(java.lang.String realImport)
Specified by:
resolvedLibraryImport in interface IJsGlobalScopeContainer

getClasspathEntries

public IIncludePathEntry[] getClasspathEntries()
Deprecated. Use getIncludepathEntries() instead

Description copied from interface: IJsGlobalScopeContainer
Answers the set of includepath entries this container is mapping to.

The set of entries associated with a includepath container may contain any of the following:

A includepath container can neither reference further includepath containers or includepath variables.

This method is called by the JavaScript model when it needs to resolve this includepath container entry into a list of library and project entries. The method is typically called exactly once for a given JavaScript project, and the resulting list of entries cached internally by the JavaScript model. This method must not be called by other clients.

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:

The effects of using other JavaScript model APIs are unspecified.

Specified by:
getClasspathEntries in interface IJsGlobalScopeContainer
Returns:
IIncludePathEntry[] - the includepath entries this container represents
See Also:
IIncludePathEntry

getIncludepathEntries

public IIncludePathEntry[] getIncludepathEntries()
Description copied from interface: IJsGlobalScopeContainer
Answers the set of includepath entries this container is mapping to.

The set of entries associated with a includepath container may contain any of the following:

A includepath container can neither reference further includepath containers or includepath variables.

This method is called by the JavaScript model when it needs to resolve this includepath container entry into a list of library and project entries. The method is typically called exactly once for a given JavaScript project, and the resulting list of entries cached internally by the JavaScript model. This method must not be called by other clients.

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:

The effects of using other JavaScript model APIs are unspecified.

Specified by:
getIncludepathEntries in interface IJsGlobalScopeContainer
Returns:
IIncludePathEntry[] - the includepath entries this container represents
See Also:
IIncludePathEntry

getDescription

public java.lang.String getDescription()
Description copied from interface: IJsGlobalScopeContainer
Answers a readable description of this container

Specified by:
getDescription in interface IJsGlobalScopeContainer
Returns:
String - a string description of the container

getKind

public int getKind()
Description copied from interface: IJsGlobalScopeContainer
Answers the kind of this container. Can be either: Typically, system containers should be placed first on a build path.

Specified by:
getKind in interface IJsGlobalScopeContainer
Returns:
the kind of this container

getPath

public IPath getPath()
Description copied from interface: IJsGlobalScopeContainer
Answers the container path identifying this container. A container path is formed by a first ID segment followed with extra segments, which can be used as additional hints for resolving to this container.

The container ID is also used to identify aJsGlobalScopeContainerInitializer registered on the extension point "org.eclipse.wst.jsdt.core.JsGlobalScopeContainerInitializer", which can be invoked if needing to resolve the container before it is explicitly set.

Specified by:
getPath in interface IJsGlobalScopeContainer
Returns:
IPath - the container path that is associated with this container

getAccessRulesStatus

public IStatus getAccessRulesStatus(IPath containerPath,
                                    IJavaScriptProject project)
Returns the access rules attribute status according to this initializer.

The returned status can have one of the following severities:

The status message can contain more information.

If the subclass does not override this method, then the default behavior is to return OK if and only if the includepath container can be updated (see canUpdateJsGlobalScopeContainer(IPath, IJavaScriptProject)).

Parameters:
containerPath - the path of the container which requires to be updated
project - the project for which the container is to be updated
Returns:
returns the access rules attribute status

getAttributeStatus

public IStatus getAttributeStatus(IPath containerPath,
                                  IJavaScriptProject project,
                                  java.lang.String attributeKey)
Returns the extra attribute status according to this initializer.

The returned status can have one of the following severities:

The status message can contain more information.

If the subclass does not override this method, then the default behavior is to return OK if and only if the includepath container can be updated (see canUpdateJsGlobalScopeContainer(IPath, IJavaScriptProject)).

Parameters:
containerPath - the path of the container which requires to be updated
project - the project for which the container is to be updated
attributeKey - the key of the extra attribute
Returns:
returns the extra attribute status
See Also:
IIncludePathAttribute

getSourceAttachmentStatus

public IStatus getSourceAttachmentStatus(IPath containerPath,
                                         IJavaScriptProject project)
Returns the source attachment attribute status according to this initializer.

The returned status can have one of the following severities:

The status message can contain more information.

If the subclass does not override this method, then the default behavior is to return OK if and only if the includepath container can be updated (see canUpdateJsGlobalScopeContainer(IPath, IJavaScriptProject)).

Parameters:
containerPath - the path of the container which requires to be updated
project - the project for which the container is to be updated
Returns:
returns the source attachment attribute status

getInferenceID

public java.lang.String getInferenceID()
Description copied from interface: IJsGlobalScopeContainerInitializer
Get the id of the inference provider for this library

Specified by:
getInferenceID in interface IJsGlobalScopeContainerInitializer
Returns:
inference provider id

removeFromProject

public void removeFromProject(IJavaScriptProject project)
Specified by:
removeFromProject in interface IJsGlobalScopeContainerInitializer