/*
    * $Id: OAST.java,v 1.100 2005/07/13 18:48:56 jlerner Exp $
    *
    * Copyright (c) 1999-2004, BBN Technologies, LLC.
    * All rights reserved.
    * http://www.daml.org/legal/opensource/bbn_license.html
    */
   
   package com.bbn.swede.core.dom;
  
  import java.io.BufferedInputStream;
  import java.io.IOException;
  import java.io.StringReader;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collections;
  import java.util.Comparator;
  import java.util.Hashtable;
  import java.util.Iterator;
  import java.util.List;
  import java.util.Map;
  import java.util.StringTokenizer;
  
  import javax.xml.parsers.FactoryConfigurationError;
  import javax.xml.parsers.ParserConfigurationException;
  import javax.xml.parsers.SAXParser;
  import javax.xml.parsers.SAXParserFactory;
  
  import org.eclipse.core.resources.IFile;
  import org.eclipse.core.resources.IResource;
  import org.eclipse.core.runtime.CoreException;
  import org.eclipse.core.runtime.QualifiedName;
  import org.eclipse.jface.text.IRegion;
  import org.eclipse.jface.text.Region;
  import org.eclipse.ui.PartInitException;
  import org.xml.sax.InputSource;
  import org.xml.sax.SAXException;
  import org.xml.sax.helpers.DefaultHandler;
  
  import com.bbn.swede.core.IOWLDocument;
  import com.bbn.swede.core.IOWLElement;
  import com.bbn.swede.core.IOWLElementVisitor;
  import com.bbn.swede.core.IOWLProject;
  import com.bbn.swede.core.OWLCore;
  import com.bbn.swede.core.dom.OASTEvent.OASTNodeRef;
  import com.bbn.swede.core.dom.rdf.Rdf;
  import com.bbn.swede.core.resources.SWResourceManager;
  import com.hp.hpl.jena.ontology.OntModel;
  import com.hp.hpl.jena.ontology.OntModelSpec;
  import com.hp.hpl.jena.rdf.model.ModelFactory;
  import com.hp.hpl.jena.rdf.model.Resource;
  import com.hp.hpl.jena.rdf.model.Statement;
  
  /***
   * This implementation of {@link com.bbn.swede.core.dom.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
   */
  public class OAST implements IOWLAbstractSyntaxTree
  {
     private static final String S_UNPARSEABLE = "com.bbn.swede.ui.unparseablemarker";
     private static final QualifiedName QNAME_UNPARSEABLE =
        new QualifiedName("com.bbn.swede.core", "unparseable");
     
     private DocumentRoot _root;
     private ArrayList _alListeners = new ArrayList();
     private ArrayList _alPrenotifiedListeners = new ArrayList();
     private IFile _file;
     private OntModel _model;
     private Map _mapResourceToNode;
     private Map _mapStatementToNode;
  
     /***
      * Returns the root node of the OAST.
      * @return The root node.
      */
     public DocumentRoot getRoot()
     {
        return _root;
     }
     
     /***
      * Translates full URIs into qualified names based on the namespace 
      * abbreviations defined within the document.
      * @param uri The URI to translate
      * @return 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.
      */
     public String getQNameForURI(String uri)
     {
        String toReturn = uri;
        OASTNode[] namespaceNodes = null;
        String temp = null;
        Namespace namespace = null;
        String fragment = null;
       String baseURI = null;
 
       if(uri.indexOf("#") != -1)
       {
          fragment = uri.substring(uri.lastIndexOf("#") + 1);
          baseURI = uri.substring(0, uri.lastIndexOf("#") + 1);
          namespaceNodes = _root.getNodesOfType(OASTNode.NAMESPACE);
          for (int i = 0; i < namespaceNodes.length; i++)
          {
             namespace = (Namespace)namespaceNodes[i];
             if(baseURI.equals(getBaseURI() + "#"))
             {
                toReturn = fragment;
                break;
             }
             else
             {
                if(namespace.getValue().equals(baseURI))
                {
                   temp = namespace.getQName();
                   if(temp.lastIndexOf(":") != -1)
                   {
                      temp = temp.substring(temp.lastIndexOf(":") + 1);
                      toReturn = temp + ":" + fragment;
                   }
                   else
                   {
                      toReturn = fragment;
                   }
                   break;
                }
             }
          }
       }
       
       return toReturn;
    }
    
    /***
     * Translates qualified names into full URIs based on the namespace 
     * abbreviations found within the document.
     * @param qName The qualified name to translate
     * @return 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.
     */
    public String getURIForQName(String qName)
    {
       String toReturn = qName;
       OASTNode[] namespaceNodes = null;
       String temp = null;
       Namespace namespace = null;
       String fragment = null;
       String baseURI = null;
 
       if(qName.indexOf(":") != -1)
       {
          fragment = qName.substring(qName.lastIndexOf(":") + 1);
          baseURI = qName.substring(0, qName.lastIndexOf(":") + 1);
          namespaceNodes = _root.getNodesOfType(OASTNode.NAMESPACE);
          for (int i = 0; i < namespaceNodes.length; i++)
          {
             namespace = (Namespace)namespaceNodes[i];
             temp = namespace.getQName();
             temp = temp.substring(temp.lastIndexOf(":") + 1);
             if(temp.equals(baseURI))
             {
                toReturn = namespace.getValue() + "#" + fragment;
                break;
             }
          }
       }
       if(qName.startsWith("#"))
       {
          toReturn = getBaseURI() + qName;
       }
       
       return toReturn;
    }
 
    /***
     * 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)
     * @return An array of IRegions representing all the unparseable sections
     *         of the document
     */
    public IRegion[] getUnparseableRegions()
    {
       String s = null;
       try
       {
          s = _file.getPersistentProperty(QNAME_UNPARSEABLE);
       }
       catch (CoreException e)
       {
          OWLCore.logWarning(
             OWLCore.getID(),
             "Error retrieving persistant property",
             e);
       }
       if (s == null)
       {
          return new IRegion[0];
       }
       int iOffset, iLength;
       StringTokenizer st = new StringTokenizer(s, " ");
       ArrayList al = new ArrayList();
       while (st.hasMoreTokens())
       {
          iOffset = Integer.parseInt(st.nextToken());
          iLength = Integer.parseInt(st.nextToken());
          al.add(new Region(iOffset, iLength));
       }
       return (IRegion[]) al.toArray(new IRegion[0]);
    }
 
    /***
     * 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.
     * @param sb The StringBuffer to be cleansed of XML comments
     * @return An ArrayList of positioned XMLComments with correct offsets
     *         and lengths that are not attached to the tree
     */
    protected ArrayList filterComments(StringBuffer sb)
    {
       ArrayList al = new ArrayList();
       for (int iPos = sb.toString().indexOf("<!--");
          iPos >= 0;
          iPos = sb.toString().indexOf("<!--"))
       {
          int iEnd = sb.toString().indexOf("-->", iPos + 4);
          if (iEnd < 0)
          {
             return al;
          }
          String s = sb.toString().substring(iPos + 4, iEnd);
          XMLComment xc = new XMLComment(s);
          xc.setOffset(iPos);
          xc.setLength(iEnd - iPos + 3);
          al.add(xc);
          for (int i = iPos; i < iEnd + 3; i++)
          {
             sb.setCharAt(i, ' ');
          }
       }
       return al;
    }
 
    /***
     * Attaches a list of already-positioned XMLComment nodes to the OAST.
     * @param alComments The list of XMLComments to attach
     * @param root Root of the tree that will receive the comments
     */
    protected void attachComments(ArrayList alComments, OASTNode root)
    {
       Iterator it = alComments.iterator();
       while (it.hasNext())
       {
          XMLComment xc = (XMLComment) it.next();
          //TODO: should insert be doing this anyway?
          OASTNode node = root.getContainingChild(xc.getOffset());
          try
          {
             node.insert(xc, false);
          }
          catch (OASTException e) 
          {
             //Do nothing - attachComments only gets called during partial
             //parse, which operates on unattached node structures that won't
             //cause any problems.
          }
       }
    }
    
    private class NodeLevelComparator implements Comparator
    {
       public int compare(Object o1, Object o2)
       {
          if (!(o1 instanceof UnparseableNode)
              || !(o2 instanceof UnparseableNode))
          {
             return 0;
          }
          UnparseableNode u1 = (UnparseableNode)o1;
          UnparseableNode u2 = (UnparseableNode)o2;
          if (u1.getLevel() < u2.getLevel())
          {
             return -1;
          }
          else if (u1.getLevel() > u2.getLevel())
          {
             return 1;
          }
          return 0;
       }
 
       public boolean equals(Object arg0)
       {
          return false;
       }
    }
    
    /***
     * Parses an entire document into an OWL Abstract Syntax Tree.  The result
     * of the parse is returned as a dummy root node, suitable for building
     * an OAST event.
     * @param file The file resource to be parsed
     * @return A dummy node whose children represent one or more node structures 
     *         resulting from the parse, or <code>null</code> if the parse fails.
     */
    private OASTNode doParseDocument(IFile file)
    {
       if (!file.isDerived() && !file.isSynchronized(IResource.DEPTH_ZERO)
          && !file.getWorkspace().isTreeLocked())
       {
          try
          {
             file.refreshLocal(IResource.DEPTH_ZERO, null);
          }
          catch (CoreException e1)
          {
             OWLCore.logWarning(OWLCore.getID(), 
                              "Unable to refresh file resource.", e1);
          }
       }
       SAXParser parser;
       try
       {
          parser = SAXParserFactory.newInstance().newSAXParser();
 
          IRegion[] regions = getUnparseableRegions();
          StringBuffer sb = new StringBuffer();
          BufferedInputStream bis =
             new BufferedInputStream(
                new UnparseableFilterStream(file.getContents(), regions));
          for (int i = bis.read(); i >= 0; i = bis.read())
          {
             sb.append((char) i);
          }
          bis.close();
          OASTNode dummy = partialParse(_root, null, sb.toString(), 0);
          return dummy;
       }
       catch (Exception e)
       {
          OWLCore.logWarning(
             OWLCore.getID(),
             "Unable to parse " + file.getName(),
             e);
          return null;
       }
    }
 
    /***
     * Generates unparseable nodes based on document metadata and attaches them
     * to a node tree.  The tree must already have space for the nodes to be
     * created.
     * @param file The file represented by the node tree
     * @param root The root of the node tree to receive the unparseable nodes
     */
    private void restorePersistedUnparseables(IFile file, OASTNode root)
    {
       IRegion[] regions = getUnparseableRegions();
       //sort the region list by tree level to ensure unparseables within
       //unparseables get attached in the correct order
       Arrays.sort(regions, new Comparator()
       {
          public int compare(Object arg0, Object arg1)
          {
             if (arg0 instanceof IRegion && arg1 instanceof IRegion)
             {
                IRegion r1 = (IRegion)arg0;
                IRegion r2 = (IRegion)arg1;
                if (r1.getOffset() < r2.getOffset())
                {
                   return -1;
                }
                else if (r1.getOffset() > r2.getOffset())
                {
                   return 1;
                }
                else
                {
                   if (r1.getLength() < r2.getLength())
                   {
                      //r2 contains r1 ==> r2 comes first
                      return 1;
                   }
                   else if (r1.getLength() > r2.getLength())
                   {
                      //r1 contains r2 ==> r1 comes first
                      return -1;
                   }
                }
             }
             return 0;
          }
 
          public boolean equals(Object arg0)
          {
             return this.equals(arg0);
          }
       });
       
       try
       {
          //attach stored unparseable nodes to the OAST
          if(file.getRawLocation() != null)
          {
             UnparseableFilterRandomAccessFile ufraf =
                new UnparseableFilterRandomAccessFile(
                   file.getRawLocation().toFile(),
                   "r",
                   regions);
             for (int i = 0; i < regions.length; i++)
             {
                IRegion r = regions[i];
                ufraf.seek(r.getOffset());
                byte[] bytes = new byte[r.getLength()];
                ufraf.readUnfiltered(bytes);
                String sText = new String(bytes);
                OASTNode node = root.getContainingChild(r.getOffset());
                if (node != null && sText != null)
                {
                   UnparseableNode un = new UnparseableNode(sText);
                   un.setOffset(r.getOffset());
                   un.setLength(sText.length());
                   if (!(node instanceof UnparseableNode))
                   {
                      un.createMarker(file);
                   }
                   node.insert(un, false);
 //                  un.attach(this, false);
                   //don't need to displace any nodes - the unparseable regions
                   //of the file were blanked out by the UFS, not just removed,
                   //so things are positioned correctly around them
 
                }
             }
             ufraf.close();
          }
       }
       catch (Exception e)
       {
          OWLCore.logWarning(
             OWLCore.getID(),
             "Unable to restore persisted unparseable regions in " + file.getName(),
             e);
       }
    }
    
    /***
     * 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
     * @param file File to be parsed
     */
    public void parseDocument(IFile file)
    {
       _file = file;
       _root = new DocumentRoot(_file, this);
       OASTNode dummy = doParseDocument(_file);
       _root.setLength(dummy.getLength());
       restorePersistedUnparseables(_file, dummy);
       attachChildren(dummy, _root);
 
       _bReadOnly = file.isReadOnly();
    }
    
    private boolean _bReadOnly;
    
    /*
     *  (non-Javadoc)
     * @see com.bbn.swede.core.dom.IOWLAbstractSyntaxTree#isReadOnly()
     */
    public boolean isReadOnly()
    {
       return _bReadOnly;
    }
 
    /***
     * 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.
     */
    protected void createModel()
    {
      
       _model = ModelFactory.createOntologyModel(OntModelSpec.OWL_MEM, null);
       _mapResourceToNode = new Hashtable();
       _mapStatementToNode = new Hashtable();
       OASTNode[] nodes = _root.getNodesOfType(OASTNode.RDF_RDF, 1);
       if (nodes.length == 0)
       {
          return;
       }
       OASTNode nodeRdf = nodes[0];
       addToModel(nodeRdf);
    }
 
    /***
     * 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).
     * @param node Node to integrate into the Jena model
     */
    /*package*/ void addToModel(OASTNode node)/package-summary/html">class="comment">package*/ void addToModel(OASTNode node)/package-summary.html">/*package*/ void addToModel(OASTNode node)/package-summary.html">class="comment">package*/ void addToModel(OASTNode node)
    {
       if (node instanceof ClassNode)
       {
          ClassNode cn = (ClassNode) node;
          cn.createJenaResource(_model);
          Resource res = cn.getAssociatedResource();
          if (res == null)
          {
             return;
          }
          
          addResource(res, node);
          
          Statement stmt = cn.getImplicitTypeStatement();
          addStatement(stmt, node);
       }
       OASTNode[] children = node.getChildren();
       for (int i = 0; i < children.length; i++)
       {
          addToModel(children[i]);
       }
       if (node instanceof PropertyNode)
       {
          PropertyNode pn = (PropertyNode) node;
          pn.createJenaStatement(_model);
 
          Statement stmt = pn.getAssociatedStatement();
          addStatement(stmt, node);
          
          Resource res = pn.getReification();
          addResource(res, node);
       }
       if (node instanceof GenericAttribute)
       {
          GenericAttribute ga = (GenericAttribute) node;
          ga.createJenaStatement(_model);
 
          Statement stmt = ga.getAssociatedStatement();
          addStatement(stmt, node);
       }
    }
    
    /***
     * Removes a node and all its descendents from the Jena model.
     * @param node The node to remove
     */
    /*package*/ void removeFromModel(OASTNode node)/package-summary/html">class="comment">package*/ void removeFromModel(OASTNode node)/package-summary.html">/*package*/ void removeFromModel(OASTNode node)/package-summary.html">class="comment">package*/ void removeFromModel(OASTNode node)
    {
       ModelCleanupVisitor mcv = new ModelCleanupVisitor(_model,
          _mapResourceToNode, _mapStatementToNode);
       if (node.getParent() instanceof PropertyNode)
       {
          //Cleanup is starting at the object of a statement, so move up one
          //level to ensure that the broken statement is removed.
          node = node.getParent();
       }
       node.accept(mcv);
    }
    
    /***
     * Adds a resource/node pair to the resource map.
     * @param res The resource
     * @param node The node.  Must not be null.
     */
    private void addResource(Resource res, OASTNode node)
    {
       if (res == null)
       {
          return;
       }
       
       List l = (List)_mapResourceToNode.get(res);
       if (l == null)
       {
          l = new ArrayList(1);
          _mapResourceToNode.put(res, l);
       }
       if (!l.contains(node))
       {
          l.add(node);
       }            
    }
    
    /***
     * Adds a statement/node pair to the statement map.
     * @param stmt The statement
     * @param node The node.  Must not be null.
     */
    private void addStatement(Statement stmt, OASTNode node)
    {
       if (stmt == null)
       {
          return;
       }
       
       List l = (List)_mapStatementToNode.get(stmt);
       if (l == null)
       {
          l = new ArrayList(1);
          _mapStatementToNode.put(stmt, l);
       }
       if (!l.contains(node))
       {
          l.add(node);
       }
    }
 
    /***
     * Returns a Jena model representing the OAST.  If the model does not already
     * exist, it will be built automatically. 
     * @return The Jena model for this OAST
     */
    public OntModel getJenaModel()
    {
       if (_model == null)
       {
          createModel();
       }
       return _model;
    }
 
    /***
     * Finds the lowest-level node in the tree that contains a given offset.
     * @param offset The offset to find
     * @return The node containing the offset or the document root if no
     *         containing node is found
     */
    public OASTNode getNode(int offset)
    {
       OASTNode ret = _root.getContainingChild(offset);
       return (ret == null ? _root : ret);
    }
 
    /***
     * Finds a node that represents a specific Jena statement.
     * @param stmt The statement to find
     * @return The node that corresponds to the statement, or null if no such
     *         node is found.
     */
    public OASTNode getNode(Statement stmt)
    {
       if (_model == null)
       {
          createModel();
       }
       
       List l = (List)_mapStatementToNode.get(stmt);
       if (l == null || l.size() == 0)
       {
          return null;
       }
       return (OASTNode)l.get(0);
    }
 
    /***
     * Finds a node that represents a specific Jena resource.
     * @param res The resource to find
     * @return The node that corresponds to the resource, or null if no such
     *         node is found
     */
    public OASTNode getNode(Resource res)
    {
       if (_model == null)
       {
          this.createModel();
       }
       
       List l = (List)_mapResourceToNode.get(res);
       if (l == null || l.size() == 0)
       {
          return null;
       }
       
       return (OASTNode)l.get(0);
    }
 
    /***
     * Finds a node that represents a specific URI.
     * @param sUri The URI to find
     * @return The node that corresponds to the URI, or null if no such node is
     *         found
     */
    public OASTNode getNode(String sUri)
    {
       if (_model == null)
       {
          this.createModel();
       }
       Resource res = _model.getResource(sUri);
       return (getNode(res));
    }
    
    /***
     * <p>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.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @param iOffset The insert position
     * @param sText Text to parse
     */
    public void insert(int iOffset, String sText)
    {
       OASTNode nodeParent = getNode(iOffset);
       if (nodeParent != null && nodeParent.getOffset() == iOffset)
       {
          nodeParent = nodeParent.getParent();
       }
       if (nodeParent == null)
       {
          nodeParent = _root;
       }
       
       try
       {
          String sProlog = getProlog();
          OASTNode dummy = partialParse(nodeParent, sProlog, sText, iOffset);
          createEvent(new OASTNode[0], dummy, nodeParent, iOffset, 0);
       }
       catch (IOException e)
       {
          OWLCore.logError(OWLCore.getID(), "Partial reparse failed", e);
       }
    }
    
    /***
     * A node visitor that will truncate a node and its children so that
     * they exist between a given start and end offset.
     * @author jlerner
     */
    private class NodeTruncationVisitor implements IOASTNodeVisitor
    {
       private int _iStart, _iEnd;
       /***
        * Creates a visitor to truncate nodes starting before or ending after
        * specific offsets.
        * @param iStartOffset The desired start offset.
        * @param iEndOffset The desired end offset.
        */
       public NodeTruncationVisitor(int iStartOffset, int iEndOffset)
       {
          _iStart = iStartOffset;
          _iEnd = iEndOffset;
       }
       
       /* (non-Javadoc)
        * @see com.bbn.swede.core.dom.IOASTNodeVisitor#visit(com.bbn.swede.core.dom.OASTNode)
        */
       public boolean visit(OASTNode node)
       {
          try
          {
             if (_iEnd <= _iStart)
             {
                node.setLength(0);
                node.setOffset(_iStart);
                if (node instanceof TextNode)
                {
                   TextNode tn = (TextNode)node;
                   tn.setText("");
                }
                return true;
             }
             if (node.getOffset() < _iStart)
             {
                int iDiff = _iStart - node.getOffset();
                node.setLength(iDiff);
                node.setOffset(_iStart);
                if (node instanceof TextNode)
                {
                   TextNode tn = (TextNode)node;
                   if (tn.getLength() <= 0)
                   {
                      //The node has been deleted, just clear its text and return
                      tn.setText("");
                      //...but still visit the children so their text also gets
                      //cleared out and they won't be reinserted later
                      return true;
                   }
                   tn.setText(tn.getText().substring(iDiff));
                }
             }
             int iNodeEnd = node.getOffset() + node.getLength(); 
             if (iNodeEnd > _iEnd)
             {
                node.setLength(node.getLength() - (iNodeEnd - _iEnd));
                if (node instanceof TextNode)
                {
                   TextNode tn = (TextNode)node;
                   if (tn.getLength() <= 0)
                   {
                      //The node has been deleted, just clear its text and return
                      tn.setText("");
                      //...but still visit the children so their text also gets
                      //cleared out and they won't be reinserted later
                      return true;
                   }
                   tn.setText(tn.getText().substring(0, tn.getLength()));
                }
             }
             return true;
          }
          catch (OASTException e)
          {
             //Do nothing.  Node truncation is always handled while the node
             //is detached from the tree so there's no risk of read-only 
             //exceptions
             return true;
          }
       }
    }
    
    /***
     * <p>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.</p>
     * 
     * <p>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.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @param nodeReplace The node to replace
     * @param sText Text to parse into replacement nodes
     * @param iOffset The offset, relative to the document, of the changed text 
     *                that caused the node replacement
     * @param iNewLength net character change in document.  Will be negative if
     *                   more characters were removed than inserted.
     */
    public void replace(OASTNode nodeReplace, String sText, int iOffset, 
                        int iNewLength)
    {
       StringBuffer sbText = new StringBuffer(sText);
       ArrayList alUnparseable = new ArrayList(
          Arrays.asList(nodeReplace.getNodesOfType(OASTNode.UNPARSEABLE)));
       if (nodeReplace instanceof UnparseableNode)
       {
          alUnparseable.remove(nodeReplace);
       }
       Iterator it = alUnparseable.iterator();
       while (it.hasNext())
       {
          UnparseableNode node = (UnparseableNode)it.next();
          //Only worry about top-level unparseables
          OASTNode nodeParent = node.getParent();
          if (nodeParent != null && nodeParent != nodeReplace 
              && nodeParent instanceof UnparseableNode)
          {
             continue;
          }
          //detach the node from the tree so it doesn't get displaced again
          //during event processing
          node.detach(false);
          int iStart = node.getOffset();
          int iEnd = iStart + node.getLength();
          if (iNewLength < 0 && iStart >= iOffset 
              && (iStart + iNewLength) < iOffset)
          {
             //Text was deleted, including the beginning of node.
             //Truncate it before blanking anything out in the replace text.
             iStart = iOffset;
             iEnd += iNewLength;
             node.accept(new NodeDisplacementVisitor(iOffset, iNewLength));
             node.accept(new NodeTruncationVisitor(iStart, iEnd));
          }
          else if (iNewLength < 0 && iStart < iOffset 
                   && (iEnd > iOffset && iEnd <= (iOffset - iNewLength)))
          {
             //Text was deleted, including the end of node.
             //Truncate it before blanking anything out in the replace text.
             iEnd = iOffset;
             node.accept(new NodeTruncationVisitor(iStart, iEnd));
          }
          else if (iStart >= iOffset)
          {
             //node occurs after the modification to nodeReplace's text.
             //Displace the node accordingly.
             iStart += iNewLength;
             iEnd += iNewLength;
             node.accept(new NodeDisplacementVisitor(iOffset, iNewLength));
          }
          //TODO: handle the very weird case where text is truncated on both
          //      sides of the deletion, one of the truncated unparseables
          //      becomes a valid literal, it expands to fill available
          //      whitespace, and winds up containing the unparseable.
          //      The "ideal" solution is to make sure at least one of them
          //      remains unparseable and, if so, munge them together into one
          //      node.  How to do this without another potentially costly parse,
          //      I do not know.  Maybe this is a case best left to the syntax
          //      builder.
          iStart -= nodeReplace.getOffset();
          iEnd -= nodeReplace.getOffset();
          for(int i = iStart; i < iEnd; i++)
          {
             sbText.setCharAt(i, ' ');
          }
       }
       
       int iOffsetReplace = nodeReplace.getOffset();
       OASTNode nodeParent = nodeReplace.getParent();
       if (nodeParent == null)
       {
          nodeParent = _root;
       }
       
       //create the nodes that are going to be inserted
       OASTNode dummy;
       try
       {
          //capture XML prolog information so it can be fed to SAX.  This ensures
          //that partial parses are consistent about character encoding and
          //entity substitution.
          String sProlog = getProlog(iOffsetReplace, nodeReplace.getLength());
          dummy = partialParse(nodeParent, sProlog.toString(), sbText.toString(), iOffsetReplace);
          Collections.sort(alUnparseable, new NodeLevelComparator());
          //Make sure the document root doesn't get reparsed, since that would
          //cause improper delta calculations.
          OASTNode[] nodes;
          if (nodeReplace instanceof DocumentRoot)
          {
             nodes = nodeReplace.getChildren();
             //Compensate for whitespace at the document root level.  This
             //could easily be faked later, but better to ensure that the
             //OAST state is accurate when event notifications go out
             createEvent(nodes, dummy, _root, 0, _root.getLength(), alUnparseable);
             return;
          }
          else
          {
             nodes = new OASTNode[]{nodeReplace};
             createEvent(nodes, dummy, nodeParent, alUnparseable);
          }
 
       }
       catch (IOException e)
       {
          OWLCore.logError(OWLCore.getID(), "Partial reparse failed", e);
       }      
 
    }
    /***
     * 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.
     * 
     * @deprecated As of SWeDE 1.0.2, use 
     *             {@link #replace(OASTNode, String, int, int)} to automatically
     *             filter out unparseable subregions of the node being replaced.
     * @param nodeReplace The node to replace
     * @param sText Text to parse into replacement nodes
     */
    public void replace(OASTNode nodeReplace, String sText)
    {
       int iOffset = nodeReplace.getOffset();
       OASTNode nodeParent = nodeReplace.getParent();
       if (nodeParent == null)
       {
          nodeParent = _root;
       }
       
       //create the nodes that are going to be inserted
       OASTNode dummy;
       try
       {
          //capture XML prolog information so it can be fed to SAX.  This ensures
          //that partial parses are consistent about character encoding and
          //entity substitution.
          String sProlog = getProlog(iOffset, nodeReplace.getLength());
          dummy = partialParse(nodeParent, sProlog.toString(), sText, iOffset);
          createEvent(new OASTNode[]{nodeReplace}, dummy, nodeParent, 0, 0);
 
       }
       catch (IOException e)
       {
          OWLCore.logError(OWLCore.getID(), "Partial reparse failed", e);
       }
    }
    
    /***
    * Creates an OAST delta representing a given set of node removals and 
    * insertions.  The correct type of delta will be created depending on 
    * whether the removed or inserted nodes lists are empty.
    * @param nodesRemoved the nodes removed for this event
    * @param dummy disposable node whose children are the nodes being inserted
    * @param parent the parent node for the nodes being inserted
    */
    private IOASTDelta createDelta(OASTNode[] nodesRemoved, OASTNode dummy, OASTNode parent)
    {
       IOASTDelta delta = null;
       OASTNode[] children = dummy.getChildren();
       if (nodesRemoved.length > 0)
       {
          if (children.length > 0)
          {
             delta = OASTDelta.createReparseDelta(nodesRemoved, children);
          }
          else
          {
             delta = OASTDelta.createRemoveDelta(nodesRemoved);
          }
       }
       else if (children.length > 0)
       {
          delta = OASTDelta.createInsertDelta(parent, children);
       }
       return delta;
    }
    /***
     * <p>Creates an OAST change event with corresponding OAST delta.  The correct
     * type of delta will be created depending on whether the removed or
     * inserted nodes lists are empty.  The event is automatically applied to the
     * tree and notifications are sent to all OAST change listeners.</p>
     * 
     * <p>This is a convenience method, fully equivalent to:
     * <blockquote>createEvent(nodesRemoved,dummy,parent,iOffset,iLength,null)
     * </blockquote></p>
     * @param nodesRemoved the nodes removed for this event
     * @param dummy disposable node whose children are the nodes being inserted
     * @param parent the parent node for the nodes being inserted
     * @param iOffset document offset of the event
     * @param iLength number of characters removed in the event
     */
    private void createEvent(OASTNode[] nodesRemoved, OASTNode dummy, 
       OASTNode parent, int iOffset, int iLength)
    {
       createEvent(nodesRemoved, dummy, parent, iOffset, iLength, null);
    }
    
    /***
     * Creates an OAST change event with corresponding OAST delta.  The correct
     * type of delta will be created depending on whether the removed or
     * inserted nodes lists are empty.  The event is automatically applied to the
     * tree and notifications are sent to all OAST change listeners.
     * @param nodesRemoved the nodes removed for this event
     * @param dummy disposable node whose children are the nodes being inserted
     * @param parent the parent node for the nodes being inserted
     * @param iOffset document offset of the event
     * @param iLength number of characters removed in the event
     * @param alUnparseable a list of unparseable nodes that need to be
     *        reattached to the tree after the event is handled
     */
    private void createEvent(OASTNode[] nodesRemoved, OASTNode dummy,
       OASTNode parent, int iOffset, int iLength, ArrayList alUnparseable)
    {
       IOASTDelta delta = createDelta(nodesRemoved, dummy, parent);
       OASTEvent event = (delta == null ? null : new OASTEvent(delta));
       
       if (iOffset >= 0)
       {
          //calculate amount of whitespace to remove
          int iRemove = iLength;
          for (int i = 0; i < nodesRemoved.length; i++)
          {
             iRemove -= nodesRemoved[i].getLength();
          }
          //calculate amount of whitespace to insert
          int iInsert = dummy.getLength();
          OASTNode[] children = dummy.getChildren();
          for (int i = 0; i < children.length; i++)
          {
             iInsert -= (children[i]).getLength();
          }
          
          applyEvent(event, iOffset, iRemove, iInsert, alUnparseable);
       }
       else
       {
          applyEvent(event, iOffset, 0, 0, alUnparseable);
       }
    }
 
    /***
     * Creates an OAST change event with corresponding OAST delta.  The correct
     * type of delta will be created depending on whether the removed or
     * inserted nodes lists are empty.  The event is automatically applied to the
     * tree and notifications are sent to all OAST change listeners.
     * @param nodesRemoved the nodes removed for this event
     * @param dummy disposable node whose children are the nodes being inserted
     * @param parent the parent node for the nodes being inserted
     * @param alUnparseable a list of unparseable nodes that need to be
     *        reattached to the tree after the event is handled
     */
    private void createEvent(OASTNode[] nodesRemoved, OASTNode dummy, 
       OASTNode parent, ArrayList alUnparseable)
    {
       if (nodesRemoved.length > 0)
       {
          int iOffset = nodesRemoved[0].getOffset();
          int iEnd = nodesRemoved[nodesRemoved.length - 1].getOffset()
                     + nodesRemoved[nodesRemoved.length - 1].getLength();
          int iLength = iEnd - iOffset;
          createEvent(nodesRemoved, dummy, parent, iOffset, iLength, alUnparseable);
       }
       else
       {
          IOASTDelta delta = createDelta(nodesRemoved, dummy, parent);
          OASTEvent event = (delta == null ? null : new OASTEvent(delta));
 
          applyEvent(event, alUnparseable);
       }
    }
    
    /***
     * <p>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.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @param iOffset Begin offset of the removal
     * @param iLength Length of the removal
     * @param 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.
     */
    public void replace(int iOffset, int iLength, OASTNode dummy)
    {
       OASTNode[] nodes = getNodes(iOffset, iLength);
       //getNode(iOffset) should be safe if clients are well-behaved about 
       //calling this method.
       OASTNode nodeParent = (nodes.length > 0 ? nodes[0].getParent() 
                                               : getNode(iOffset));
       if (nodeParent == null)
       {
          nodeParent = _root;
       }
       
       createEvent(nodes, dummy, nodeParent, iOffset, iLength);
 
    }
 
    /***
     * <p>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.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @param iOffset Begin offset of the removal
     * @param iLength Length of removal
     * @param sText Text to parse into replacement nodes
     */
    public void replace(int iOffset, int iLength, String sText)
    {
       OASTNode[] nodes = getNodes(iOffset, iLength);
       //getNode(iOffset) should be safe if clients are well-behaved about 
       //calling this method.
       OASTNode nodeParent = (nodes.length > 0 ? nodes[0].getParent() 
                                               : getNode(iOffset));
       if (nodeParent == null)
       {
          nodeParent = _root;
       }
       
       try
       {
          //capture XML prolog information so it can be fed to SAX.  This ensures
          //that partial parses are consistent about character encoding and
          //entity substitution.
          String sProlog = getProlog(iOffset, iLength);
          OASTNode dummy = partialParse(nodeParent, sProlog, sText, iOffset);
          IOASTDelta delta = null;
          createEvent(nodes, dummy, nodeParent, iOffset, iLength);
 
       }
       catch (IOException e)
       {
          OWLCore.logError(OWLCore.getID(), "Partial reparse failed", e);
       }
    }
    
    /***
     * Captures and returns the full XML prolog for the document.  The XML
     * prolog consists of the XML version tag, other processing instructions,
     * and DOCTYPE.
     * @return A string containing the full XML prolog.  This may be an empty
     *         string.
     */
    private String getProlog()
    {
       StringBuffer sbProlog = new StringBuffer();
       OASTNode[] children = _root.getChildren();
       for (int i = 0; i < children.length; i++)
       {
          OASTNode n = children[i];
          if (!(n instanceof TextNode))
          {
             break;
          }
          if (n instanceof ProcessingInstruction //will also detect XMLVersion
              || n instanceof Doctype)
          {
             String s = ((TextNode)n).getText();
             sbProlog.append(s);
          }
       }
       return sbProlog.toString();
    }
    
    /***
     * Captures and returns the XML prolog (processing instructions & DOCTYPE) 
     * for the document, excluding any prolog elements that intersect with a
     * specified range of the text.
     * @param iOffset Begin offset of the ignore region
     * @param iLength Length of the ignore region
     * @return A string containing the non-intersecting portions of the XML prolog
     */
    private String getProlog(int iOffset, int iLength)
    {
       StringBuffer sbProlog = new StringBuffer();
       OASTNode[] children = _root.getChildren();
       for (int i = 0; i < children.length; i++)
       {
          OASTNode n = children[i];
          if (!(n instanceof TextNode))
          {
             break;
          }
          if (n instanceof ProcessingInstruction //will also detect XMLVersion
              || n instanceof Doctype)
          {
             if (n.getOffset() >= iOffset && n.getOffset() < iOffset + iLength)
             {
                continue;
             }
             String s = ((TextNode)n).getText();
             sbProlog.append(s);
          }
       }
       return sbProlog.toString();
       
    }
 
    /***
     * Removes a node from the OAST.  The tree 
     * will be displaced by an appropriate amount to compensate for the removal.
     * 
     * @deprecated As of SWeDE 2.0.0, use 
     *             {@link OASTNode#remove(OASTNode, boolean)} instead.  The OAST
     *             class's edit operations are now intended exclusively for
     *             internal use by the editor and related classes.
     * @param node The node to remove
     * @return The parent of the removed node
     */
    public OASTNode remove(OASTNode node)
    {
       OASTNode parent = node.getParent();
       try
       {
          parent.remove(node, true);
       }
       catch (OASTException e)
       {
          //Do nothing.  This method should no longer be used anyway so the
          //remove can just quietly fail.
       }
 
       return parent;
    }
 
    /***
     * <p>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.</p>
     * 
     * <p>This is a convenience method, fully equivalent to:
     * <blockquote>replace(iOffset, iLength, "")</blockquote></p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @param iOffset Start offset of the removal.  Nodes that start before this
     *                offset will not be removed.
     * @param iLength Length of the removal.  Nodes that end after 
     *                iOffset + iLength will not be removed.
     */
    public void remove(int iOffset, int iLength)
    {
       replace(iOffset, 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.
     * @param iOffset Start offset of the range.  Nodes that start before this
     *                offset will not be included.
     * @param iLength Length of the range.  Nodes that end after 
     *                iOffset + iLength will not be included.
     * @return An array of nodes contained in the specified range, all at the
     *         same level in the OAST.
     */
    protected OASTNode[] getNodes(int iOffset, int iLength)
    {
       OASTNode parent = getNode(iOffset);
       if (parent.getOffset() == iOffset && parent.getLength() < iLength)
       {
          parent = parent.getParent();
       }
       OASTNode[] children = parent.getChildren();
       ArrayList alReturn = new ArrayList();
       if (parent.startsAfter(iOffset) && parent.endsBefore(iOffset + iLength))
       {
          alReturn.add(parent);
       }
       else
       {
          for (int i = 0; i < children.length; i++)
          {
             OASTNode node = children[i];
             if (node.startsAfter(iOffset)
                && node.endsBefore(iOffset + iLength))
             {
                alReturn.add(node);
             }
          }
       }
       OASTNode[] nodes = new OASTNode[alReturn.size()];
       alReturn.toArray(nodes);
       return nodes;
    }
 
 
    /***
     * Helper method for <code>applyEvent()</code>.  Handles node removals for
     * an event, including displacement of the remaining nodes in the tree.
     * @param event The event to apply.  Must be a non-composite event.
     */
    private void removeNodes(OASTEvent event)
    {
       OASTNodeRef[] removed = event.getRemoved(0);
       for (int i = 0; i < removed.length; i++)
       {
          OASTNodeRef nodeRef = removed[i];
          nodeRef.getNode().detach(true);
       }
    }
    
    /***
     * Helper method for <code>applyEvent()</code>.  Handles node insertions for
     * an event, including displacement of the existing nodes in the tree.
     * @param event The event to apply.  Must be a non-composite event.
     */
    private void insertNodes(OASTEvent event)
    {
       OASTNodeRef[] inserted = event.getInserted(0);
       for (int i = 0; i < inserted.length; i++)
       {
          OASTNodeRef nodeRef = inserted[i];
          nodeRef.getNode().attach(this, true);
       }
    }
    
    /***
     * <p>Helper method for <code>applyEvent()</code>.  Performs additional
     * displacement on the tree to compensate for whitespace that was removed
     * and/or inserted that is not included in the length of the removed and
     * inserted nodes.</p>
     * 
     * <p>Additionally, a list of unparseable nodes that will later be reattached
     * to the tree may be specified.  If a non-empty list is provided, the
     * nodes it contains will also be adjusted to compensate for the extra removed
     * and added whitespace.</p>
     * @param iOffset The offset of the document event that caused the OAST event
     * @param iRemoveWhitespace Number of extra whitespace characters removed
     * @param iInsertWhitespace Number of extra whitespace characters inserted
     */
    private void adjustForWhitespace(int iOffset, int iRemoveWhitespace, 
       int iInsertWhitespace)
    {
       if (iRemoveWhitespace > 0)
       {
          _root.accept(new NodeDisplacementVisitor(iOffset, -iRemoveWhitespace));
       }
       if (iInsertWhitespace > 0)
       {
          _root.accept(new NodeDisplacementVisitor(iOffset, iInsertWhitespace));
       }
    }
    
    /***
     * Helper method for <code>applyEvent()</code>.  Reattaches a list of 
     * filtered-out unparseable nodes to the tree after a reparse event has been 
     * applied.
     * @param lUnparseable the list of filtered-out unparseables
     */
    private void reattachUnparseables(List lUnparseable)
    {
       if (lUnparseable == null)
       {
          return;
       }
       Iterator it = lUnparseable.iterator();
       while (it.hasNext())
       {
          UnparseableNode node = (UnparseableNode)it.next();
          //disregard unparseables that contain only whitespace
          //and unparseables whose length became nonpositive as a result of
          //the text modification
          if (node.getText().trim().length() == 0)
          {
             continue;
          }
          node.attach(this, false);
       }      
    }
    
 
    /***
     * Applies an event caused by text modification to the OAST.  This includes
     * detaching removed nodes, displacing the tree to compensate for the event,
     * and attaching inserted nodes, as well as sending event notifications to
     * OAST change listeners.  The event will be flagged as a text event before
     * OAST change notifications are sent out.
     * @param event The OAST event resulting from the text modification.  Must
     *              be a non-composite event.
     * @param alUnparseable list of unparseable nodes to manually attach to the
     *                      tree after applying the event 
     */
    private void applyEvent(OASTEvent event, ArrayList alUnparseable)
    {
       if (event != null)
       {
          event.setTextEvent(true);
          removeNodes(event);
          insertNodes(event);
       }
       reattachUnparseables(alUnparseable);
       if (event != null)
       {
          try
          {
             changed(event);
          }
          catch (OASTException e)
          {
             OWLCore.logError(OWLCore.getID(), "OAST locked during manual text edit.", e);
          }
       }
    }
    
    /***
     * Applies an event caused by text modification to the OAST.  This includes
     * detaching removed nodes, displacing the tree to compensate for the event,
     * and attaching inserted nodes, as well as sending event notifications to
     * OAST change listeners.  The event will be flagged as a text event before
     * OAST change notifications are sent out.
     * @param event The OAST event resulting from the text modification.  Must
     *              be a non-composite event.
     * @param iOffset The offset of the document event that caused the OAST event 
     * @param iRemoveWhitespace Amount of extra whitespace that must be removed
     *                          at the event offset
     * @param iInsertWhitespace Amount of whitespace that must be added at the
     *                       event offset  
     * @param alUnparseable list of unparseable nodes to manually attach to the
     *                      tree after applying the event 
     */
    private void applyEvent(OASTEvent event, int iOffset, int iRemoveWhitespace,
       int iInsertWhitespace, ArrayList alUnparseable)
    {
       if (event != null)
       {
          event.setTextEvent(true);
          removeNodes(event);
       }
       adjustForWhitespace(iOffset, iRemoveWhitespace, iInsertWhitespace);
       if (event != null)
       {
          insertNodes(event);
          reattachUnparseables(alUnparseable);
          try
          {
             changed(event);
          }
          catch (OASTException e)
          {
             OWLCore.logError(OWLCore.getID(), "OAST locked during manual text edit.", e);
          }
       }
    }
 
    /***
     * <p>Attempts to parse an XML fragment into a node structure.  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.  It is up to the caller
     * to position the dummy node's children correctly for insertion in the tree
     * and to create the actual parent/child relationships by calling 
     * attachChildren</p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @deprecated As of SWeDE 2.0.0, use 
     * {@link #partialParse(OASTNode, String, String, int)}.  This version
     * will continue to function as a convenience method for 
     * <code>partialParse(parent,sProlog,sText,0)</code>.
     * @see #attachChildren(OASTNode, OASTNode)
     * @param parent The intended parent node
     * @param sProlog XML prolog information to prepend to the text when SAX
     *                parses it
     * @param sText The new text to parse
     * @return A dummy node whose children represent one or more node structures
     *         resulting from the parse.
     * @throws IOException
     */
    private OASTNode partialParse(OASTNode parent, String sProlog, String sText)
       throws IOException
    {
       return partialParse(parent, sProlog, sText, 0);
    }
 
    /***
     * <p>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 <code>attachChildren</code>.</p>
     * 
     * <p>This is a convenience method, fully equivalent to:
     * <blockquote>partialParse(parent, getProlog(iOffset, sText.length()), 
     * sText, iOffset)</blockquote></p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @see #attachChildren(OASTNode, OASTNode)
     * @see #attachChildren(OASTNode[], OASTNode)
     * @param parent Intended parent node for newly parsed nodes
     * @param sText Text to parse
     * @param iOffset Insertion offset
     * @return 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.
     */
    public OASTNode partialParse(OASTNode parent, String sText, int iOffset)
       throws IOException
    {
       return partialParse(parent, getProlog(iOffset, sText.length()), sText, iOffset);
    }
 
    /***
     * A specialized OAST root, usable as a placeholder root node for partial
     * parses.  DummyRoot differs from DocumentRoot only in its displace 
     * behavior: DocumentRoot nodes always want to maintain a starting offset
     * of 0, so any displacement is handled by lengthening the node.  DummyRoots
     * may start at any offset and so they displace just like other nodes.
     * @author jlerner
     */
    private class DummyRoot extends DocumentRoot
    {
       /***
        * Creates a dummy root representing a portion of a file.
        * @param file The file
        */
       public DummyRoot(IFile file)
       {
          super(file, null);
       }
       
       public boolean displace(int offset, int length)
       {
          return OASTNode.displace(this, offset, length);
       }
    }
    /***
     * <p>Attempts to parse an XML fragment into a node structure.  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 
     * <code>attachChildren</code>.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     * @see #attachChildren(OASTNode, OASTNode)
     * @see #attachChildren(OASTNode[], OASTNode)
     * @param parent The intended parent node
     * @param sProlog XML prolog information to prepend to the text when SAX
     *                parses it
     * @param sText The new text to parse
     * @param iOffset The document offset the dummy node should be displaced to
     * @return A dummy node whose children represent one or more node structures
     *         resulting from the parse.
     * @throws IOException
     */
    private OASTNode partialParse(OASTNode parent, String sProlog, String sText, int iOffset)
       throws IOException
    {
       if (sProlog == null)
       {
          sProlog = "";
       }
       if (parent == null)
       {
          parent = _root;
       }
 
       OASTNode root;
       if (parent instanceof ClassNode)
       {
          root = new GenericPredicate("");
       }
       else if (parent instanceof PropertyNode || parent instanceof Rdf)
       {
          root = new GenericThing("");
       }
       else
       {
          IOWLDocument doc = parent.getOWLDocument();
          IFile file = (IFile) doc.getCorrespondingResource();
          //use DummyRoot rather than DocumentRoot because the result of the
          //partial parse needs to be displacable to a nonzero starting offset
          root = new DummyRoot(file);
       }
       StringBuffer sbText = new StringBuffer(sText);
       ArrayList alComments = filterComments(sbText);
       OASTStringHandler handler =
          new OASTStringHandler(
             root,
             sbText.toString(),
             (parent == _root ? false : true));
       if (sbText.toString().trim().length() == 0)
       {
          if (sText.trim().length() > 0) //Only XML comments were inserted
          {
             root.setLength(sText.length());
             attachComments(alComments, root);
             //there's no root dummy node here, the comments are directly
             //parented to the root
          }
          else //Only whitespace was inserted
          {
             root.setLength(sText.length());
          }
          root.accept(new NodeDisplacementVisitor(0, iOffset));
          return root;
       }
       SAXParser parser;
       try
       {
          parser = SAXParserFactory.newInstance().newSAXParser();
          //Wrapping the new text in a dummy tag ensures that SAX
          //won't freak out about a missing root tag.  In turn , this 
          //ensures proper differentiation between literals and 
          //unparseable nodes, and should allow pasting of multiple 
          //complete node substructures.
          StringReader sr;
          if (parent == _root)
          {
             sr = new StringReader(sProlog + sbText.toString());
          }
          else
          {
             sr = new StringReader(sProlog + "<a>" + sbText.toString() + "</a>");
          }
          InputSource is = new InputSource(sr);
          try
          {
             parser.parse(is, handler);
          }
          catch (Exception e)
          {
             //My code is written against the specification for the SAX parser,
             //which indicates that it will throw a SAX exception if basically
             //anything goes wrong at runtime.  Java 1.5 helpfully violates this
             //by throwing an array index out of bounds exception in response
             //to certain types of malformed XML prologs.  This stupid workaround
             //allows me to handle that case while leaving the rest of my code 
             //intact.
             throw new SAXException(e);
          }
          OASTNode node;
          if (parent != _root)
          {
             node = (OASTNode) root.getChildren()[0]; //the root dummy node
          }
          else
          {
             node = root;
             //detect and attach XML prolog nodes
             OASTNode n = (OASTNode)node.getChildren()[0];
             XMLPrologParser xpp = new XMLPrologParser();
             OASTNode[] nodes = xpp.parse(sbText.toString().substring(0, n.getOffset()));
             attachChildren(nodes, node);
          }
          attachComments(alComments, root);
          node.accept(new NodeDisplacementVisitor(0, iOffset));
          return node;
       }
       catch (SAXException se)
       {
 //       se.printStackTrace();
 //       String sTrimmed = sText.trim();
 //       iOffset += sText.indexOf(sTrimmed);
          if (parent == _root)
          {
             try
             {
                StringReader sr = new StringReader(sbText.toString() + "<a/>");
                SAXParser p = SAXParserFactory.newInstance().newSAXParser();
                p.parse(new InputSource(sr), new DefaultHandler());
                //If we got here, the string must have been a valid XML prolog
                //with no root tag, so we can build a tree for it after all
 
                //alComments already contains nodes for comments found in sText
                //and sbText already has those comments blanked out
                XMLPrologParser xpp = new XMLPrologParser();
                OASTNode[] nodes = xpp.parse(sbText.toString());
                OASTNode dummy = new GenericThing("");
                dummy.setOffset(0);
                dummy.setLength(sbText.toString().length());
                attachChildren(nodes, dummy);
                attachComments(alComments, dummy);
                dummy.accept(new NodeDisplacementVisitor(0, iOffset));
                return dummy;
             }
             catch (SAXException e1)
             {
             }
             catch (ParserConfigurationException e1)
             {
             }
             catch (FactoryConfigurationError e1)
             {
             }
             catch (IOException e1)
             {
             }
          }
          OASTNode dummy = new GenericThing("");
          UnparseableNode un = new UnparseableNode(sText);
          dummy.appendChild(un);
          un.setLength(sText.length());
          dummy.setOffset(un.getOffset());
          dummy.setLength(un.getLength());
          dummy.accept(new NodeDisplacementVisitor(0, iOffset));
          return dummy;
       }
       catch (ParserConfigurationException e)
       {
          OWLCore.logError(
             OWLCore.getID(),
             "SAX creation failed for partial reparse",
             e);
          return null;
       }
       catch (FactoryConfigurationError e)
       {
          OWLCore.logError(
             OWLCore.getID(),
             "SAX creation failed for partial reparse",
             new Exception(e));
          return null;
       }
    }
 
 
    /***
     * Attaches an array of nodes as children of a specified parent.  This
     * method doesn't do any node displacement.  Offsets and lengths should be
     * set before calling attachChildren
     * @param nodes Array of child nodes to attach
     * @param parent Parent to receive the new child nodes
     */
    private void attachChildren(OASTNode[] nodes, OASTNode parent)
    {
       for (int i = 0; i < nodes.length; i++)
       {
          OASTNode n = nodes[i];
          if (parent.getOWLAbstractSyntaxTree() == this)
          {
             //This is only used for parsing so use attach rather than insert
             //so no event is created
             n.attach(this, false);
          }
          else
          {
             try
             {
                parent.insert(n, false);
             }
             catch (OASTException e)
             {
                //If we're parsing text the file should be writable, but log
                //the error in case the impossible happens
                OWLCore.logWarning(OWLCore.getID(), "Unable to attach children during partial parse", e);
             }
          }
       }
 
    }
    
    /***
     * Attaches the children of a given node to a specified parent.  This method
     * doesn't do any node displacement.  Offsets and lengths should be set
     * before calling attachChildren.
     * @param node The node whose children will be attached
     * @param parent Node to act as the parent for the attached children
     */
    private void attachChildren(OASTNode node, OASTNode parent)
    {
       OASTNode[] children = node.getChildren();
       attachChildren(children, parent);
    }
 
    /***
     * Finds the IOWLDocument corresponding to a namespace URI.
     * @param uri URI of the namespace to locate
     * @return The IOWLDocument for the specified URI, or null if the project
     *         does not contain a document with the specified base URI
     */
    public IOWLDocument getNamespace(String uri)
    {
       if (uri == null || uri.length() == 0)
       {
          //assume current document namespace
          return (IOWLDocument) SWResourceManager.getModel().getCorrespondingElement(
             _file);
       }
       IOWLProject proj =
          (IOWLProject) SWResourceManager.getModel().getCorrespondingElement(
             _file.getProject());
       if (uri.endsWith("#"))
       {
          uri = uri.substring(0, uri.length() - 1);
       }
       return proj.getDocument(uri);
    }
    
    /***
     * Returns the base URI for the document represented by this OAST.
     * @return The document's base URI
     */
    public String getBaseURI()
    {
       IOWLDocument doc = getNamespace(null);
       if (doc != null)
       {
          return doc.getURI();
       }
       return "";
    }
 
    /***
     * Lists all namespace URIs in the current project.
     * @return A java.util.List of all known document URIs
     */
    public List listNamespaces()
    {
       IOWLProject proj =
          (IOWLProject) SWResourceManager.getModel().getCorrespondingElement(
             _file.getProject());
       final List l = new ArrayList();
       IOWLElementVisitor ev = new IOWLElementVisitor()
       {
          public boolean visit(IOWLElement element)
          {
             if (element instanceof IOWLDocument)
             {
                IOWLDocument doc = (IOWLDocument) element;
                if (!l.contains(doc.getURI()))
                {
                   l.add(doc.getURI());
                }
             }
             return true;
          }
       };
       proj.accept(ev);
       return l;
    }
 
    /***
     * Saves a snapshot of which the document's unparseable regions to the
     * project metadata.
     */
    public synchronized void persistUnparseability()
    {
       OASTNode[] nodes = _root.getNodesOfType(OASTNode.UNPARSEABLE);
       if (nodes.length == 0)
       {
          try
          {
             _file.setPersistentProperty(QNAME_UNPARSEABLE, null);
          }
          catch (CoreException e)
          {
             OWLCore.logWarning(
                OWLCore.getID(),
                "Unable to set persistent property",
                e);
          }
          return;
       }
       StringBuffer sbUnparseable = new StringBuffer();
       for (int i = 0; i < nodes.length; i++)
       {
          OASTNode node = nodes[i];
          sbUnparseable.append(node.getOffset() + " " + node.getLength() + " ");
       }
       try
       {
          _file.setPersistentProperty(
             QNAME_UNPARSEABLE,
             sbUnparseable.toString());
       }
       catch (CoreException e)
       {
          OWLCore.logWarning(
             OWLCore.getID(),
             "Unable to set persistent property",
             e);
       }
    }
 
    /***
     * <p>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.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * 
     */
    public void reload()
    {
       try
       {
          _file.deleteMarkers(S_UNPARSEABLE, false, IResource.DEPTH_INFINITE);
       }
       catch (CoreException e)
       {
          OWLCore.logWarning(
             OWLCore.getID(),
             "Unable to delete markers for full reparse",
             e);
       }
       OASTNode[] oldNodes = _root.getChildren();
       OASTNode dummy = doParseDocument(_file);
       restorePersistedUnparseables(_file, dummy);
       createEvent(oldNodes, dummy, _root, 0, _root.getLength());
    }
    
    /***
     * Registers a new OASTChangeListener.  Listeners receive notifications
     * after nodes are added or removed from the OAST.
     * @param ocl The listener to register
     */
    public void addOASTChangeListener(IOASTChangeListener ocl)
    {
       _alListeners.add(ocl);
    }
 
    /***
     * Unregisters an OASTChangeListener.  It will no longer receive
     * OASTChange notifications.
     * @param ocl The listener to unregister.  If ocl is not registered as an
     *            OASTChangeListener, this method does nothing.
     */
    public void removeOASTChangeListener(IOASTChangeListener ocl)
    {
       _alListeners.remove(ocl);
    }
    
    /***
     * <p>Registers an OASTChangeListener that gets notified of modifications before
     * those registered with addOASTChangeListener.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * @param ocl The listener to register
     */
    public void addPrenotifiedOASTChangeListener(IOASTChangeListener ocl)
    {
       _alPrenotifiedListeners.add(ocl);
    }
    
    /***
     * <p>Unregisters a prenotified OASTChangeListener.  It will no longer receive
     * OASTChange notifications.</p>
     * 
     * <p>This method is not intended for public use.</p>
     * @param ocl The listener to unregister.  If ocl is not registered as a
     *            prenotified OASTChangeListener, this method does nothing.
     */
    public void removePrenotifiedOASTChangelistener(IOASTChangeListener ocl)
    {
       _alPrenotifiedListeners.remove(ocl);
    }
    
    private void preDispatchEvent(OASTEvent event)
    {
       _bPreLock = true;
       _preEvent = new OASTEvent(event);
       Iterator it = _alPrenotifiedListeners.iterator();
       try
       {
          while (it.hasNext())
          {
             IOASTChangeListener ocl = (IOASTChangeListener)it.next();
             ocl.oastChanged(event);
          }
       }
       finally
       {
          _bPreLock = false;
       }
    }
    private void dispatchEvent(OASTEvent event)
    {
       _bLock = true;
       try
       {
          for (int i = 0; i < _alListeners.size(); i++)
          {
             IOASTChangeListener ocl = (IOASTChangeListener)_alListeners.get(i);
             ocl.oastChanged(event);
          }
       }
       finally
       {
          _bLock = false;
       }
    }
    
    private boolean _bLock;
    private boolean _bPreLock;
    private OASTEvent _preEvent;
    /***
     * Notifies all OASTChangeListeners that the OAST has just changed.
     * @param event Describes the change that was just made
     * @throws OASTException if the OAST is locked for modifications.
     */
    protected synchronized void changed(OASTEvent event) throws OASTException
    {
       if (_bLock)
       {
          throw new OASTException("The OAST is locked for modifications.", this);
       }
       if (_iCollectEvents > 0)
       {
          if (_compositeEvent == null)
          {
             _compositeEvent = event;
          }
          else
          {
             _compositeEvent.combine(event);
          }
          return;
       }
       //prenotified listeners are allowed to cause additional events, which
       //get quietly combined into a copy of the original event.  The resulting
       //composite event is what will ultimately be sent out to ordinary OAST
       //change listeners.  This is required for content formatting to do some 
       //of its adjustemnts to attributes and literals, but it's kind of sketchy
       //and nobody should really use this "feature" except the editor.
       if (_bPreLock)
       {
          _preEvent.combine(event);
          return;
       }
       //Make sure the file is open in an OWL editor to ensure proper
       //updating of the document's text.
       if (!event.isTextEvent())
       {
          IOWLDocument doc = getRoot().getOWLDocument();
          try
          {
             OWLCore.openEditor(doc);
          }
          catch (PartInitException e)
          {
             OWLCore.logError(OWLCore.getID(), "Error opening editor for " + doc.getElementName(), e);
          }
       }
 
       preDispatchEvent(event);
       dispatchEvent(_preEvent);
       _preEvent = null;
    }
 
    private int _iCollectEvents;
    private OASTEvent _compositeEvent;
    /* (non-Javadoc)
     * @see com.bbn.swede.core.dom.IOWLAbstractSyntaxTree#run(com.bbn.swede.core.dom.IOASTRunnable)
     */
    public synchronized void run(IOASTRunnable action) throws OASTException
    {
       _iCollectEvents++;
       try
       {
          action.run();
       }
       finally
       {
          _iCollectEvents--;
          if (_iCollectEvents <= 0 && _compositeEvent != null)
          {
             OASTNode nodePrimary = action.getPrimaryNode();
             _compositeEvent.setPrimaryNode(nodePrimary);
             _iCollectEvents = 0;
             changed(_compositeEvent);
             _compositeEvent = null;
          }
       }
    }
 
 
    /* (non-Javadoc)
     * @see com.bbn.swede.core.dom.IOWLAbstractSyntaxTree#hasModel()
     */
    public boolean hasModel()
    {
       return (_model != null);
    }
 }