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 00023 namespace zorba { 00024 00025 /** \brief A Collection is a persistent sequence of node items. 00026 * 00027 * Instances of this class can be used to modify or retrieve the contents 00028 * of a collection. 00029 * 00030 * The variable aNodes passed to any of the insert functions is evaluated 00031 * as though it were an enclosed expression in an element constructor. 00032 * The result of this step is a sequence of nodes to be inserted into the collection. 00033 * 00034 * Note: This class is reference counted. When writing multi-threaded clients, 00035 * it is the responibility of the client code to synchronize assignments to the 00036 * SmartPtr holding this object. 00037 */ 00038 class ZORBA_DLL_PUBLIC Collection : public SmartObject 00039 { 00040 public: 00041 /** 00042 * \brief Get the name of the collection. 00043 * 00044 * @return The name of the collection. 00045 */ 00046 virtual const Item 00047 getName() const = 0; 00048 00049 /** 00050 * This function inserts copies of the 00051 * given nodes at the beginning of the collection. 00052 * 00053 * @param aNodes The sequences of nodes whose copies 00054 * should be added to the collection. 00055 * 00056 */ 00057 virtual void 00058 insertNodesFirst(const ItemSequence_t& aNodes) = 0; 00059 00060 /** 00061 * This function inserts copies of the 00062 * given nodes at the end of the collection. 00063 * 00064 * @param aNodes The sequences of nodes whose copies 00065 * should be added to the collection. 00066 * 00067 */ 00068 virtual void 00069 insertNodesLast(const ItemSequence_t& aNodes) = 0; 00070 00071 /** 00072 * This function inserts copies of the given 00073 * nodes into a collection at the position directly preceding the 00074 * given target node. 00075 * 00076 * @param aTarget the node in the collection before which the 00077 * sequence should be inserted. 00078 * @param aNodes The sequences of nodes whose copies should 00079 * be added to the collection. 00080 * 00081 * @throw XDDY0011 if any nodes in the sequence is not a member of a collection 00082 * or not all nodes of the sequence belong to the same collection. 00083 * 00084 */ 00085 virtual void 00086 insertNodesBefore( 00087 const Item& aTarget, 00088 const ItemSequence_t& aNodes) = 0; 00089 00090 /** 00091 * This function inserts copies of the given 00092 * nodes into a collection at the position directly following the 00093 * given target node. 00094 * 00095 * @param aTarget the node in the collection after which the 00096 * sequence should be inserted. 00097 * @param aNodes The sequences of nodes whose copies should 00098 * be added to the collection. 00099 * 00100 * @throw XDDY0011 if any nodes in the sequence is not a member of a collection 00101 * or not all nodes of the sequence belong to the same collection. 00102 * 00103 */ 00104 virtual void 00105 insertNodesAfter( 00106 const Item& aTarget, 00107 const ItemSequence_t& aNodes) = 0; 00108 00109 /** 00110 * This function deletes zero of more nodes from a collection. 00111 * 00112 * @param aNodes the nodes in the collection that should be deleted. 00113 * 00114 * @throw XDDY0011 if any nodes in the given sequence is not a member of a collection 00115 * or not all nodes of the sequence belong to the same collection. 00116 * 00117 */ 00118 virtual void 00119 deleteNodes(const ItemSequence_t& aNodes) = 0; 00120 00121 /** 00122 * This function deletes the first node from a collection. 00123 * 00124 * @throw XDDY0011 if the collection doesn't contain any node. 00125 * 00126 */ 00127 virtual void 00128 deleteNodeFirst() = 0; 00129 00130 /** 00131 * This function deletes the n first nodes from a collection. 00132 * 00133 * @throw XDDY0011 if the collection doesn't contain any node. 00134 * 00135 */ 00136 virtual void 00137 deleteNodesFirst(unsigned long aNumNodes) = 0; 00138 00139 /** 00140 * This function deletes the last node from a collection. 00141 * 00142 * @throw XDDY0011 if the collection doesn't contain any node. 00143 * 00144 */ 00145 virtual void 00146 deleteNodeLast() = 0; 00147 00148 /** 00149 * This function deletes the n last nodes from a collection. 00150 * 00151 * @throw XDDY0011 if the collection doesn't contain any node. 00152 * 00153 */ 00154 virtual void 00155 deleteNodesLast(unsigned long aNumNodes) = 0; 00156 00157 /** 00158 * This function returns the index of the given node in the collection. 00159 * 00160 * @param aNode The node to retrieve the index from. 00161 * 00162 * @return Returns the position of the given node in the collection. 00163 * 00164 * @throw XDDY0011 if node is not contained in any collection. 00165 * 00166 */ 00167 virtual long long 00168 indexOf(const Item& aNode) = 0; 00169 00170 /** 00171 * This function returns the sequence of nodes of the collection. 00172 * 00173 * @return The sequence contained in the given collection. 00174 * 00175 */ 00176 virtual ItemSequence_t 00177 contents() = 0; 00178 00179 /** 00180 * \brief Destructor. 00181 */ 00182 virtual ~Collection() {} 00183 00184 }; 00185 00186 } /* namespace zorba */ 00187 00188 #endif 00189 /* 00190 * Local variables: 00191 * mode: c++ 00192 * End: 00193 */ 00194 /* vim:set et sw=2 ts=2: */