com.bbn.swede.core.dom
Class OAST

java.lang.Object
  extended bycom.bbn.swede.core.dom.OAST
All Implemented Interfaces:
IOWLAbstractSyntaxTree

public class OAST
extends Object
implements IOWLAbstractSyntaxTree

This implementation of IOWLAbstractSyntaxTree manages the actual OASTNode structure of the tree. OAST is responsible for parsing (both full and partial), node insertion, removal, and replacement, sending notifications to OAST change listeners, and adapting the tree into a Jena model.

Author:
jlerner

Constructor Summary
OAST()
           
 
Method Summary
 void addOASTChangeListener(IOASTChangeListener ocl)
          Registers a new OASTChangeListener.
 void addPrenotifiedOASTChangeListener(IOASTChangeListener ocl)
          Registers an OASTChangeListener that gets notified of modifications before those registered with addOASTChangeListener.
(package private)  void addToModel(OASTNode node)
          Attempts to add a node to the Jena model.
protected  void attachComments(ArrayList alComments, OASTNode root)
          Attaches a list of already-positioned XMLComment nodes to the OAST.
protected  void changed(OASTEvent event)
          Notifies all OASTChangeListeners that the OAST has just changed.
protected  void createModel()
          Builds a Jena model based on the current state of the OAST.
protected  ArrayList filterComments(StringBuffer sb)
          Locates XML comments in a string.
 String getBaseURI()
          Returns the base URI for the document represented by this OAST.
 OntModel getJenaModel()
          Returns a Jena model representing the OAST.
 IOWLDocument getNamespace(String uri)
          Finds the IOWLDocument corresponding to a namespace URI.
 OASTNode getNode(int offset)
          Finds the lowest-level node in the tree that contains a given offset.
 OASTNode getNode(String sUri)
          Finds a node that represents a specific URI.
protected  OASTNode[] getNodes(int iOffset, int iLength)
          Produces an array of nodes contained in a specific text range.
 String getQNameForURI(String uri)
          Translates full URIs into qualified names based on the namespace abbreviations defined within the document.
 DocumentRoot getRoot()
          Returns the root node of the OAST.
 IRegion[] getUnparseableRegions()
          Produces a list of unparseable regions in the document, as it is currently stored in the project metadata.
 String getURIForQName(String qName)
          Translates qualified names into full URIs based on the namespace abbreviations found within the document.
 boolean hasModel()
          Indicates whether the tree's Jena model has been built.
 void insert(int iOffset, String sText)
          Performs a partial parse on a string of text and inserts the resulting nodes into the tree at a specified offset.
 boolean isReadOnly()
          Indicates whether the tree represents a read-only document.
 List listNamespaces()
          Lists all namespace URIs in the current project.
 void parseDocument(IFile file)
          Parses an entire document into an OWL Abstract Syntax Tree.
 OASTNode partialParse(OASTNode parent, String sText, int iOffset)
          Attempts to parse an XML fragment into a node structure.
 void persistUnparseability()
          Saves a snapshot of which the document's unparseable regions to the project metadata.
 void reload()
          Reparses the entire document from the file and the unparseability state state stored in the metadata.
 void remove(int iOffset, int iLength)
          Remove a range of nodes from the abstract syntax tree.
 OASTNode remove(OASTNode node)
          Deprecated. As of SWeDE 2.0.0, use OASTNode.remove(OASTNode, boolean) instead. The OAST class's edit operations are now intended exclusively for internal use by the editor and related classes.
(package private)  void removeFromModel(OASTNode node)
          Removes a node and all its descendents from the Jena model.
 void removeOASTChangeListener(IOASTChangeListener ocl)
          Unregisters an OASTChangeListener.
 void removePrenotifiedOASTChangelistener(IOASTChangeListener ocl)
          Unregisters a prenotified OASTChangeListener.
 void replace(int iOffset, int iLength, OASTNode dummy)
          Replaces a range of nodes in the syntax tree with any number of new nodes in a specified ArrayList.
 void replace(int iOffset, int iLength, String sText)
          Replaces a range of nodes in the syntax tree with one or more new nodes constructed by performing a partial reparse on some new text.
 void replace(OASTNode nodeReplace, String sText)
          Deprecated. As of SWeDE 1.0.2, use replace(OASTNode, String, int, int) to automatically filter out unparseable subregions of the node being replaced.
 void replace(OASTNode nodeReplace, String sText, int iOffset, int iNewLength)
          Replaces a node in the syntax tree with a new one constructed by performing a partial reparse on some new text.
 void run(IOASTRunnable action)
          Runs the given action as an atomic OWL abstract syntax tree operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OAST

public OAST()
Method Detail

getRoot

public DocumentRoot getRoot()
Returns the root node of the OAST.

Specified by:
getRoot in interface IOWLAbstractSyntaxTree
Returns:
The root node.

getQNameForURI

public String getQNameForURI(String uri)
Translates full URIs into qualified names based on the namespace abbreviations defined within the document.

Parameters:
uri - The URI to translate
Returns:
If a namespace abbreviation can be found for the URI, or it exists in the default namespace, a qualified name for the URI. Otherwise, the URI itself is returned.

getURIForQName

public String getURIForQName(String qName)
Translates qualified names into full URIs based on the namespace abbreviations found within the document.

Parameters:
qName - The qualified name to translate
Returns:
If the namespace abbreviation in the specified qname exists, or if it refers to the default namespace, the full URI. Otherwise, the qualified name itself is returned.

getUnparseableRegions

public IRegion[] getUnparseableRegions()
Produces a list of unparseable regions in the document, as it is currently stored in the project metadata. For information on unparseability in the current, possibly unsaved, document state, use getNodesOfType(OASTNode.UNPARSEABLE)

Returns:
An array of IRegions representing all the unparseable sections of the document

filterComments

protected ArrayList filterComments(StringBuffer sb)
Locates XML comments in a string. The comments will be blanked out in the string and returend as XMLComment objects specifying the positions where they were found.

Parameters:
sb - The StringBuffer to be cleansed of XML comments
Returns:
An ArrayList of positioned XMLComments with correct offsets and lengths that are not attached to the tree

attachComments

protected void attachComments(ArrayList alComments,
                              OASTNode root)
Attaches a list of already-positioned XMLComment nodes to the OAST.

Parameters:
alComments - The list of XMLComments to attach
root - Root of the tree that will receive the comments

parseDocument

public void parseDocument(IFile file)
Parses an entire document into an OWL Abstract Syntax Tree. If this instance of OAST already contains a tree, it will be replaced with the results of the parse

Parameters:
file - File to be parsed

isReadOnly

public boolean isReadOnly()
Description copied from interface: IOWLAbstractSyntaxTree
Indicates whether the tree represents a read-only document. A read-only OAST cannot be modified with the OAST API. An OASTException will be thrown by any API method that is called on a read-only OAST.

Specified by:
isReadOnly in interface IOWLAbstractSyntaxTree
Returns:
true if the OAST is read-only, false if it can be modified.

createModel

protected void createModel()
Builds a Jena model based on the current state of the OAST. This method should only be called when something actually requests the model, as it may take some time to build it.


addToModel

void addToModel(OASTNode node)
Attempts to add a node to the Jena model. This means either creating a Resource (for subclasses of ClassNode) or a statement (for GenericAttribute and subclasses of PropertyNode).

Parameters:
node - Node to integrate into the Jena model

removeFromModel

void removeFromModel(OASTNode node)
Removes a node and all its descendents from the Jena model.

Parameters:
node - The node to remove

getJenaModel

public OntModel getJenaModel()
Returns a Jena model representing the OAST. If the model does not already exist, it will be built automatically.

Specified by:
getJenaModel in interface IOWLAbstractSyntaxTree
Returns:
The Jena model for this OAST

getNode

public OASTNode getNode(int offset)
Finds the lowest-level node in the tree that contains a given offset.

Specified by:
getNode in interface IOWLAbstractSyntaxTree
Parameters:
offset - The offset to find
Returns:
The node containing the offset or the document root if no containing node is found

getNode

public OASTNode getNode(String sUri)
Finds a node that represents a specific URI.

Specified by:
getNode in interface IOWLAbstractSyntaxTree
Parameters:
sUri - The URI to find
Returns:
The node that corresponds to the URI, or null if no such node is found

insert

public void insert(int iOffset,
                   String sText)

Performs a partial parse on a string of text and inserts the resulting nodes into the tree at a specified offset. The new node(s) will be parented to the node currently in the OAST at the insertion point and nodes beyond that point will be displaced to accomodate the new items.

This method is not intended for public use.

Parameters:
iOffset - The insert position
sText - Text to parse

replace

public void replace(OASTNode nodeReplace,
                    String sText,
                    int iOffset,
                    int iNewLength)

Replaces a node in the syntax tree with a new one constructed by performing a partial reparse on some new text. The nodes created by the reparse will be positioned in the tree based on the offset and parent of the node being removed.

Unparseable regions within the node being replaced are blanked out to avoid cascading XML errors up the document. The corresponding UnparseableNodes are reattached to the tree after the new text is parsed into the OAST. Preserving individual unparseable regions of text allows XML errors to cascade back down the document if an enclosing node becomes unparseable and is then fixed.

This method is not intended for public use.

Parameters:
nodeReplace - The node to replace
sText - Text to parse into replacement nodes
iOffset - The offset, relative to the document, of the changed text that caused the node replacement
iNewLength - net character change in document. Will be negative if more characters were removed than inserted.

replace

public void replace(OASTNode nodeReplace,
                    String sText)
Deprecated. As of SWeDE 1.0.2, use replace(OASTNode, String, int, int) to automatically filter out unparseable subregions of the node being replaced.

Replaces a node in the syntax tree with a new one constructed by performing a partial reparse on some new text. The nodes created by the reparse will be positioned in the tree based on the offset and parent of the node being removed.

Parameters:
nodeReplace - The node to replace
sText - Text to parse into replacement nodes

replace

public void replace(int iOffset,
                    int iLength,
                    OASTNode dummy)

Replaces a range of nodes in the syntax tree with any number of new nodes in a specified ArrayList. The inserted nodes will be parented to the parent of the first node removed.

This method is not intended for public use.

Parameters:
iOffset - Begin offset of the removal
iLength - Length of the removal
dummy - The dummy parent node resulting from a partial reparse executed outside the OAST. The node itself will be discarded, but its children will be integrated into the tree.

replace

public void replace(int iOffset,
                    int iLength,
                    String sText)

Replaces a range of nodes in the syntax tree with one or more new nodes constructed by performing a partial reparse on some new text. The nodes created by the reparse will be positioned in the tree based on the offset of the remove range and the parent of the first node being removed.

This method is not intended for public use.

Parameters:
iOffset - Begin offset of the removal
iLength - Length of removal
sText - Text to parse into replacement nodes

remove

public OASTNode remove(OASTNode node)
Deprecated. As of SWeDE 2.0.0, use OASTNode.remove(OASTNode, boolean) instead. The OAST class's edit operations are now intended exclusively for internal use by the editor and related classes.

Removes a node from the OAST. The tree will be displaced by an appropriate amount to compensate for the removal.

Parameters:
node - The node to remove
Returns:
The parent of the removed node

remove

public void remove(int iOffset,
                   int iLength)

Remove a range of nodes from the abstract syntax tree. The tree will be displaced to compensate for the removed node(s) as well as surrounding whitespace.

This is a convenience method, fully equivalent to:

replace(iOffset, iLength, "")

This method is not intended for public use.

Parameters:
iOffset - Start offset of the removal. Nodes that start before this offset will not be removed.
iLength - Length of the removal. Nodes that end after iOffset + iLength will not be removed.

getNodes

protected OASTNode[] getNodes(int iOffset,
                              int iLength)
Produces an array of nodes contained in a specific text range. The first complete node found within the range determines the tree level of the search. Only nodes that are both completely contained in the specified range and at the same level in the OAST will be returned.

Parameters:
iOffset - Start offset of the range. Nodes that start before this offset will not be included.
iLength - Length of the range. Nodes that end after iOffset + iLength will not be included.
Returns:
An array of nodes contained in the specified range, all at the same level in the OAST.

partialParse

public OASTNode partialParse(OASTNode parent,
                             String sText,
                             int iOffset)
                      throws IOException

Attempts to parse an XML fragment into a node structure. Any XML prolog information alread stored in the OAST is used to ensure proper XML encoding and entity substitutions. The resulting node(s) are parented to a dummy node which is returned, but are structured based on the type of the supplied parent node. The dummy node will be displaced to start at a supplied document offset. It is up to the caller to create the actual parent/child relationships by calling attachChildren.

This is a convenience method, fully equivalent to:

partialParse(parent, getProlog(iOffset, sText.length()), sText, iOffset)

This method is not intended for public use.

Parameters:
parent - Intended parent node for newly parsed nodes
sText - Text to parse
iOffset - Insertion offset
Returns:
A dummy node whose children represent one or more node structures resulting from the parse.
Throws:
IOException - if an I/O error occurs during the reparse.
See Also:
#attachChildren(OASTNode, OASTNode), #attachChildren(OASTNode[], OASTNode)

getNamespace

public IOWLDocument getNamespace(String uri)
Finds the IOWLDocument corresponding to a namespace URI.

Specified by:
getNamespace in interface IOWLAbstractSyntaxTree
Parameters:
uri - URI of the namespace to locate
Returns:
The IOWLDocument for the specified URI, or null if the project does not contain a document with the specified base URI

getBaseURI

public String getBaseURI()
Returns the base URI for the document represented by this OAST.

Specified by:
getBaseURI in interface IOWLAbstractSyntaxTree
Returns:
The document's base URI

listNamespaces

public List listNamespaces()
Lists all namespace URIs in the current project.

Specified by:
listNamespaces in interface IOWLAbstractSyntaxTree
Returns:
A java.util.List of all known document URIs

persistUnparseability

public void persistUnparseability()
Saves a snapshot of which the document's unparseable regions to the project metadata.


reload

public void reload()

Reparses the entire document from the file and the unparseability state state stored in the metadata. Use this method to revert changes that have been made to the OAST as a result of unsaved changes in the editor.

This method is not intended for public use.


addOASTChangeListener

public void addOASTChangeListener(IOASTChangeListener ocl)
Registers a new OASTChangeListener. Listeners receive notifications after nodes are added or removed from the OAST.

Specified by:
addOASTChangeListener in interface IOWLAbstractSyntaxTree
Parameters:
ocl - The listener to register

removeOASTChangeListener

public void removeOASTChangeListener(IOASTChangeListener ocl)
Unregisters an OASTChangeListener. It will no longer receive OASTChange notifications.

Specified by:
removeOASTChangeListener in interface IOWLAbstractSyntaxTree
Parameters:
ocl - The listener to unregister. If ocl is not registered as an OASTChangeListener, this method does nothing.

addPrenotifiedOASTChangeListener

public void addPrenotifiedOASTChangeListener(IOASTChangeListener ocl)

Registers an OASTChangeListener that gets notified of modifications before those registered with addOASTChangeListener.

This method is not intended for public use.

Parameters:
ocl - The listener to register

removePrenotifiedOASTChangelistener

public void removePrenotifiedOASTChangelistener(IOASTChangeListener ocl)

Unregisters a prenotified OASTChangeListener. It will no longer receive OASTChange notifications.

This method is not intended for public use.

Parameters:
ocl - The listener to unregister. If ocl is not registered as a prenotified OASTChangeListener, this method does nothing.

changed

protected void changed(OASTEvent event)
                throws OASTException
Notifies all OASTChangeListeners that the OAST has just changed.

Parameters:
event - Describes the change that was just made
Throws:
OASTException - if the OAST is locked for modifications.

run

public void run(IOASTRunnable action)
         throws OASTException
Description copied from interface: IOWLAbstractSyntaxTree
Runs the given action as an atomic OWL abstract syntax tree operation. All OAST modifications that occur within the runnable will be combined into a single event so that listeners are only notified once.

Specified by:
run in interface IOWLAbstractSyntaxTree
Parameters:
action - The action to perform.
Throws:
OASTException - if this OAST is read-only and action attempts to modify it

hasModel

public boolean hasModel()
Description copied from interface: IOWLAbstractSyntaxTree
Indicates whether the tree's Jena model has been built.

Specified by:
hasModel in interface IOWLAbstractSyntaxTree
Returns:
true if the tree is maintaining a Jena model, false if it has not been built yet.


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