Iterator.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2008 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef API_ITERATOR_H
17 #define API_ITERATOR_H
18 
19 /** \brief Interface for an Iterator over an instance of the XML Data Model
20  * (i.e., a sequence of items).
21  *
22  * An iterator can be in one of the following two states: open or not-open.
23  * When in open state, only methods isOpen(), next() and close() may be called.
24  * When in not-open state, only isOpen and open() may be called. The open()
25  * method changes the state from non-open to open, and the close() method
26  * changes the state from open to not-open.
27  *
28  * Note: Iterator is not a thread-safe class, i.e., none of its methods should
29  * ever be called by two or more threads in parallel.
30  *
31  */
32 class Iterator
33 {
34 protected:
35  friend class DynamicContext;
36  friend class DocumentManager;
37  friend class CollectionManager;
38  friend class Collection;
39  friend class StaticContext;
40  friend class XQuery;
41  friend class ItemSequence;
42  zorba::Iterator_t theIterator;
43  zorba::Item theItem;
45 public:
46  // constructors
47  Iterator() {}
48  Iterator(const Iterator& anIterator)
49  : theIterator(anIterator.theIterator),
50  theItem(anIterator.theItem),
51  theConsumed(false)
52  {}
53  Iterator(zorba::Iterator_t anIterator)
54  : theIterator(anIterator),
55  theConsumed(false)
56  {}
57  Iterator(zorba::Item& aItem)
58  : theIterator(0),
59  theItem(aItem),
60  theConsumed(false)
61  {}
62 
63  /** \brief Start iterating.
64  *
65  * This function needs to be called before calling next() or close().
66  * Its purpose is to create and initialize any resources that may be
67  * needed during the iteration. It should not be called again until
68  * after close() has been called.
69  *
70  * @throw ZorbaException if an error occurs, or the iterator is open already.
71  */
72  void open();
73 
74  /**
75  * brief Check whether the iterator is open or not
76  */
77  bool isOpen();
78 
79  /** \brief Get the next Item of the sequence.
80  *
81  * @param aItem the next Item of the result sequence, if true is returned
82  * by the function.
83  * @return false if all the items of the sequence have been returned already
84  * by previous invocations of next(); true otherwise.
85  * @throw ZorbaException if an error occurs, or the Iterator has not been opened.
86  */
87  bool next(Item& aItem);
88 
89  /** \brief Stop iterating.
90  *
91  * The purpose of this method is to release resources that were allocated
92  * during open. After calling close(), neither close() nor next() may be
93  * called again. However, the iterator may be re-opened (by calling open()).
94  *
95  * @throw ZorbaException if an error occurs, or the Iterator has not been opened.
96  */
97  void close();
98 
99  /**
100  * brief Destroy this iterator from memory
101  */
102  void destroy();
103 }; // class Iterator
104 
105 #endif
blog comments powered by Disqus