com.bbn.swede.core.dom
Class OASTEvent

java.lang.Object
  extended bycom.bbn.swede.core.dom.OASTEvent

public class OASTEvent
extends Object

Represents the addition, removal, or replacement of nodes in an OAST.

Author:
jlerner

Nested Class Summary
protected  class OASTEvent.NodeLocationVisitor
          Searches for a delta indicating a change in a specific OAST node.
 class OASTEvent.OASTNodeRef
          Provides a reference to the node that originally caused an event and its state at the time.
 
Constructor Summary
OASTEvent(IOASTDelta delta)
          Constructs a new OASTEvent representing a change signified by an OAST delta.
OASTEvent(OASTEvent other)
          Creates a deep copy of an OAST event.
OASTEvent(OASTNode[] removed, OASTNode[] inserted)
          Deprecated. As of SWeDE 2.0.0, use OASTEvent(IOASTDelta) instead.
 
Method Summary
(package private)  void combine(OASTEvent other)
          Turns this event into a composite event.
 int getCount()
          Returns the number of individual events represented by this object.
 IOASTDelta getDelta()
          Retrieves the OAST delta containing detailed information about the changes involved in this event.
 IOASTDelta getDelta(OASTNode node)
          Searches the delta tree for a delta representing a change in a specific OAST node.
 OASTNode[] getInserted()
          Deprecated. As of SWeDE 2.0.0, use getCount(), getRemoved(int), and getInserted(int) instead. These methods allow you to properly capture the sequence of top-level removes and inserts represented by this event. If this sequence of events is unimportant, considering using getDelta() instead.
 OASTEvent.OASTNodeRef[] getInserted(int iEvent)
          Retrieves the inserted nodes array for a specific discrete event encapsulated by this composite event.
 IOWLAbstractSyntaxTree getOWLAbstractSyntaxTree()
          Retrieves the OWL abstract syntax tree affected by this event.
 OASTNode getPrimaryNode()
          Retrieves the node that is the primary focus of this event.
 OASTNode[] getRemoved()
          Deprecated. As of SWeDE 2.0.0, use getCount(), getRemoved(int), and getInserted(int) instead. These methods allow you to properly capture the sequence of top-level removes and inserts represented by this events. If this sequence of events is unimportant, considering using getDelta() instead.
 OASTEvent.OASTNodeRef[] getRemoved(int iEvent)
          Retrieves the removed nodes array for a specific discrete event encapsulated by this composite event.
 boolean isInsert()
          Indicates if this event represents a node insertion.
 boolean isRemove()
          Indicates if this event represents a node removal.
 boolean isReplace()
          Indicates if this event represents a node replacement.
 boolean isTextEvent()
          Indicates whether or not this is a text event.
(package private)  void setPrimaryNode(OASTNode node)
          Marks a node as the primary focus of the event.
(package private)  void setTextEvent(boolean bTextEvent)
          Sets whether or not this is a text event.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OASTEvent

public OASTEvent(OASTEvent other)
Creates a deep copy of an OAST event.

Parameters:
other - The event to clone

OASTEvent

public OASTEvent(OASTNode[] removed,
                 OASTNode[] inserted)
Deprecated. As of SWeDE 2.0.0, use OASTEvent(IOASTDelta) instead.

Constructs a new OASTEvent representing a specific set of additions and removals. A reparse delta will be created for the event. Both the removed and inserted arrays must contain at least one element.

Parameters:
removed - Array of nodes being removed
inserted - Array of nodes being inserted

OASTEvent

public OASTEvent(IOASTDelta delta)
Constructs a new OASTEvent representing a change signified by an OAST delta. The lists of removed and inserted notes are created based on the delta for compatibility with listeners written for the original event system.

Parameters:
delta - the OAST delta representing the change
Method Detail

isRemove

public boolean isRemove()
Indicates if this event represents a node removal. Note that isRemove() and isInsert() are not mutually exclusive.

Returns:
true if this event indicates one or more nodes being removed, false if not

isInsert

public boolean isInsert()
Indicates if this event represents a node insertion. Note that isInsert() and isRemove() are not mutually exclusive.

Returns:
true if this event indicates one or more nodes being inserted, false if not

isReplace

public boolean isReplace()
Indicates if this event represents a node replacement. This is a convenience method, fully equivalent to isRemove() && isInsert()

Returns:
true if this event indiciates both a removal and an insertion of nodes, false if it is only one or the other.

getOWLAbstractSyntaxTree

public IOWLAbstractSyntaxTree getOWLAbstractSyntaxTree()
Retrieves the OWL abstract syntax tree affected by this event.

Returns:
The affected OAST

getRemoved

public OASTNode[] getRemoved()
Deprecated. As of SWeDE 2.0.0, use getCount(), getRemoved(int), and getInserted(int) instead. These methods allow you to properly capture the sequence of top-level removes and inserts represented by this events. If this sequence of events is unimportant, considering using getDelta() instead.

Retrieves the node(s) being removed. This may be an empty array.

Returns:
The array of nodes being removed

getInserted

public OASTNode[] getInserted()
Deprecated. As of SWeDE 2.0.0, use getCount(), getRemoved(int), and getInserted(int) instead. These methods allow you to properly capture the sequence of top-level removes and inserts represented by this event. If this sequence of events is unimportant, considering using getDelta() instead.

Retrieves the node(s) being inserted. This may be an empty array.

Returns:
The array of nodes being inserted

getCount

public int getCount()
Returns the number of individual events represented by this object. If this is not a composite event, the count will be 1.

Returns:
The number of individual events included in this composite.

getRemoved

public OASTEvent.OASTNodeRef[] getRemoved(int iEvent)
Retrieves the removed nodes array for a specific discrete event encapsulated by this composite event.

Parameters:
iEvent - The event index of the removed array to retrieve. Must be nonnegative and less than getCount().
Returns:
The requested event's removed node array.

getInserted

public OASTEvent.OASTNodeRef[] getInserted(int iEvent)
Retrieves the inserted nodes array for a specific discrete event encapsulated by this composite event.

Parameters:
iEvent - The event index of the inserted array to retrieve. Must be nonnegative and less than getCount().
Returns:
The requested event's inserted node array.

getDelta

public IOASTDelta getDelta()
Retrieves the OAST delta containing detailed information about the changes involved in this event. This will always be a DESCENDANT delta representing the OAST's DocumentRoot node, with specific node changes represented by a tree of deltas below it.

Returns:
the event's OAST delta

setTextEvent

void setTextEvent(boolean bTextEvent)
Sets whether or not this is a text event. By default, events are assumed not to be text events.

Parameters:
bTextEvent - true to mark this as a text event, false to mark this as a non-text event.

isTextEvent

public boolean isTextEvent()

Indicates whether or not this is a text event. A text event is one that resulted from parsing text in the document. Non-text events result from using the OASTNode interface to manipulate nodes in memory.

This flag is intended primarily for use by the OWL editor, which must distinguish between text and non-text events to correctly update the document when the OAST is modified indirectly.

Returns:
true if this is a text event, false if it is a non-text event.

combine

void combine(OASTEvent other)

Turns this event into a composite event. The event being merged with this one is assumed to have occured later, and may be either a standalone event or a composite one. The inserted and removed arrays from the second event will be appended to the insert and remove lists of this one. This event's delta will be updated to reflect the composite change represented by both events.

Events should only be combined internally by an OWL abstract syntax tree during pre-event processing and while dealing with an OAST runnable.

Parameters:
other - The new event to merge into this one.

getDelta

public IOASTDelta getDelta(OASTNode node)
Searches the delta tree for a delta representing a change in a specific OAST node.

Parameters:
node - The node that existed in the OAST prior to the event
Returns:
A delta indicating the change to node, or null if node is unchanged.

setPrimaryNode

void setPrimaryNode(OASTNode node)

Marks a node as the primary focus of the event. The primary node is considered to be the main purpose of a composite event, even though it may include changes to other parts of the document structure. For example, you may use a composite event to update the namespace declarations to include some additional URIs and then add a tag structure to the document that uses the inserted namespaces. Setting the tag structure as the primary node allows SWeDE to correctly treat it as the focus of the event.

Setting a primary node for an event is optional, and different OAST change listeners may react differently to the presence of one. The OWL source editor, for example, checks for and selects the primary node after formatting the text inserted by the event.

The primary node will be updated automatically if it is changed, replaced, or removed by another event that is combined with this one.

Parameters:
node - The primary node for the event. This node must have a corresponding delta in this event.

getPrimaryNode

public OASTNode getPrimaryNode()

Retrieves the node that is the primary focus of this event. The primary node is considered to be the main purpose of a composite event, even though it may include changes to other parts of the document structure. For example, in a composite event that update the namespace declarations to include some additional URIs and then adds a tag structure to the document that uses the inserted namespaces, the inserted tag structure might be marked as primary so that it can correctly be treated as the focus of the event.

Not all events will have a primary node. OAST change listeners should generally process the entire event delta and use the primary node only for UI cues. For example, the OWL editor checks for a primary node and selects its text after formatting the text inserted by an API event.

Returns:
The primary node for the event, or null if the event has no primary node.


Copyright © 2004-2005 BBN Technologies. All Rights Reserved.