View Javadoc

1   /*
2    * $Id: IOASTDelta.java,v 1.5 2005/06/01 17:38:38 jlerner Exp $
3    *
4    * Copyright (c) 1999-2004, BBN Technologies, LLC.
5    * All rights reserved.
6    * http://www.daml.org/legal/opensource/bbn_license.html
7    */
8    
9   package com.bbn.swede.core.dom;
10  
11  /***
12   * Represents changes to a document's OWL abstract syntax tree between two 
13   * discrete points in time.  Only structural changes are considered when
14   * computing OAST deltas.  Position and length adjustments always affect the 
15   * tree as a whole, so components that rely upon stored offsets should always
16   * do a full refresh when the OAST changes to ensure accuracy.  
17   * @author jlerner
18   */
19  public interface IOASTDelta
20  {
21     /***
22      * Change constant (bit mask) indicating that the node has been inserted as
23      * a child of its parent.
24      */
25     int INSERTED = 1;
26     /***
27      * Change constant (bit mask) indicating that the node has been removed as
28      * a child of its parent.
29      */
30     int REMOVED = 2;
31     /***
32      * Change constant (bit mask) indicating that the node has been changed.
33      * This value only applies to TextNodes and AttributeNodes.
34      */
35     int CHANGED = 4;
36     /***
37      * Change constant (bit mask) indicating that the node has been replaced with
38      * another node of the same type.  This usually indicates that a portion of
39      * the document was reparsed without major structural changes.
40      */
41     int REPLACED = 8;
42     /***
43      * Change constant (bit mask) indicating that there are changes below the
44      * node in the tree. 
45      */
46     int DESCENDANT = 16;
47     
48     /***
49      * Retrieves the node that was in the tree before the event that created
50      * this delta.  There is no before node for <code>INSERTED</code> or 
51      * <code>DESCENDANT</code> deltas.
52      * @return The node as it existed before the event, or <code>null</code> if
53      *         this is not applicable for the delta's type.
54      */
55     
56     OASTNode getNodeBefore();
57     /***
58      * Retrieves the node that is in the tree after the event that created
59      * this delta.  There is no after node for <code>REMOVED</code> deltas.
60      * @return The node as it exists after the event, or <code>null</code> if
61      *         this is not applicable for the delta's type.
62      */
63     OASTNode getNodeAfter();
64     
65     /***
66      * Returns the type of this OAST delta.  The type will be one of 
67      * <code>INSERTED</code>, <code>REMOVED</code>, <code>CHANGED</code>, 
68      * <code>REPLACED</code>, or <code>DESCENDANT</code>.
69      * @return the type of this OAST delta
70      */
71     int getType();
72     
73     /***
74      * Begins a preorder traversal starting with this delta.  The visitor's
75      * <code>visit</code> method will be called for this resource delta and, if
76      * it returns <code>true</code>, on this delta's children.
77      * @param visitor The visitor to use for the traversal.
78      */
79     void accept(IOASTDeltaVisitor visitor);
80     //TODO: additional accept method to automagically filter against node types?
81     //      This would be really nice, but would require a major restructuring
82     //      of OASTNode to allow node types to be built into type masks.
83     
84     /***
85      * <p>Returns OAST deltas for all children of this node which were inserted,
86      * removed, replaced, or changed.</p>
87      * 
88      * <p>This is a convenience method, fully equivalent to:
89      * <blockquote>getChildren(INSERTED | REMOVED | CHANGED | DESCENDANT)
90      * </blockquote></p>
91      * @return the OAST deltas for all child nodes, or an empty array if no
92      *         children were modified.
93      */
94     IOASTDelta[] getChildren();
95     
96     /***
97      * Returns OAST deltas for all children of this node whose type matches the
98      * specified mask.
99      * @param typeMask a type mask formed by a bitwise OR of IOASTDelta type 
100     *                 constants
101     * @return the OAST deltas for all child nodes matching <code>typeMask</code>,
102     *         or an empty array if no children match.
103     */
104    IOASTDelta[] getChildren(int typeMask);
105    
106    /***
107     * Searches the delta tree rooted at this delta for all changes matching
108     * a particular type mask.
109     * @param typeMask The type mask.
110     * @return An array containing all deltas matching <code>typeMask</code>.
111     */
112    IOASTDelta[] getDeltas(int typeMask);
113    
114    /***
115     * Indicates whether the delta's type matches a specified mask.
116     * @param typeMask The type mask.
117     * @return <code>true</code> if this delta's type matches 
118     *         <code>typeMask</code>, <code>false</code> if not.
119     */
120    boolean typeMatches(int typeMask);
121 }