DefaultSourceElement Class

com.bea.ide.sourceeditor.element
DefaultSourceElement Class

public abstract class DefaultSourceElement

    extends DefaultDocumentElement
    implements ISourceElement, IStructureFeature.IStructureNode

A default implementation of ISourceElement.


Hierarchy
Object
  DefaultElement
    DefaultTreeElement
      DefaultDocumentElement
        DefaultSourceElement
All Implemented Interfaces

IDocumentElement, IElement, ISourceElement, IStructureFeature.IStructureNode, ITreeElement
Direct Known Subclasses

InvalidElement, JavaElement, XmlDocumentRoot, XmlNode

Nested Class Summary

protected classDefaultSourceElement.CompilerPropertyDescriptor
           A CompilerPropertyDescriptor object describes a property that is found on a given source element type.
protected classDefaultSourceElement.DefaultAuthorElement
           DefaultAuthorElement are returned from createAuthorNode as part of the two-way editing process.
protected static classDefaultSourceElement.StaticCompilerPropertyDescriptor
           For performance, a class that can be passed to CompilerPropertyDescriptor's constructor to save the overhead of finding the getter and setter methods.
protected classDefaultSourceElement.StickyRange
           A StickyRange is a Range object whose start and end offsets track modifications to the source document.

Field Summary

protected DefaultSourceElement.StickyRange
_range
The range of this element.
public static final String
PROP_NAME
A constant used to identify the name property on a source element.
public static final String
PROP_VALUE
A constant used to identify the value property on a source element.
   
Fields from  com.bea.ide.element.DefaultTreeElement
_parent, _vChildren
 
Fields from interface com.bea.ide.sourceeditor.element.ISourceElement
STATUS_IN_TREE, STATUS_NOT_IN_TREE, STATUS_REMOVED_FROM_TREE
 

Constructor Summary

DefaultSourceElement(Object structureNodeCookie)

Creates a new DefaultSourceElement.
 

Method Summary

public void
addChild(ITreeElement child)
Adds a child to this element.
public IStructureFeature.IAuthorNode
createAuthorNode()
Used by IDE two-way editing code to create a template node that will be passed to the compiler.
public void
debugDump(StringBuffer buf, int depth)
A simple means of viewing the document's parse tree for debugging purposes.
public boolean
equals(Object o)
Compares two elements with each other.
public List
getChildrenByClass(Class type)
Allows for quick retrieval of all children of a given type.
public ClassLoader
getClassLoader()
Utility method to return the current application classloader.
public final Object
getCookie()
Returns a cookie object provided by the compiler at creation time.
protected abstract DefaultSourceElement.CompilerPropertyDescriptor[]
getDefaultPropertyDescriptors()
DefaultSourceElement subclasses define their set of available CompilerPropertyDescriptor objects by implementing this method.
public List
getDiagnostics()
Returns a list of all diagnostics that overlap or are contained by the range of this element.
public ISourceElementGroup
getGroup()
By default, elements are not grouped together (other than by parentage).
public String
getInstanceName()
Returns the name property for this element, if such a property exists.
public Object
getProperty(String sProp)
Gets a property from this source element.
public IStructureFeature.StructureCode
getPropertyCode(String propertyName)
Returns a code used by the compiler to identify property types.
public final PropertyDescriptor[]
getPropertyDescriptors()
This method returns this element's set of property descriptors.
protected DefaultSourceElement.StickyRange
getPropertySourceRange(IStructureFeature.StructureCode prop)
Returns the source range that is occupied by an element property.
protected DefaultSourceElement.StickyRange[]
getPropertySourceRanges(IStructureFeature.StructureCode prop)
Returns nn array of source ranges occupied by an element property.
protected String
getPropertySourceText(IStructureFeature.StructureCode prop)
Gets the source text for a particular property.
public String
getPropertySourceText(String sProp)
Gets the source text for a particular property.
public Range
getRange(ISourceDocument doc)
Gets the range of this source element.
public Range
getRange()
Gets the range of this source element.
protected Set
getRangePrefetchProperties()
Returns a Set of IStructureFeature.StructureCode objects.
public int
getStatus()
Gets the tree status of this element.
public abstract IStructureFeature.StructureCode
getTypeCode()
This method returns a code used by the compiler to identify the type of this element.
public void
initializeRange(ISourceDocument doc)
Initializes the range of this element.
protected void
initializeRange(IStructureFeature structureFeature, ISourceModel model)
Converts compiler provided range information into source model sticky positions.
public void
insertChild(int index, ISourceElement newChild)
Adds a child to this element.
protected boolean
isAuthorProperty(DefaultSourceElement.CompilerPropertyDescriptor pd)
Allows a DefaultSourceElement derivation to specify that certain properties should not be passed to the compiler when performing a two way edit.
public void
markRemovedFromTree()
Mark this element as removed from the parse tree.
public boolean
mergeElements(ISourceElement sourceElement)
Called when a new parse tree has been made available by the compiler to merge the new data into the existing tree generating appropriate change events.
public void
mergeFrom(ISourceElement sourceElement)
Merges the contents of one source element into the this source element, firing property change events as appropriate.
public void
propertyModified(String sProperty, Object oldValue, Object newValue)
Utility method used to initiate an element change events.
public ISourceElement
removeChild(int index)
Removes a child from this element.
public void
removeChild(ITreeElement child)
Removes a child from this element.
public ISourceElement
replaceChild(int index, ISourceElement replacement)
Replaces a child of this element.
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.
public void
setProperty(String sProp, Object value)
Sets a property on this element, firing property change events as appropriate.
protected void
setStatus(int status)
Set the status of this element.
 
Methods from  com.bea.ide.document.DefaultDocumentElement
getDocument, setDocument
 
Methods from  com.bea.ide.element.DefaultTreeElement
addChild, children, getChild, getChildCount, getParent,
 
Methods from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
   
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.sourceeditor.element.ISourceElement
createAuthorNode, getCookie, getDiagnostics, getPropertyCode, getRange, getStatus, mergeFrom, requestAddChild, requestAddChild, requestRemoveChild, requestSetProperty
 
Methods from interface com.bea.compiler.feature.IStructureFeature.IStructureNode
getCookie, getTypeCode
 
Methods from interface com.bea.ide.element.ITreeElement
children, getChild, getChildCount, getParent
 

Field Detail

_range

protected DefaultSourceElement.StickyRange _range
The range of this element. Note that this value isn't valid until initializeRange has been called, so it is generally best to get range information by calling getRange, unless direct access to this member variable is required.


PROP_NAME

public static final String PROP_NAME
A constant used to identify the name property on a source element.


PROP_VALUE

public static final String PROP_VALUE
A constant used to identify the value property on a source element.

 

Constructor Detail

DefaultSourceElement

public DefaultSourceElement(Object structureNodeCookie)
Creates a new DefaultSourceElement.
 

Method Detail

addChild(ITreeElement) Method

public void addChild(ITreeElement child)
Adds a child to this element. This method may only be called on elements that are not part of a parse tree. Once an element is part of a parse tree, DefaultSourceElement.requestAddChild(ISourceElement) must be used instead.

Overrides
DefaultDocumentElement.addChild(ITreeElement)

Parameters

child
the child to be added.

createAuthorNode() Method

public IStructureFeature.IAuthorNode createAuthorNode()
Description copied from ISourceElement.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.

Related Topics

ISourceElement.createAuthorNode()


debugDump(StringBuffer, int) Method

public void debugDump(StringBuffer buf, 
                      int depth)
A simple means of viewing the document's parse tree for debugging purposes.

Parameters

buf
the buffer into which to place the tree description
depth
the current depth of recursion, used to determine indentation level. External callers will probably want to pass zero to this method.

equals(Object) Method

public boolean equals(Object o)
Compares two elements with each other. Two elements are only equal if they are of the same type and if all of their properties are equal. If both elements are part of a compiler-produced parse trees, their documents and document ranges are compared as well.

Overrides
Object.equals(Object)

Parameters

o
the object to which this element should be compared

Returns

boolean indicating whether this element is equal to the provided element

getChildrenByClass(Class) Method

public List getChildrenByClass(Class type)
Allows for quick retrieval of all children of a given type.

Parameters

type
The class of the elements that are desired. For example, "JavaMethod.class".

Returns

A non-null list of all children of the specified type. This list may be empty. It is always safe to cast the elements in the returned list to the element type requested.

getClassLoader() Method

public ClassLoader getClassLoader()
Utility method to return the current application classloader.

Returns

The current ClassLoader

getCookie() Method

public final Object getCookie()
Description copied from ISourceElement.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.


getDefaultPropertyDescriptors() Method

protected abstract DefaultSourceElement.CompilerPropertyDescriptor[] getDefaultPropertyDescriptors()
DefaultSourceElement subclasses define their set of available CompilerPropertyDescriptor objects by implementing this method.

Returns

an array of CompilerPropertyDescriptor objects

getDiagnostics() Method

public List getDiagnostics()
Returns a list of all diagnostics that overlap or are contained by the range of this element. This method can only be used to determine if any diagnostics will be visible within this element in source view. This method cannot determine if the cause of a diagnostic (a code error, for example) lies within a particular source element.

Returns

A list of all diagnostics overlapping or contained by this element.

getGroup() Method

public ISourceElementGroup getGroup()
By default, elements are not grouped together (other than by parentage). To be groupable, a class must override this method.


getInstanceName() Method

public String getInstanceName()
Returns the name property for this element, if such a property exists.

Returns

This property's name, null if no such property exists.

getProperty(String) Method

public Object getProperty(String sProp)
Gets a property from this source element.

Overrides
DefaultElement.getProperty(String)

Parameters

sProp
The desired property's name. This property must be part of this element's property descriptors.

Returns

The property's value.

getPropertyCode(String) Method

public IStructureFeature.StructureCode getPropertyCode(String propertyName)
Returns a code used by the compiler to identify property types.

Parameters

propertyName
The IDE-side name for a property, generally defined in that property's DefaultSourceElement.CompilerPropertyDescriptor

Returns

The compiler id for the specified property name.

getPropertyDescriptors() Method

public final PropertyDescriptor[] getPropertyDescriptors()
This method returns this element's set of property descriptors. DefaultSourceElements do not provide their properties directly via this method. This functionality is handled by the getDefaultPropertyDescriptors method.

Overrides
DefaultElement.getPropertyDescriptors()

Returns

Array of property descriptor objects describing the properties that this IElement exposes

getPropertySourceRange(IStructureFeature.StructureCode) Method

protected DefaultSourceElement.StickyRange getPropertySourceRange(IStructureFeature.StructureCode prop)
Returns the source range that is occupied by an element property. If a property occupies more than one disjoint range, the first range will be returned. For example, take the following variable declaration:

    int a[];

If we assume that this declaration starts at offset 100, the range of the type property occupies [100, 103) and [105, 107). This method would return the StickyRange corresponding to [100, 103) only. If the both ranges are needed, call DefaultSourceElement.getPropertySourceRanges(IStructureFeature.StructureCode).

Parameters

prop
the property for which a range is desired

Returns

the range in source that the property's source text occupies.

getPropertySourceRanges(IStructureFeature.StructureCode) Method

protected DefaultSourceElement.StickyRange[] getPropertySourceRanges(IStructureFeature.StructureCode prop)
Returns nn array of source ranges occupied by an element property. This array almost always contains just one entry. However, in some circumstances, two or more entries are possible. For example, take the following variable declaration:

    int a[];

If we assume that this declaration starts at offset 100, the range of the type property occupies [100, 103) and [105, 107). This method would return the an array that contains both ranges.

Parameters

prop
the property for which a range is desired

Returns

the range in source that the property's source text occupies.

getPropertySourceText(IStructureFeature.StructureCode) Method

protected String getPropertySourceText(IStructureFeature.StructureCode prop)
Gets the source text for a particular property. For example, the return type property of a JavaMethod will always be fully qualified- to determine the return type type as it appears in source, this method must be used.

Parameters

prop
The property for which source text is desired.

Returns

The source text for the property, possibly null.

getPropertySourceText(String) Method

public String getPropertySourceText(String sProp)
Gets the source text for a particular property. For example, the return type property of a JavaMethod will always be fully qualified- to determine the return type type as it appears in source, this method must be used.

Parameters

sProp
The name of the property for which source text is desired.

Returns

The source text for the property, possibly null.

getRange(ISourceDocument) Method

public Range getRange(ISourceDocument doc)
Gets the range of this source element. This method may only be called on methods that are part of a valid parse tree. For example, calling (new JavaMethod()).getRange() will fail with an UnsupportedOperationException.

Parameters

doc
currently ignored, may be used in a future implementation during construction of new parse trees.

Returns

The range that this element occupies in source. [0, 0) will be returned

getRange() Method

public Range getRange()
Gets the range of this source element. This method may only be called on methods that are part of a valid parse tree. For example, calling (new JavaMethod()).getRange() will fail with an UnsupportedOperationException.

Returns

The range that this element occupies in source. [0, 0) will be returned

getRangePrefetchProperties() Method

protected Set getRangePrefetchProperties()
Returns a Set of IStructureFeature.StructureCode objects. This set defines those properties that will contain range information in the parse tree.


getStatus() Method

public int getStatus()
Gets the tree status of this element.

Returns

One of the ISourceElement status constants.

getTypeCode() Method

public abstract IStructureFeature.StructureCode getTypeCode()
This method returns a code used by the compiler to identify the type of this element. This method should not be called directly, since the return value isn't useful outside of the compiler.

Returns

A compiler structure code identifying the type of this element.

initializeRange(ISourceDocument) Method

public void initializeRange(ISourceDocument doc)
Initializes the range of this element. Called as part of construction of a new parse tree, before the tree has been associated with a document. This method is public for implementation purposes only, and should not be called externally. Call DefaultSourceElement.getRange(ISourceDocument) to get the range of an element.

Parameters

doc
The source document that that will be associated with this element's tree once tree construction is complete.

initializeRange(IStructureFeature, ISourceModel) Method

protected void initializeRange(IStructureFeature structureFeature, 
                               ISourceModel model)
Converts compiler provided range information into source model sticky positions. This method assumes it is run on the AWT thread.


insertChild(int, ISourceElement) Method

public void insertChild(int index, 
                        ISourceElement newChild)
Adds a child to this element. This method may only be called on elements that are not part of a parse tree. Once an element is part of a parse tree, ISourceElement.requestAddChild(ISourceElement, int) must be used instead.

Parameters

index
the index at which the child should be added.

isAuthorProperty(DefaultSourceElement.CompilerPropertyDescriptor) Method

protected boolean isAuthorProperty(DefaultSourceElement.CompilerPropertyDescriptor pd)
Allows a DefaultSourceElement derivation to specify that certain properties should not be passed to the compiler when performing a two way edit.

Parameters

pd
The property descriptor that could be passed to the compiler

Returns

boolean indicating whether the specified property should be passed.

markRemovedFromTree() Method

public void markRemovedFromTree()
Mark this element as removed from the parse tree. This will cascade down through all of this element's children.


mergeElements(ISourceElement) Method

public boolean mergeElements(ISourceElement sourceElement)
Called when a new parse tree has been made available by the compiler to merge the new data into the existing tree generating appropriate change events. This method is public for implementation reasons, and should not generally be called directly.

The merge algorithm is recursive, descending down through the element tree starting from the root. Each element first checks its properties (in the case of a method, these would be name, return type, access specification, etc.) against the element to which it is being compared. Property change notifications are sent if any properties differ. The element is then responsible for determining if the child sets of the old and new elements differ. This is done by first comparing the left-most child in each child in each list. If they are the same, we move one child to the right in each list, and repeat the comparison. This continues until we find a child pair that is not equal, or run out of children to compare. If we run out of children, we know the child lists are the same, and we move on, recursing down into each. If an inequality was found, we store the location of the inequality and start comparisons again, this time from the right side of the lists, working our way left. In this way, we end up with an interval (the “gap�) in each list where we know changes have occurred.

For example, lets say that the old list contained three elements, A, B, and C, and that the new list contained two elements, A and C. Starting from the left, we see that the elements in the first position are equal (A and A), but the elements in the second position of each list are not (B and C). From the right, we see that the elements in the last position are the same (C and C), but the elements in the second-to-last position are not (B and A). We now have two gaps, on in each list, between known list equalities. The gap in the old list is between items 1 and 3, since items 1 and 3 both had matches in the other list. The gap in the new list is empty, since every item was matched up. A non-empty gap in the old list and an empty gap in the new list indicates the removal of all elements in the gap, so element-removed notifications are sent for the missing elements. Likewise, an empty gap in the old list and a non-empty gap in the new list indicates that elements were inserted, and non-empty gaps in both lists indicate to changes to single children, or combinations of replacements and removals, as can occur when pasting one block of code over another.

This algorithm is very fast (linear time for number of elements in the tree), and works because we can safely make the assumption that code changes tend to be contiguous. The algorithm falls apart in the case where there are simultaneous insertions at the top and bottom of the file, for example, since the gaps would then span the entirety of both lists. In practice, this occurs extremely rarely.

Parameters

sourceElement
The new element to be merged into this one.

Returns

boolean indicating whether the merge was successful. A false return value generally indicates to the parent that element change events should be fired.

mergeFrom(ISourceElement) Method

public void mergeFrom(ISourceElement sourceElement)
Description copied from ISourceElement.mergeFrom(ISourceElement)
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.

Related Topics

ISourceElement.mergeFrom(ISourceElement)


propertyModified(String, Object, Object) Method

public void propertyModified(String sProperty, 
                             Object oldValue, 
                             Object newValue)
Utility method used to initiate an element change events. This method is public for implmentation reasons, and should not be called directly.

Parameters

sProperty
The property that has changed
oldValue
The old value of the property
newValue
The new value of the property

removeChild(int) Method

public ISourceElement removeChild(int index)
Removes a child from this element. This method may only be called on elements that are not part of a parse tree. Once an element is part of a parse tree, DefaultSourceElement.requestRemoveChild(ISourceElement) must be used instead.

Parameters

index
the index of the child to be removed

Returns

the removed element

removeChild(ITreeElement) Method

public void removeChild(ITreeElement child)
Removes a child from this element. This method may only be called on elements that are not part of a parse tree. Once an element is part of a parse tree, DefaultSourceElement.requestRemoveChild(ISourceElement) must be used instead.

Overrides
DefaultTreeElement.removeChild(ITreeElement)

Parameters

child
the child to be removed

replaceChild(int, ISourceElement) Method

public ISourceElement replaceChild(int index, 
                                   ISourceElement replacement)
Replaces a child of this element. This method may only be called on elements that are not part of a parse tree. Once an element is part of a parse tree, DefaultSourceElement.requestRemoveChild(ISourceElement) and DefaultSourceElement.requestAddChild(ISourceElement) must be used. instead.

Parameters

index
the index of the child to be replaced
replacement
the child to insert after the current child is removed

Returns

the removed child

requestAddChild(ISourceElement) Method

public ISourceElement requestAddChild(ISourceElement newChild)
throws InvalidElementException
Description copied from ISourceElement.requestAddChild(ISourceElement)
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

Related Topics

ISourceElement.requestAddChild(ISourceElement)


requestAddChild(ISourceElement, int) Method

public ISourceElement requestAddChild(ISourceElement newChild, 
                                      int index)
throws InvalidElementException
Description copied from ISourceElement.requestAddChild(ISourceElement, int)
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

Related Topics

ISourceElement.requestAddChild(ISourceElement, int)


requestRemoveChild(ISourceElement) Method

public void requestRemoveChild(ISourceElement child)
throws InvalidElementException
Description copied from ISourceElement.requestRemoveChild(ISourceElement)
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

Related Topics

ISourceElement.requestRemoveChild(ISourceElement)


requestSetProperty(String, Object) Method

public void requestSetProperty(String strProp, 
                               Object value)
throws InvalidElementException
Description copied from ISourceElement.requestSetProperty(String, Object)
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

Related Topics

ISourceElement.requestSetProperty(String, Object)


setProperty(String, Object) Method

public void setProperty(String sProp, 
                        Object value)
Sets a property on this element, firing property change events as appropriate. This method may only be called on elements that are not part of a parse tree. Once an element is part of a parse tree, ISourceElement.requestSetProperty(String, Object) must be used instead.

Overrides
DefaultElement.setProperty(String, Object)

Parameters

sProp
The property to set. This property must be defined in this element's property descriptors.
value
The new value of the property

setStatus(int) Method

protected void setStatus(int status)
Set the status of this element. Note that setting the status to ISourceElement.STATUS_REMOVED_FROM_TREE will additionally cascade down through this element's children.

Parameters

status
One of the status constants defined on the ISourceElement interface.