org.eclipse.wst.jsdt.core

## Interface IJavaScriptElement

All Superinterfaces:
  ILookupScope

All Known Subinterfaces:
  IClassFile, IExportContainer, IExportDeclaration, IField, IFunction, IImportContainer, IImportDeclaration, IInitializer, IJavaScriptModel, IJavaScriptProject, IJavaScriptUnit, ILocalVariable, IMember, IPackageFragment, IPackageFragmentRoot, IType, ITypeRoot

    public interface IJavaScriptElement
    extends ILookupScope

Common protocol for all elements provided by the JavaScript model. JavaScript model elements are exposed to clients as handles to the actual underlying element. The JavaScript model may hand out any number of handles for each element. Handles that refer to the same element are guaranteed to be equal, but not necessarily identical.

Methods annotated as "handle-only" do not require underlying elements to exist. Methods that require underlying elements to exist throw a `JavaScriptModelException` when an underlying element is missing. `JavaScriptModelException.isDoesNotExist` can be used to recognize this common special case.

This interface is not intended to be implemented by clients.

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

Fields
`static int` `CLASS_FILE` Constant representing a non-editable javaScript file.
`static int` `EXPORT_CONTAINER` Constant representing all export declarations within a compilation unit.
`static int` `EXPORT_DECLARATION` Constant representing an export declaration within a compilation unit.
`static int` `FIELD` Constant representing a field or a var with file scope.
`static int` `IMPORT_CONTAINER` Constant representing all import declarations within a compilation unit.
`static int` `IMPORT_DECLARATION` Constant representing an import declaration within a compilation unit.
`static int` `INITIALIZER` Constant representing a stand-alone instance or class initializer.
`static int` `JAVASCRIPT_MODEL` Constant representing a JavaScript model (workspace level object).
`static int` `JAVASCRIPT_PROJECT` Constant representing a JavaScript project.
`static int` `JAVASCRIPT_UNIT` Constant representing a JavaScript file.
`static int` `LOCAL_VARIABLE` Constant representing a local variable declaration.
`static int` `METHOD` Constant representing a function, method or constructor.
`static int` `PACKAGE_FRAGMENT` Constant representing a source folder (package fragment).
`static int` `PACKAGE_FRAGMENT_ROOT` Constant representing a root source folder (package fragment root).
`static int` `TYPE` Constant representing a type (a class or interface).

### Method Summary

All Methods Instance Methods Abstract Methods
`boolean` `exists()` Returns whether this JavaScript element exists in the model.
`IJavaScriptElement` `getAncestor(int ancestorType)` Returns the first ancestor of this JavaScript element that has the given type.
`java.lang.String` `getAttachedJavadoc(IProgressMonitor monitor)` Returns the Jsdoc as an html source if this element has an attached jsdoc, null otherwise.
`LibrarySuperType` `getCommonSuperType()` Returns the Super type this file is considered to be a member of.
`IResource` `getCorrespondingResource()` Returns the resource that corresponds directly to this element, or `null` if there is no resource that corresponds to this element.
`java.lang.String` `getDisplayName()` Returns a readable (non mangled) name.
`java.lang.String` `getElementName()` Returns the name of this element.
`int` `getElementType()` Returns this element's kind encoded as an integer.
`java.lang.String` `getHandleIdentifier()` Returns a string representation of this element handle.
`java.net.URI` `getHostPath()` If a resource is virtual, then return a real host path for the element.
`IJavaScriptModel` `getJavaScriptModel()` Returns the JavaScript model.
`IJavaScriptProject` `getJavaScriptProject()` Returns the JavaScript project this element is contained in, or `null` if this element is not contained in any JavaScript project (for instance, the `IJavaScriptModel` is not contained in any JavaScript project).
`IOpenable` `getOpenable()` Returns the first openable parent.
`IJavaScriptElement` `getParent()` Returns the element directly containing this element, or `null` if this element has no parent.
`IPath` `getPath()` Returns the path to the innermost resource enclosing this element.
`IJavaScriptElement` `getPrimaryElement()` Returns the primary element (whose compilation unit is the primary compilation unit) this working copy element was created from, or this element if it is a descendant of a primary javaScript unit or if it is not a descendant of a working copy (e.g. it is a binary member).
`IResource` `getResource()` Returns the innermost resource enclosing this element.
`ISchedulingRule` `getSchedulingRule()` Returns the scheduling rule associated with this JavaScript element.
`IResource` `getUnderlyingResource()` Returns the smallest underlying resource that contains this element, or `null` if this element is not contained in a resource.
`boolean` `isReadOnly()` Returns whether this JavaScript element is read-only.
`boolean` `isStructureKnown()` Returns whether the structure of this element is known.
`boolean` `isVirtual()` Returns if this is a virtual element (ie actually exists in the model or filesystem).

### Methods inherited from interface org.eclipse.wst.jsdt.core.ILookupScope

`newNameLookup, newNameLookup, newSearchableNameEnvironment, newSearchableNameEnvironment`

### Field Detail

#### JAVASCRIPT_MODEL

    static final int JAVASCRIPT_MODEL

Constant representing a JavaScript model (workspace level object). A JavaScript element with this type can be safely cast to `IJavaScriptModel`.

See Also:
  Constant Field Values

#### JAVASCRIPT_PROJECT

    static final int JAVASCRIPT_PROJECT

Constant representing a JavaScript project. A JavaScript element with this type can be safely cast to `IJavaScriptProject`.

See Also:
  Constant Field Values

#### PACKAGE_FRAGMENT_ROOT

    static final int PACKAGE_FRAGMENT_ROOT

Constant representing a root source folder (package fragment root). A JavaScript element with this type can be safely cast to `IPackageFragmentRoot`.

See Also:
  Constant Field Values

#### PACKAGE_FRAGMENT

    static final int PACKAGE_FRAGMENT

Constant representing a source folder (package fragment). A JavaScript element with this type can be safely cast to `IPackageFragment`.

See Also:
  Constant Field Values

#### JAVASCRIPT_UNIT

    static final int JAVASCRIPT_UNIT

Constant representing a JavaScript file. A JavaScript element with this type can be safely cast to `IJavaScriptUnit`.

See Also:
  Constant Field Values

#### CLASS_FILE

    static final int CLASS_FILE

Constant representing a non-editable javaScript file. A JavaScript element with this type can be safely cast to `IClassFile`.

See Also:
  Constant Field Values

#### TYPE

    static final int TYPE

Constant representing a type (a class or interface). A JavaScript element with this type can be safely cast to `IType`.

See Also:
  Constant Field Values

#### FIELD

    static final int FIELD

Constant representing a field or a var with file scope. A JavaScript element with this type can be safely cast to `IField`.

See Also:
  Constant Field Values

#### METHOD

    static final int METHOD

Constant representing a function, method or constructor. A JavaScript element with this type can be safely cast to `IFunction`.

See Also:
  Constant Field Values

#### INITIALIZER

    static final int INITIALIZER

Constant representing a stand-alone instance or class initializer. A JavaScript element with this type can be safely cast to `IInitializer`.

See Also:
  Constant Field Values

#### IMPORT_CONTAINER

    static final int IMPORT_CONTAINER

Constant representing all import declarations within a compilation unit. A JavaScript element with this type can be safely cast to `IImportContainer`. This type only applies to ECMAScript 4 which is not yet supported

See Also:
  Constant Field Values

#### IMPORT_DECLARATION

    static final int IMPORT_DECLARATION

Constant representing an import declaration within a compilation unit. A JavaScript element with this type can be safely cast to `IImportDeclaration`. This type only applies to ECMAScript 4 which is not yet supported

See Also:
  Constant Field Values

#### LOCAL_VARIABLE

    static final int LOCAL_VARIABLE

Constant representing a local variable declaration. A JavaScript element with this type can be safely cast to `ILocalVariable`.

See Also:
  Constant Field Values

#### EXPORT_CONTAINER

    static final int EXPORT_CONTAINER

Constant representing all export declarations within a compilation unit. A JavaScript element with this type can be safely cast to `IExportContainer`.

See Also:
  Constant Field Values

#### EXPORT_DECLARATION

    static final int EXPORT_DECLARATION

Constant representing an export declaration within a compilation unit. A JavaScript element with this type can be safely cast to `IExportDeclaration`.

See Also:
  Constant Field Values

### Method Detail

#### exists

    boolean exists()

Returns whether this JavaScript element exists in the model.

JavaScript elements are handle objects that may or may not be backed by an actual element. JavaScript elements that are backed by an actual element are said to "exist", and this method returns `true`. For JavaScript elements that are not working copies, it is always the case that if the element exists, then its parent also exists (provided it has one) and includes the element as one of its children. It is therefore possible to navigated to any existing JavaScript element from the root of the JavaScript model along a chain of existing JavaScript elements. On the other hand, working copies are said to exist until they are destroyed (with `IWorkingCopy.destroy`). Unlike regular JavaScript elements, a working copy never shows up among the children of its parent element (which may or may not exist).

Returns:
  `true` if this element exists in the JavaScript model, and `false` if this element does not exist

#### getAncestor

    IJavaScriptElement getAncestor(int ancestorType)

Returns the first ancestor of this JavaScript element that has the given type. Returns `null` if no such an ancestor can be found. This is a handle-only method.

Parameters:
  `ancestorType` - the given type
Returns:
  the first ancestor of this JavaScript element that has the given type, null if no such an ancestor can be found

#### getAttachedJavadoc

    java.lang.String getAttachedJavadoc(IProgressMonitor monitor)
                                 throws JavaScriptModelException

Returns the Jsdoc as an html source if this element has an attached jsdoc, null otherwise.

This should be used only for binary elements. Source elements will always return null.

The encoding used to read the jsdoc is the one defined by the content type of the file. If none is defined, then the project's encoding of this java element is used. If the project's encoding cannot be retrieved, then the platform encoding is used.

In case of the jsdoc doesn't exist for this element, null is returned.

The html is extracted from the attached jsdoc and provided as is. No transformation or validation is done.

Parameters:
  `monitor` - the given progress monitor
Returns:
  the extracted jsdoc from the attached jsdoc, null if none
Throws:
  `JavaScriptModelException` - if:
  - this element does not exist
  - retrieving the attached jsdoc fails (timed-out, invalid URL, ...)
  - the format of the jsdoc doesn't match expected standards (different anchors,...)
See Also:
  `IIncludePathAttribute.JSDOC_LOCATION_ATTRIBUTE_NAME`

#### getCorrespondingResource

    IResource getCorrespondingResource()
                                throws JavaScriptModelException

Returns the resource that corresponds directly to this element, or `null` if there is no resource that corresponds to this element.

For example, the corresponding resource for an `IJavaScriptUnit` is its underlying `IFile`. The corresponding resource for an `IPackageFragment` that is not contained in an archive is its underlying `IFolder`. An `IPackageFragment` contained in an archive has no corresponding resource. Similarly, there are no corresponding resources for `IMethods`, `IFields`, etc.

Returns:
  the corresponding resource, or `null` if none
Throws:
  `JavaScriptModelException` - if this element does not exist or if an exception occurs while accessing its corresponding resource

#### getElementName

    java.lang.String getElementName()

Returns the name of this element. This is a handle-only method.

Returns:
  the element name

#### getElementType

    int getElementType()

Returns this element's kind encoded as an integer. This is a handle-only method.

Returns:
  the kind of element; one of the constants declared in `IJavaScriptElement`
See Also:
  `IJavaScriptElement`

#### getHandleIdentifier

    java.lang.String getHandleIdentifier()

Returns a string representation of this element handle. The format of the string is not specified; however, the identifier is stable across workspace sessions, and can be used to recreate this handle via the `JavaScriptCore.create(String)` method.

Returns:
  the string handle identifier
See Also:
  `JavaScriptCore.create(java.lang.String)`

#### getJavaScriptModel

    IJavaScriptModel getJavaScriptModel()

Returns the JavaScript model. This is a handle-only method.

Returns:
  the JavaScript model

#### getJavaScriptProject

    IJavaScriptProject getJavaScriptProject()

Returns the JavaScript project this element is contained in, or `null` if this element is not contained in any JavaScript project (for instance, the `IJavaScriptModel` is not contained in any JavaScript project). This is a handle-only method.

Returns:
  the containing JavaScript project, or `null` if this element is not contained in a JavaScript project

#### getOpenable

    IOpenable getOpenable()

Returns the first openable parent. If this element is openable, the element itself is returned. Returns `null` if this element doesn't have an openable parent. This is a handle-only method.

Returns:
  the first openable parent or `null` if this element doesn't have an openable parent.

#### getParent

    IJavaScriptElement getParent()

Returns the element directly containing this element, or `null` if this element has no parent. This is a handle-only method.

Returns:
  the parent element, or `null` if this element has no parent

#### getPath

    IPath getPath()

Returns the path to the innermost resource enclosing this element. If this element is not included in an external archive, the path returned is the full, absolute path to the underlying resource, relative to the workbench. If this element is included in an external archive, the path returned is the absolute path to the archive in the file system. This is a handle-only method.

Returns:
  the path to the innermost resource enclosing this element

#### getPrimaryElement

    IJavaScriptElement getPrimaryElement()

Returns the primary element (whose compilation unit is the primary compilation unit) this working copy element was created from, or this element if it is a descendant of a primary javaScript unit or if it is not a descendant of a working copy (e.g. it is a binary member). The returned element may or may not exist.

Returns:
  the primary element this working copy element was created from, or this element.

#### getResource

    IResource getResource()

Returns the innermost resource enclosing this element. If this element is included in an archive and this archive is not external, this is the underlying resource corresponding to the archive. If this element is included in an external archive, `null` is returned. This is a handle-only method.

Returns:
  the innermost resource enclosing this element, `null` if this element is included in an external archive

#### getSchedulingRule

    ISchedulingRule getSchedulingRule()

Returns the scheduling rule associated with this JavaScript element. This is a handle-only method.

Returns:
  the scheduling rule associated with this JavaScript element

#### getUnderlyingResource

    IResource getUnderlyingResource()
                             throws JavaScriptModelException

Returns the smallest underlying resource that contains this element, or `null` if this element is not contained in a resource.

Returns:
  the underlying resource, or `null` if none
Throws:
  `JavaScriptModelException` - if this element does not exist or if an exception occurs while accessing its underlying resource

#### isReadOnly

    boolean isReadOnly()

Returns whether this JavaScript element is read-only. An element is read-only if its structure cannot be modified by the java model.

Note this is different from IResource.isReadOnly(). For example, .jar files are read-only as the javaScript model doesn't know how to add/remove elements in this file, but the underlying IFile can be writable.

This is a handle-only method.

Returns:
  `true` if this element is read-only

#### isStructureKnown

    boolean isStructureKnown()
                      throws JavaScriptModelException

Returns whether the structure of this element is known. For example, for a javaScript file that could not be parsed, `false` is returned. If the structure of an element is unknown, navigations will return reasonable defaults. For example, `getChildren` will return an empty collection.

Note: This does not imply anything about consistency with the underlying resource/buffer contents.

Returns:
  `true` if the structure of this element is known
Throws:
  `JavaScriptModelException` - if this element does not exist or if an exception occurs while accessing its corresponding resource

#### getDisplayName

    java.lang.String getDisplayName()

Returns a readable (non mangled) name. In virtual elements this is derived from a JsGlobalScopeContainerInitializer

Returns:
  a human friendly element name.

#### isVirtual

    boolean isVirtual()

Returns if this is a virtual element (ie actually exists in the model or filesystem).

Returns:
  if this is a virtual element.

#### getHostPath

    java.net.URI getHostPath()

If a resource is virtual, then return a real host path for the element. (Query the container initializer).

Returns:
  if this is a virtual element.

#### getCommonSuperType

    LibrarySuperType getCommonSuperType()

Returns the Super type this file is considered to be a member of. For Browser base javaScript, this would be "Window".

Returns:
  the supertype for the javascript file.