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_COLLECTION_API_H 00017 #define ZORBA_COLLECTION_API_H 00018 00019 #include <zorba/config.h> 00020 #include <zorba/api_shared_types.h> 00021 #include <zorba/item.h> 00022 #include <vector> 00023 00024 namespace zorba { 00025 00026 /** \brief A Collection is a persistent sequence of node items. 00027 * 00028 * Instances of this class can be used to modify or retrieve the contents 00029 * of a collection. 00030 * 00031 * The variable aNodes passed to any of the insert functions is evaluated 00032 * as though it were an enclosed expression in an element constructor. 00033 * The result of this step is a sequence of nodes to be inserted into the collection. 00034 * 00035 * Note: This class is reference counted. When writing multi-threaded clients, 00036 * it is the responibility of the client code to synchronize assignments to the 00037 * SmartPtr holding this object. 00038 */ 00039 class ZORBA_DLL_PUBLIC Collection : public SmartObject 00040 { 00041 public: 00042 /** 00043 * \brief Get the name of the collection. 00044 * 00045 * @return The name of the collection. 00046 */ 00047 virtual const Item 00048 getName() const = 0; 00049 00050 /** 00051 * This function inserts copies of the 00052 * given nodes at the beginning of the collection. 00053 * 00054 * @param aNodes The sequences of nodes whose copies 00055 * should be added to the collection. 00056 * 00057 */ 00058 virtual void 00059 insertNodesFirst(const ItemSequence_t& aNodes) = 0; 00060 00061 /** 00062 * This function inserts copies of the 00063 * given nodes at the end of the collection. 00064 * 00065 * @param aNodes The sequences of nodes whose copies 00066 * should be added to the collection. 00067 * 00068 */ 00069 virtual void 00070 insertNodesLast(const ItemSequence_t& aNodes) = 0; 00071 00072 /** 00073 * This function inserts copies of the given 00074 * nodes into a collection at the position directly preceding the 00075 * given target node. 00076 * 00077 * @param aTarget the node in the collection before which the 00078 * sequence should be inserted. 00079 * @param aNodes The sequences of nodes whose copies should 00080 * be added to the collection. 00081 * 00082 * @throw XDDY0011 if any nodes in the sequence is not a member of a collection 00083 * or not all nodes of the sequence belong to the same collection. 00084 * 00085 */ 00086 virtual void 00087 insertNodesBefore( 00088 const Item& aTarget, 00089 const ItemSequence_t& aNodes) = 0; 00090 00091 /** 00092 * This function inserts copies of the given 00093 * nodes into a collection at the position directly following the 00094 * given target node. 00095 * 00096 * @param aTarget the node in the collection after which the 00097 * sequence should be inserted. 00098 * @param aNodes The sequences of nodes whose copies should 00099 * be added to the collection. 00100 * 00101 * @throw XDDY0011 if any nodes in the sequence is not a member of a collection 00102 * or not all nodes of the sequence belong to the same collection. 00103 * 00104 */ 00105 virtual void 00106 insertNodesAfter( 00107 const Item& aTarget, 00108 const ItemSequence_t& aNodes) = 0; 00109 00110 /** 00111 * This function deletes zero of more nodes from a collection. 00112 * 00113 * @param aNodes the nodes in the collection that should be deleted. 00114 * 00115 * @throw XDDY0011 if any nodes in the given sequence is not a member of a collection 00116 * or not all nodes of the sequence belong to the same collection. 00117 * 00118 */ 00119 virtual void 00120 deleteNodes(const ItemSequence_t& aNodes) = 0; 00121 00122 /** 00123 * This function deletes the first node from a collection. 00124 * 00125 * @throw XDDY0011 if the collection doesn't contain any node. 00126 * 00127 */ 00128 virtual void 00129 deleteNodeFirst() = 0; 00130 00131 /** 00132 * This function deletes the n first nodes from a collection. 00133 * 00134 * @throw XDDY0011 if the collection doesn't contain any node. 00135 * 00136 */ 00137 virtual void 00138 deleteNodesFirst(unsigned long aNumNodes) = 0; 00139 00140 /** 00141 * This function deletes the last node from a collection. 00142 * 00143 * @throw XDDY0011 if the collection doesn't contain any node. 00144 * 00145 */ 00146 virtual void 00147 deleteNodeLast() = 0; 00148 00149 /** 00150 * This function deletes the n last nodes from a collection. 00151 * 00152 * @throw XDDY0011 if the collection doesn't contain any node. 00153 * 00154 */ 00155 virtual void 00156 deleteNodesLast(unsigned long aNumNodes) = 0; 00157 00158 /** 00159 * This function returns the index of the given node in the collection. 00160 * 00161 * @param aNode The node to retrieve the index from. 00162 * 00163 * @return Returns the position of the given node in the collection. 00164 * 00165 * @throw XDDY0011 if node is not contained in any collection. 00166 * 00167 */ 00168 virtual long long 00169 indexOf(const Item& aNode) = 0; 00170 00171 /** 00172 * This function returns the sequence of nodes of the collection. 00173 * 00174 * @return The sequence contained in the given collection. 00175 * 00176 */ 00177 virtual ItemSequence_t 00178 contents() = 0; 00179 00180 /** 00181 * \brief Destructor. 00182 */ 00183 virtual ~Collection() {} 00184 00185 /** 00186 * Retrieves all annotations for the given collection. 00187 * If the collection is a statically declared collection, the annotations 00188 * are the ones that haven been given in the declaration of the collection 00189 * (or the defaults). If the collection is a dynamic collection, the 00190 * annotations are the default ones for dynamic collections. 00191 * 00192 * @return a list of all annotations for the given collection (if found) 00193 */ 00194 virtual void 00195 getAnnotations(std::vector<Annotation_t>& aAnnotations) const = 0; 00196 00197 /** 00198 * The function checks if this collection has been statically declared. 00199 * 00200 * @return true if the collection is a static collection, false otherwise. 00201 */ 00202 virtual bool 00203 isStatic() const = 0; 00204 00205 /** 00206 * Retrieves the sequence type for this (static declared) collection. 00207 * 00208 * @return the sequence type for the said collection, or 0 00209 * if this collection is not statically declared. 00210 * 00211 * @see isStatic() 00212 */ 00213 virtual TypeIdentifier_t 00214 getType() const = 0; 00215 00216 /** \brief Register a DiagnosticHandler to which errors 00217 * occuring during the management or manipulation of this collection 00218 * are reported. 00219 * 00220 * If no DiagnosticHandler has been set using 00221 * (1) this function, 00222 * (2) the corresponding function of the XmlDataManager, or 00223 * (3) the corresponding function of the CollectionManager 00224 * then subclasses of the ZorbaException class are thrown to report 00225 * errors. 00226 * 00227 * @param aDiagnosticHandler DiagnosticHandler to which errors 00228 * are reported. The caller retains ownership over the 00229 * DiagnosticHandler passed as parameter. 00230 */ 00231 virtual void 00232 registerDiagnosticHandler(DiagnosticHandler* aDiagnosticHandler) = 0; 00233 00234 }; 00235 00236 } /* namespace zorba */ 00237 00238 #endif 00239 /* 00240 * Local variables: 00241 * mode: c++ 00242 * End: 00243 */ 00244 /* vim:set et sw=2 ts=2: */