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
This interface represents an instance of the XQuery 1.0 and XPath 2.0 Data Model (XDM).
Definition: ItemSequence.h:25
This class is the representation of an XQuery in the Zorba engine.
Definition: XQuery.h:27
A Collection is a persistent sequence of node items.
Definition: Collection.h:29
Instances of the class StaticContext contain the information that is available at the time the query ...
Definition: StaticContext.h:79
bool next(Item &aItem)
Get the next Item of the sequence.
This class defines a set of functions for managing persistent collections.
Iterator(zorba::Item &aItem)
Definition: Iterator.h:57
zorba::Iterator_t theIterator
Definition: Iterator.h:42
void close()
Stop iterating.
void destroy()
brief Destroy this iterator from memory
Iterator(const Iterator &anIterator)
Definition: Iterator.h:48
The Zorba Item interface.
Definition: Item.h:39
void open()
Start iterating.
bool isOpen()
brief Check whether the iterator is open or not
zorba::Item theItem
Definition: Iterator.h:43
Interface for an Iterator over an instance of the XML Data Model (i.e., a sequence of items)...
Definition: Iterator.h:32
Instances of the class DynamicContext contain the information that is available at the time the query...
Iterator()
Definition: Iterator.h:47
Iterator(zorba::Iterator_t anIterator)
Definition: Iterator.h:53
bool theConsumed
Definition: Iterator.h:44