org.eclipse.wst.jsdt.core
Interface IJavaScriptElement

All Superinterfaces:
ILookupScope
All Known Subinterfaces:
IClassFile, IField, IFunction, IImportContainer, IImportDeclaration, IInitializer, IJavaScriptModel, IJavaScriptProject, IJavaScriptUnit, ILocalVariable, IMember, IPackageDeclaration, IPackageFragment, IPackageFragmentRoot, IType, ITypeParameter, 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
static int CLASS_FILE
          Constant representing a non-editable javaScript file.
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_DECLARATION
          Constant representing a package declaration within a compilation unit.
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).
static int TYPE_PARAMETER
          Constant representing a type parameter declaration.
 
Method Summary
 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

PACKAGE_DECLARATION

static final int PACKAGE_DECLARATION
Constant representing a package declaration within a compilation unit. A JavaScript element with this type can be safely cast to IPackageDeclaration. This type only applies to ECMAScript 4 which is not yet supported

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

TYPE_PARAMETER

static final int TYPE_PARAMETER
Constant representing a type parameter declaration. A JavaScript element with this type can be safely cast to ITypeParameter. This type only applies to ECMAScript 4 which is not yet supported

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.