Source Code Cross Referenced for DTMIterator.java in  » XML » xalan » org » apache » xml » dtm » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » XML » xalan » org.apache.xml.dtm 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        /*
002:         * Copyright 1999-2004 The Apache Software Foundation.
003:         *
004:         * Licensed under the Apache License, Version 2.0 (the "License");
005:         * you may not use this file except in compliance with the License.
006:         * You may obtain a copy of the License at
007:         *
008:         *     http://www.apache.org/licenses/LICENSE-2.0
009:         *
010:         * Unless required by applicable law or agreed to in writing, software
011:         * distributed under the License is distributed on an "AS IS" BASIS,
012:         * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013:         * See the License for the specific language governing permissions and
014:         * limitations under the License.
015:         */
016:        /*
017:         * $Id: DTMIterator.java,v 1.7 2004/02/16 23:03:44 minchau Exp $
018:         */
019:        package org.apache.xml.dtm;
020:
021:        /**
022:
023:         * <code>DTMIterators</code> are used to step through a (possibly
024:         * filtered) set of nodes.  Their API is modeled largely after the DOM
025:         * NodeIterator.
026:         * 
027:         * <p>A DTMIterator is a somewhat unusual type of iterator, in that it 
028:         * can serve both single node iteration and random access.</p>
029:         * 
030:         * <p>The DTMIterator's traversal semantics, i.e. how it walks the tree,
031:         * are specified when it is created, possibly and probably by an XPath
032:         * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or 
033:         * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.</p>
034:         * 
035:         * <p>A DTMIterator is meant to be created once as a master static object, and 
036:         * then cloned many times for runtime use.  Or the master object itself may 
037:         * be used for simpler use cases.</p>
038:         *
039:         * <p>At this time, we do not expect DTMIterator to emulate
040:         * NodeIterator's "maintain relative position" semantics under
041:         * document mutation.  It's likely to respond more like the
042:         * TreeWalker's "current node" semantics. However, since the base DTM
043:         * is immutable, this issue currently makes no practical
044:         * difference.</p>
045:         *
046:         * <p>State: In progress!!</p> */
047:        public interface DTMIterator {
048:
049:            // Constants returned by acceptNode, borrowed from the DOM Traversal chapter
050:            // %REVIEW% Should we explicitly initialize them from, eg,
051:            // org.w3c.dom.traversal.NodeFilter.FILTER_ACCEPT?
052:
053:            /**
054:             * Accept the node.
055:             */
056:            public static final short FILTER_ACCEPT = 1;
057:
058:            /**
059:             * Reject the node. Same behavior as FILTER_SKIP. (In the DOM these
060:             * differ when applied to a TreeWalker but have the same result when
061:             * applied to a NodeIterator).
062:             */
063:            public static final short FILTER_REJECT = 2;
064:
065:            /**
066:             * Skip this single node. 
067:             */
068:            public static final short FILTER_SKIP = 3;
069:
070:            /**
071:             * Get an instance of a DTM that "owns" a node handle.  Since a node 
072:             * iterator may be passed without a DTMManager, this allows the 
073:             * caller to easily get the DTM using just the iterator.
074:             *
075:             * @param nodeHandle the nodeHandle.
076:             *
077:             * @return a non-null DTM reference.
078:             */
079:            public DTM getDTM(int nodeHandle);
080:
081:            /**
082:             * Get an instance of the DTMManager.  Since a node 
083:             * iterator may be passed without a DTMManager, this allows the 
084:             * caller to easily get the DTMManager using just the iterator.
085:             *
086:             * @return a non-null DTMManager reference.
087:             */
088:            public DTMManager getDTMManager();
089:
090:            /**
091:             * The root node of the <code>DTMIterator</code>, as specified when it
092:             * was created.  Note the root node is not the root node of the 
093:             * document tree, but the context node from where the iteration 
094:             * begins and ends.
095:             *
096:             * @return nodeHandle int Handle of the context node.
097:             */
098:            public int getRoot();
099:
100:            /**
101:             * Reset the root node of the <code>DTMIterator</code>, overriding
102:             * the value specified when it was created.  Note the root node is
103:             * not the root node of the document tree, but the context node from
104:             * where the iteration begins.
105:             *
106:             * @param nodeHandle int Handle of the context node.
107:             * @param environment The environment object.  
108:             * The environment in which this iterator operates, which should provide:
109:             * <ul>
110:             * <li>a node (the context node... same value as "root" defined below) </li>
111:             * <li>a pair of non-zero positive integers (the context position and the context size) </li>
112:             * <li>a set of variable bindings </li>
113:             * <li>a function library </li>
114:             * <li>the set of namespace declarations in scope for the expression.</li>
115:             * <ul>
116:             * 
117:             * <p>At this time the exact implementation of this environment is application 
118:             * dependent.  Probably a proper interface will be created fairly soon.</p>
119:             * 
120:             */
121:            public void setRoot(int nodeHandle, Object environment);
122:
123:            /**
124:             * Reset the iterator to the start. After resetting, the next node returned
125:             * will be the root node -- or, if that's filtered out, the first node
126:             * within the root's subtree which is _not_ skipped by the filters.
127:             */
128:            public void reset();
129:
130:            /**
131:             * This attribute determines which node types are presented via the
132:             * iterator. The available set of constants is defined above.  
133:             * Nodes not accepted by
134:             * <code>whatToShow</code> will be skipped, but their children may still
135:             * be considered.
136:             *
137:             * @return one of the SHOW_XXX constants, or several ORed together.
138:             */
139:            public int getWhatToShow();
140:
141:            /**
142:             * <p>The value of this flag determines whether the children of entity
143:             * reference nodes are visible to the iterator. If false, they  and
144:             * their descendants will be rejected. Note that this rejection takes
145:             * precedence over <code>whatToShow</code> and the filter. </p>
146:             * 
147:             * <p> To produce a view of the document that has entity references
148:             * expanded and does not expose the entity reference node itself, use
149:             * the <code>whatToShow</code> flags to hide the entity reference node
150:             * and set <code>expandEntityReferences</code> to true when creating the
151:             * iterator. To produce a view of the document that has entity reference
152:             * nodes but no entity expansion, use the <code>whatToShow</code> flags
153:             * to show the entity reference node and set
154:             * <code>expandEntityReferences</code> to false.</p>
155:             *
156:             * <p>NOTE: In Xalan's use of DTM we will generally have fully expanded
157:             * entity references when the document tree was built, and thus this
158:             * flag will have no effect.</p>
159:             *
160:             * @return true if entity references will be expanded.  */
161:            public boolean getExpandEntityReferences();
162:
163:            /**
164:             * Returns the next node in the set and advances the position of the
165:             * iterator in the set. After a <code>DTMIterator</code> has setRoot called,
166:             * the first call to <code>nextNode()</code> returns that root or (if it
167:             * is rejected by the filters) the first node within its subtree which is
168:             * not filtered out.
169:             * @return The next node handle in the set being iterated over, or
170:             *  <code>DTM.NULL</code> if there are no more members in that set.
171:             */
172:            public int nextNode();
173:
174:            /**
175:             * Returns the previous node in the set and moves the position of the
176:             * <code>DTMIterator</code> backwards in the set.
177:             * @return The previous node handle in the set being iterated over,
178:             *   or <code>DTM.NULL</code> if there are no more members in that set.
179:             */
180:            public int previousNode();
181:
182:            /**
183:             * Detaches the <code>DTMIterator</code> from the set which it iterated
184:             * over, releasing any computational resources and placing the iterator
185:             * in the INVALID state. After <code>detach</code> has been invoked,
186:             * calls to <code>nextNode</code> or <code>previousNode</code> will
187:             * raise a runtime exception.
188:             */
189:            public void detach();
190:
191:            /**
192:             * Specify if it's OK for detach to release the iterator for reuse.
193:             * 
194:             * @param allowRelease true if it is OK for detach to release this iterator 
195:             * for pooling.
196:             */
197:            public void allowDetachToRelease(boolean allowRelease);
198:
199:            /**
200:             * Get the current node in the iterator. Note that this differs from
201:             * the DOM's NodeIterator, where the current position lies between two
202:             * nodes (as part of the maintain-relative-position semantic).
203:             *
204:             * @return The current node handle, or -1.
205:             */
206:            public int getCurrentNode();
207:
208:            /**
209:             * Tells if this NodeSetDTM is "fresh", in other words, if
210:             * the first nextNode() that is called will return the
211:             * first node in the set.
212:             *
213:             * @return true if the iteration of this list has not yet begun.
214:             */
215:            public boolean isFresh();
216:
217:            //========= Random Access ==========
218:
219:            /**
220:             * If setShouldCacheNodes(true) is called, then nodes will
221:             * be cached, enabling random access, and giving the ability to do 
222:             * sorts and the like.  They are not cached by default.
223:             *
224:             * %REVIEW% Shouldn't the other random-access methods throw an exception
225:             * if they're called on a DTMIterator with this flag set false?
226:             *
227:             * @param b true if the nodes should be cached.
228:             */
229:            public void setShouldCacheNodes(boolean b);
230:
231:            /**
232:             * Tells if this iterator can have nodes added to it or set via 
233:             * the <code>setItem(int node, int index)</code> method.
234:             * 
235:             * @return True if the nodelist can be mutated.
236:             */
237:            public boolean isMutable();
238:
239:            /** Get the current position within the cached list, which is one
240:             * less than the next nextNode() call will retrieve.  i.e. if you
241:             * call getCurrentPos() and the return is 0, the next fetch will
242:             * take place at index 1.
243:             *
244:             * @return The position of the iteration.
245:             */
246:            public int getCurrentPos();
247:
248:            /**
249:             * If an index is requested, NodeSetDTM will call this method
250:             * to run the iterator to the index.  By default this sets
251:             * m_next to the index.  If the index argument is -1, this
252:             * signals that the iterator should be run to the end and
253:             * completely fill the cache.
254:             *
255:             * @param index The index to run to, or -1 if the iterator should be run
256:             *              to the end.
257:             */
258:            public void runTo(int index);
259:
260:            /**
261:             * Set the current position in the node set.
262:             * 
263:             * @param i Must be a valid index.
264:             */
265:            public void setCurrentPos(int i);
266:
267:            /**
268:             * Returns the <code>node handle</code> of an item in the collection. If
269:             * <code>index</code> is greater than or equal to the number of nodes in
270:             * the list, this returns <code>null</code>.
271:             *
272:             * @param index of the item.
273:             * @return The node handle at the <code>index</code>th position in the
274:             *   <code>DTMIterator</code>, or <code>-1</code> if that is not a valid
275:             *   index.
276:             */
277:            public int item(int index);
278:
279:            /**
280:             * Sets the node at the specified index of this vector to be the
281:             * specified node. The previous component at that position is discarded.
282:             *
283:             * <p>The index must be a value greater than or equal to 0 and less
284:             * than the current size of the vector.  
285:             * The iterator must be in cached mode.</p>
286:             * 
287:             * <p>Meant to be used for sorted iterators.</p>
288:             *
289:             * @param node Node to set
290:             * @param index Index of where to set the node
291:             */
292:            public void setItem(int node, int index);
293:
294:            /**
295:             * The number of nodes in the list. The range of valid child node indices
296:             * is 0 to <code>length-1</code> inclusive. Note that this requires running
297:             * the iterator to completion, and presumably filling the cache.
298:             *
299:             * @return The number of nodes in the list.
300:             */
301:            public int getLength();
302:
303:            //=========== Cloning operations. ============
304:
305:            /**
306:             * Get a cloned Iterator that is reset to the start of the iteration.
307:             *
308:             * @return A clone of this iteration that has been reset.
309:             *
310:             * @throws CloneNotSupportedException
311:             */
312:            public DTMIterator cloneWithReset()
313:                    throws CloneNotSupportedException;
314:
315:            /**
316:             * Get a clone of this iterator, but don't reset the iteration in the 
317:             * process, so that it may be used from the current position.
318:             *
319:             * @return A clone of this object.
320:             *
321:             * @throws CloneNotSupportedException
322:             */
323:            public Object clone() throws CloneNotSupportedException;
324:
325:            /**
326:             * Returns true if all the nodes in the iteration well be returned in document 
327:             * order.
328:             * 
329:             * @return true if all the nodes in the iteration well be returned in document 
330:             * order.
331:             */
332:            public boolean isDocOrdered();
333:
334:            /**
335:             * Returns the axis being iterated, if it is known.
336:             * 
337:             * @return Axis.CHILD, etc., or -1 if the axis is not known or is of multiple 
338:             * types.
339:             */
340:            public int getAxis();
341:
342:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.