Source code: javax/ide/model/java/source/tree/Tree.java
1 /*
2 * @(#)Tree.java
3 */
4
5 package javax.ide.model.java.source.tree;
6
7 import java.util.List;
8 import java.util.ListIterator;
9 import javax.ide.model.java.source.util.SourcePosition;
10 import javax.ide.model.java.source.util.TreeTraversal;
11 import javax.ide.model.java.source.util.TreeVisitor;
12
13 /**
14 * Base supertype of all AST nodes in the parse tree. <p/>
15 *
16 * @author Andy Yu
17 * */
18 public interface Tree
19 {
20 // ----------------------------------------------------------------------
21
22 public static final Tree[] EMPTY_ARRAY = new Tree[ 0 ];
23
24
25 // ----------------------------------------------------------------------
26
27 /**
28 * Identifies what kind of Tree this is. <p/>
29 *
30 * @return What kind of Tree this is.
31 */
32 public TreeKind getTreeKind();
33
34 /**
35 * Gets the position of this Tree object.
36 *
37 * @return The position of this Tree object.
38 */
39 public SourcePosition getPosition();
40
41
42 // ----------------------------------------------------------------------
43
44 /**
45 * True if this Tree element corresponds to an actual source
46 * representation. <p/>
47 *
48 * @return True if this Tree element corresponds to an actual source
49 * representation. One example of a synthetic element is the default
50 * constructor generated when a "class" or "enum" declaration does
51 * not declare any constructors. Another example of a synthetic
52 * element is the generated-on-the-fly InterfacesT element returned
53 * by <code>ClassT.getInterfacesClause()</code> when there is no
54 * interfaces declaration.
55 */
56 public boolean isSynthetic();
57
58
59 // ----------------------------------------------------------------------
60
61 /**
62 * Gets the owning FileT.
63 *
64 * @return The owning FileT for this node.
65 */
66 public FileT getOwningFile();
67
68 /**
69 * Gets the parent Tree to this.
70 *
71 * @return The parent of this node.
72 */
73 public Tree getParent();
74
75 /**
76 * Gets the list of children Trees.
77 *
78 * @return The array of non-token children linked to this element. <p/>
79 *
80 * List of Trees.
81 */
82 public List getChildren();
83
84 /**
85 * Gets a ListIterator for this Tree's siblings.
86 *
87 * @return The same behavior as ListIterator. The "this" element
88 * will be returned via an initial call to next(). If the initial
89 * call is prev(), then the previous element will be returned. <p/>
90 *
91 * Note: Unlike ListIterator, next() and previous() will return null
92 * instead of throwing NoSuchElementException's. That allows the client
93 * to safely call getSiblings().previous() and getSiblings().next().
94 */
95 public ListIterator getSiblings();
96
97 /**
98 * Visits this element and its children (as determined by {@link
99 * #getChildren() }).
100 */
101 public void accept(TreeTraversal t);
102
103 /**
104 * Visits this element.
105 */
106 public void accept(TreeVisitor v);
107
108
109 // ----------------------------------------------------------------------
110
111 /**
112 * Gets the sibling before this. <p/>
113 *
114 * This operation currently performs in time proportional to the
115 * number of siblings this element has. That is, this is not a fast
116 * operation.
117 *
118 * @return This element's sibling with an earlier start offset. Null
119 * if none.
120 */
121 public Tree getSiblingBefore();
122
123 /**
124 * Gets the sibling after this. <p/>
125 *
126 * This operation currently performs in time proportional to the
127 * number of siblings this element has. That is, this is not a fast
128 * operation.
129 *
130 * @return This element's sibling with a later start offset. Null if
131 * none.
132 */
133 public Tree getSiblingAfter();
134
135
136 // ----------------------------------------------------------------------
137
138 /**
139 * Performs a deep-copy of this Tree but attached to the input
140 * FileT. If this element has children, then the clone of this
141 * element will have, as its children, clones of this element's
142 * children. <p/>
143 *
144 * Properties are not copied. <p/>
145 *
146 * Cloning a FileT in this manner results in an
147 * UnsupportedOperationException. To clone a FileT, please use
148 * {@link javax.ide.model.java.source.write.TreeManager#cloneSourceFile(FileT,FileT)}. <p/>
149 *
150 * @return An unattached deep-copy of this Tree. "Deep copy" is
151 * explained above. "Unattached" means unparented.
152 *
153 * @throws UnsupportedOperationException if this is a FileT.
154 */
155 public Tree cloneSelf( FileT targetFile );
156
157 /**
158 * Performs an add (usually append) of this element to the parent.
159 * Insertion point is left to the discretion of the implementation.
160 *
161 * @throws UnsupportedOperationException if this element may not
162 * be added.
163 * @throws IllegalStateException if this element already has a
164 * parent.
165 */
166 public void addSelf( Tree parent );
167
168 /**
169 * Performs an add of this element to the parent of the input
170 * sibling.
171 *
172 * @param before If true, this element will be added before the
173 * sibling. If false, this element will be added after the sibling.
174 *
175 * @throws UnsupportedOperationException if addSelf does same.
176 * @throws IllegalStateException if addSelf does same or if sibling
177 * does not have a parent.
178 */
179 public void addSelf( Tree sibling, boolean before );
180
181 /**
182 */
183 public void addSelfBefore( Tree sibling );
184
185 /**
186 */
187 public void addSelfAfter( Tree sibling );
188
189 /**
190 * Performs a set of this element with the newElement.
191 *
192 * @throws UnsupportedOperationException if this element may not
193 * be removed or the new element may not be added.
194 * @throws IllegalStateException if this element does not have a
195 * parent or if the new element already has a parent.
196 */
197 public void replaceSelf( Tree newElement );
198
199 /**
200 * Performs a remove of this element from its parent.
201 *
202 * @throws UnsupportedOperationException if this element may not
203 * be removed.
204 * @throws IllegalStateException if the element does not have a
205 * parent.
206 */
207 public void removeSelf();
208
209
210 // ----------------------------------------------------------------------
211
212 /**
213 * Gets the property saved with the given key, null if none. To prevent
214 * collisions, clients should pick keys that start with the calling
215 * class's {@link java.lang.Class#getName()} value. <p/>
216 *
217 * @return The property of the given type that is stored in this node,
218 * null if none.
219 */
220 public Object getProperty(String key);
221
222 /**
223 * Stores the input property. Overwrites any property stored under the
224 * same key.
225 *
226 * @return The overwritten property, null if none.
227 */
228 public Object setProperty(String key, Object data);
229
230 /**
231 * Nulls out the property stored with the given key.
232 */
233 public void clearProperty(String key);
234
235
236 // ----------------------------------------------------------------------
237 }