00001 /* 00002 * Copyright 2006-2008 The FLWOR Foundation. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 #ifndef ZORBA_ITERATOR_API_H 00017 #define ZORBA_ITERATOR_API_H 00018 00019 #include <zorba/config.h> 00020 #include <zorba/api_shared_types.h> 00021 #include <zorba/item_sequence.h> 00022 00023 namespace zorba { 00024 00025 /** \brief Interface for an Iterator over an instance of the XML Data Model 00026 * (i.e., a sequence of items). 00027 * 00028 * An iterator can be in one of the following two states: open or not-open. 00029 * When in open state, only methods isOpen(), next() and close() may be called. 00030 * When in not-open state, only isOpen and open() may be called. The open() 00031 * method changes the state from non-open to open, and the close() method 00032 * changes the state from open to not-open. 00033 * 00034 * Iterator is not a thread-safe class, i.e., none of its methods should ever 00035 * be called by two or more threads in parallel. 00036 * 00037 * Note: This class is reference counted. When writing multi-threaded clients, 00038 * it is the responibility of the client code to synchronize assignments to the 00039 * SmartPtr holding this object. 00040 */ 00041 class ZORBA_DLL_PUBLIC Iterator : virtual public SmartObject 00042 { 00043 public: 00044 /** \brief Destructor 00045 */ 00046 virtual ~Iterator() {} 00047 00048 /** \brief Start iterating. 00049 * 00050 * This function needs to be called before calling next() or close(). 00051 * Its purpose is to create and initialize any resources that may be 00052 * needed during the iteration. It should not be called again until 00053 * after close() has been called. 00054 * 00055 * @throw ZorbaException if an error occurs, or the iterator is open already. 00056 */ 00057 virtual void 00058 open() = 0; 00059 00060 /** \brief Get the next Item of the sequence. 00061 * 00062 * @param aItem the next Item of the result sequence, if true is returned 00063 * by the function. 00064 * @return false if all the items of the sequence have been returned already 00065 * by previous invocations of next(); true otherwise. 00066 * @throw ZorbaException if an error occurs, or the Iterator has not been opened. 00067 */ 00068 virtual bool 00069 next(Item& aItem) = 0; 00070 00071 /** \brief Stop iterating. 00072 * 00073 * The purpose of this method is to release resources that were allocated 00074 * during open. After calling close(), neither close() nor next() may be 00075 * called again. However, the iterator may be re-opened (by calling open()). 00076 */ 00077 virtual void 00078 close() = 0; 00079 00080 /** 00081 * brief Check whether the iterator is open or not 00082 */ 00083 virtual bool 00084 isOpen() const = 0; 00085 }; 00086 00087 00088 } /* namespace zorba */ 00089 #endif 00090 /* vim:set et sw=2 ts=2: */