org.eclipse.wst.jsdt.core

## Interface IJsGlobalScopeContainerInitializer

All Known Implementing Classes:
  BasicBrowserLibraryJsGlobalScopeContainerInitializer, FireFoxLibInitializer, InternetExplorerLibInitializer, JREContainerInitializer, JsGlobalScopeContainerInitializer

    public interface IJsGlobalScopeContainerInitializer

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.

### Method Summary

All Methods Instance Methods Abstract Methods
`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.
`java.lang.Object` `getComparisonID(IPath containerPath, IJavaScriptProject project)` Returns an object which identifies a container for comparison purpose.
`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)`
`java.lang.String` `getInferenceID()` Get the id of the inference provider for this library
`LibraryLocation` `getLibraryLocation()`
`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.

### Method Detail

#### initialize

    void initialize(IPath containerPath,
                    IJavaScriptProject project)
             throws CoreException

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:

- `JavaScriptCore#setJsGlobalScopeContainer(IPath, IJavaScriptProject[], IJsGlobalScopeContainer[], org.eclipse.core.runtime.IProgressMonitor)`
- `JavaScriptCore.getJsGlobalScopeContainer(IPath, IJavaScriptProject)`
- `JavaScriptCore#create(org.eclipse.core.resources.IWorkspaceRoot)`
- `JavaScriptCore#create(org.eclipse.core.resources.IProject)`
- `IJavaScriptModel.getJavaScriptProjects()`
- JavaScript element operations marked as "handle-only"

The effects of using other JavaScript model APIs are unspecified.

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

    boolean canUpdateJsGlobalScopeContainer(IPath containerPath,
                                            IJavaScriptProject project)

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`/

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

    void requestJsGlobalScopeContainerUpdate(IPath containerPath,
                                             IJavaScriptProject project,
                                             IJsGlobalScopeContainer containerSuggestion)
                                      throws CoreException

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.

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)`, `JsGlobalScopeContainerInitializer.canUpdateJsGlobalScopeContainer(IPath, IJavaScriptProject)`

#### getDescription

    java.lang.String getDescription(IPath containerPath,
                                    IJavaScriptProject project)

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

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

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

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

    java.lang.Object getComparisonID(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.

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

    java.net.URI getHostPath(IPath path,
                             IJavaScriptProject project)

#### getLibraryLocation

    LibraryLocation getLibraryLocation()

#### allowAttachJsDoc

    boolean allowAttachJsDoc()

#### containerSuperTypes

    java.lang.String[] containerSuperTypes()

returns a String of all SuperTypes provided by this library.

#### getInferenceID

    java.lang.String getInferenceID()

Get the id of the inference provider for this library

Returns:
  inference provider id

#### removeFromProject

    void removeFromProject(IJavaScriptProject project)