# com.bea.ide.sourceeditor.element
ISourceElement Interface

public interface ISourceElement
extends `IDocumentElement`

An ISourceElement is a specific type of IElement corresponding to the contents of a document. All parse tree elements are of type ISourceElement.

All Known Implementing Classes
  `DefaultSourceElement`

All Superinterfaces
  `IDocumentElement`, `IElement`, `ITreeElement`

All Known Subinterfaces
  `IDOMSourceElement`

## Field Summary

`public static final int` | `STATUS_IN_TREE` Status value, returned from `getStatus```, indicating that this element is currently part of a valid parse tree.
`public static final int` | `STATUS_NOT_IN_TREE` Status value, returned from `getStatus```, indicating that this element has not been part of any parse tree.
`public static final int` | `STATUS_REMOVED_FROM_TREE` Status value, returned from `getStatus```, indicating that this element was once part of a valid parse tree, but has since been removed.

## Method Summary

`public `IStructureFeature.IAuthorNode`` | `createAuthorNode`() Used by IDE two-way editing code to create a template node that will be passed to the compiler.
`public `Object`` | `getCookie`() Returns a cookie object provided by the compiler at creation time.
`public `List`` | `getDiagnostics`() Returns a list of the `ICompilerDiagnostic``` objects found in the text corresponding to this source element.
`public `IStructureFeature.StructureCode`` | `getPropertyCode`(`String` propertyName) This method allows the IDE elements to maintain a property set with different names than those provided by the compiler by providing a mechanism by which IDE names can be mapped back to compiler type codes.
`public `Range`` | `getRange`() Returns the text range occupied by the source element.
`public int` | `getStatus`() Returns the constant indicating the current status of this ISourceElement.
`public void` | `mergeFrom`(`ISourceElement` sourceElement) Merges the contents of one source element into the this source element, firing property change events as appropriate.
`public `ISourceElement`` | `requestAddChild`(`ISourceElement` newChild) Two way editing method allowing for the direct addition of children to an element in an ISourceElement parse tree.
`public `ISourceElement`` | `requestAddChild`(`ISourceElement` newChild, int index) Two way editing method allowing for the direct addition of children to an element in an ISourceElement parse tree.
`public void` | `requestRemoveChild`(`ISourceElement` child) Two way editing method allowing for the direct removal of children from an ISourceElement parse tree.
`public void` | `requestSetProperty`(`String` strProp, `Object` value) Two way editing method allowing for the direct manipulation of property values of an element in an ISourceElement parse tree.

Methods from interface `com.bea.ide.document.`IDocumentElement``
``getDocument``

Methods from interface `com.bea.ide.element.`IElement``
``getProperty`, `getPropertyDescriptors`, `setProperty``

Methods from interface `com.bea.ide.element.`ITreeElement``
``children`, `getChild`, `getChildCount`, `getParent``

## Field Detail

### STATUS_IN_TREE

    public static final int STATUS_IN_TREE

  Status value, returned from `getStatus```, indicating that this element is currently part of a valid parse tree.

### STATUS_NOT_IN_TREE

    public static final int STATUS_NOT_IN_TREE

  Status value, returned from `getStatus```, indicating that this element has not been part of any parse tree. This status generally only applies to elements that have been created for for purposes of an upcoming two-way edit.

### STATUS_REMOVED_FROM_TREE

    public static final int STATUS_REMOVED_FROM_TREE

  Status value, returned from `getStatus```, indicating that this element was once part of a valid parse tree, but has since been removed. Two-way edits may not be performed on elements with this status.

## Method Detail

### createAuthorNode() Method

    public IStructureFeature.IAuthorNode createAuthorNode()

Used by IDE two-way editing code to create a template node that will be passed to the compiler. Note that IAuthorNodes are intended to be created, possibly modified, passed to the compiler, and then discarded. There is no guarantee that the author node will remain in the same form after being passed to the compiler.

#### Returns

a snapshot of the current node in a form that can be used for the purposes of two-way editing.

### getCookie() Method

    public Object getCookie()

Returns a cookie object provided by the compiler at creation time. This value has no meaning to code outside of the compiler. This method should never be called within IDE extension code.

### getDiagnostics() Method

    public List getDiagnostics()

Returns a list of the `ICompilerDiagnostic``` objects found in the text corresponding to this source element. Note that diagnostics overlapping the range will be returned as well as those that are completely contained.

#### Returns

A list of `ICompilerDiagnostic``` objects.

### getPropertyCode(String) Method

    public IStructureFeature.StructureCode getPropertyCode(String propertyName)

This method allows the IDE elements to maintain a property set with different names than those provided by the compiler by providing a mechanism by which IDE names can be mapped back to compiler type codes.

#### Parameters

propertyName
  an IDE element property name

#### Returns

a compiler type code. The return value must be the same as that passed to the `setProperty``` call that creates properties of this type.

### getRange() Method

    public Range getRange()

Returns the text range occupied by the source element.

### getStatus() Method

    public int getStatus()

Returns the constant indicating the current status of this ISourceElement. See status constants for more information.

### mergeFrom(ISourceElement) Method

    public void mergeFrom(ISourceElement sourceElement)

Merges the contents of one source element into the this source element, firing property change events as appropriate. The elements must be of compatible types. This method is used on an element-by-element basis when merging a new parse tree into an existing tree. After the merge, `this.equals(sourceElement)` will return true while `this == sourceElement` will return false. Note that this method has no effect on the children of the source or destination elements: it only applies to element properties.

#### Parameters

sourceElement
  the element from which to copy data.

### requestAddChild(ISourceElement) Method

    public ISourceElement requestAddChild(ISourceElement newChild)
         throws InvalidElementException

Two way editing method allowing for the direct addition of children to an element in an ISourceElement parse tree. Once an element is part of a compiled document, modifications to the element structure must be made via 'request' methods. These methods send the modification request to the compiler, which will cause a modification of the document source code, followed by a reparse and subsequent element change events on the document. Note that this method initiates an asynchronous call; completion of the edit is indicated by an element change event, not by the return from the call.

#### Parameters

newChild
  a template for the child element to be added. `newChild` itself will NOT be added to the parse tree, though an element equivalent to it will appear after the edit completes. Source code corresponding to this element will be inserted into the source document.

#### Returns

The new child added, if found. This method will return null in the case of addition failure, or in the case where the addition of a child may have caused the removal of the parent element.

#### Exceptions

``InvalidElementException``
  if the element state is not valid. This is most frequently caused by attempting to perform a two-way edit on an element that is no longer part of a valid parse tree. Calling `getStatus``` on this element to verify in-tree status is one way to reduce occurrences of this problem.

### requestAddChild(ISourceElement, int) Method

    public ISourceElement requestAddChild(ISourceElement newChild,
                                          int index)
         throws InvalidElementException

Two way editing method allowing for the direct addition of children to an element in an ISourceElement parse tree. Once an element is part of a compiled document, modifications to the element structure must be made via 'request' methods. These methods send the modification request to the compiler, which will cause a modification of the document source code, followed by a reparse and subsequent element change events on the document. Note that this method initiates an asynchronous call; completion of the edit is indicated by an element change event, not by the return from the call.

#### Parameters

newChild
  a template for the child element to be added. `newChild` itself will NOT be added to the parse tree, though an element equivalent to it will appear after the edit completes. Source code corresponding to this element will be inserted into the source document.

index
  The index, relative to the new child's siblings, where the element should be inserted

#### Returns

The new child added, if found. This method will return null in the case of addition failure, or in the case where the addition of a child may have caused the removal of the parent element.

#### Exceptions

``InvalidElementException``
  if the element state is not valid. This is most frequently caused by attempting to perform a two-way edit on an element that is no longer part of a valid parse tree. Calling `getStatus``` on this element to verify in-tree status is one way to reduce occurrences of this problem.

### requestRemoveChild(ISourceElement) Method

    public void requestRemoveChild(ISourceElement child)
         throws InvalidElementException

Two way editing method allowing for the direct removal of children from an ISourceElement parse tree. Once an element is part of a compiled document, modifications to the element structure must be made via 'request' methods. These methods send the modification request to the compiler, which will cause a modification of the document source code, followed by a reparse and subsequent element change events on the document. Note that this method initiates an asynchronous call; completion of the edit is indicated by an element change event, not by the return from the call.

#### Parameters

child
  the element to be removed from the parse tree. All corresponding source code will be deleted from the document.

#### Exceptions

``InvalidElementException``
  if the element state is not valid. This is most frequently caused by attempting to perform a two-way edit on an element that is no longer part of a valid parse tree. Calling `getStatus``` on this element to verify in-tree status is one way to reduce occurrences of this problem.

### requestSetProperty(String, Object) Method

    public void requestSetProperty(String strProp,
                                   Object value)
         throws InvalidElementException

Two way editing method allowing for the direct manipulation of property values of an element in an ISourceElement parse tree. Once an element is part of a compiled document, modifications to the element must be made via 'request' methods. These methods send the modification request to the compiler, which will cause a modification of the document source code, followed by a reparse and subsequent element change events on the document. Note that this method initiates an asynchronous call; completion of the edit is indicated by an element change event, not by the return from the call.

#### Parameters

strProp
  the IDE property name to be modified

value
  the new value for the property. It is the caller's responsibility to ensure that the object type is compatible with property values accepted by the compiler.

#### Exceptions

``InvalidElementException``
  if the element state is not valid. This is most frequently caused by attempting to perform a two-way edit on an element that is no longer part of a valid parse tree. Calling `getStatus``` on this element and the child element to verify in-tree status is one way to prevent this problem.