StaticCollectionManager.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2012 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_STATIC_COLLECTION_MANAGER_H
17 #define API_STATIC_COLLECTION_MANAGER_H
18 
19  /** \brief Using the StaticCollectionManager one can retrieve information
20  * about statically declared collections and indexes as well as manage them.
21  *
22  * The StaticCollectionManager can be retrieved from (1) a compiled XQuery
23  * or (2) a StaticContext object. In both cases, this class provides access
24  * to information for the collections and indexes that are declared in (1) all the
25  * modules (transitively) imported by the main query or (2) the module
26  * that resulted in the compilation of the StaticContext, respectively.
27  * Moreover, this class allows to create or delete such collections and indexes.
28  *
29  */
31 {
32 private:
33  zorba::StaticCollectionManager* theStaticManager;
34 
35 public:
36  StaticCollectionManager(const StaticCollectionManager& aMgr) : theStaticManager(aMgr.theStaticManager) {}
37  StaticCollectionManager(zorba::StaticCollectionManager* aMgr) : theStaticManager(aMgr) {}
38 
39  /**
40  * This function returns a sequence of names of the collections
41  * that are available. If this is an instance of the StaticCollectionManager
42  * class (i.e. returned by any of the getStaticCollectionManager methods),
43  * the collections returned by this function are also
44  * statically declared.
45  *
46  * @return The list of names of the available collections.
47  *
48  */
50 
51  /**
52  * This function returns a sequence of names of the indexes
53  * that are available.
54  *
55  * @return The list of names of the available indexes.
56  */
58 
59  /**
60  * This function creates the collection with the given name.
61  *
62  * @param aName The name of the collection to create.
63  *
64  * @throw XDDY0002 if a collection with the given name already exists.
65  *
66  */
67  void createCollection(const Item &aName );
68 
69  /**
70  * This function creates the collection with the given name.
71  * Moreover, it adds copies of the sequence aContents to the new collection.
72  *
73  * @param aName The name of the collection to create.
74  * @param aContents The sequence of items.
75  *
76  * @throw XDDY0002 if a collection with the given name already exists.
77  *
78  */
79  void createCollection(const Item &aName, const ItemSequence &aContents );
80 
81  /**
82  * Create the index with the given name.
83  *
84  * @param aQName The name of the index to create.
85  *
86  * @throw zerr:ZDDY0021 if a index with the given name is not declared.
87  *
88  * @throw zerr:ZDDY0022 if a index with the given name already exists.
89  */
90  void createIndex( const Item & aQName );
91 
92  /**
93  * List all the collections that are declared in the XQuery or the
94  * StaticContext that was used to retrieve this StaticCollectionManager.
95  *
96  * @return a sequence of QNames of all said collections
97  */
99 
100  /**
101  * List all the indexes that are declared in the XQuery or the
102  * StaticContext that was used to retrieve this StaticCollectionManager.
103  *
104  * @return a sequence of QNames of all said indexes
105  */
107 
108  /**
109  * This function removes the collection with the given name.
110  *
111  * @param aName The name of the collection to delete.
112  *
113  * @throw XDDY0003 if the collection does not exist.
114  */
115  void deleteCollection(const Item &aName );
116 
117  /**
118  * Create the index with the given name.
119  *
120  * @param aQName The name of the index to create.
121  *
122  * @throw zerr:ZDDY0021 if a index with the given name is not declared.
123  *
124  * @throw zerr:ZDDY0009 if a index with the given name does not exist
125  */
126  void deleteIndex(const Item &aQName );
127 
128  /**
129  * Returns a instance of the Collection class which can
130  * be used to modify and retrieve the contents of the collection
131  * identified by the given name.
132  *
133  * @param aName The name of the collection to retrieve.
134  *
135  * @throw XDDY0003 if the collection does not exist.
136  */
137  Collection getCollection(const Item &aName );
138 
139  /**
140  * This function returns true if a collection with the given name is available.
141  * If this is an instance of the StaticCollectionManager class (i.e.
142  * returned by any of the getStaticCollectionManager() methods),
143  * the collection also needs to be statically declared.
144  *
145  * @param aName The name of the collection that is being checked.
146  *
147  * @return true if the collection is available and false otherwise.
148  *
149  */
150  bool isAvailableCollection(const Item &aName );
151 
152  /**
153  * This function returns true if a index with the given name is available.
154  *
155  * @param aQName The name of the index that is being checked.
156  *
157  * @return true if the index is available and false otherwise.
158  */
159  bool isAvailableIndex(const Item &aQName );
160 
161  /**
162  * Checks if a collection with a given QName is declared in the XQuery
163  * or the StaticContext that was used to retrieve this
164  * StaticCollectionManager.
165  *
166  * @return true if a collection with the given name is declared,
167  * false otherwise.
168  */
169  bool isDeclaredCollection( const Item & aQName );
170 
171  /**
172  * Checks if a index with a given QName is declared in the XQuery
173  * or the StaticContext that was used to retrieve this
174  * StaticCollectionManager.
175  *
176  * @return true if a collection with the given name is declared,
177  * false otherwise.
178  */
179  bool isDeclaredIndex( const Item & aQName );
180 
181  /** \brief Register a DiagnosticHandler to which errors
182  * occuring during the management of collections are reported.
183  *
184  * If no DiagnosticHandler has been set using this function or
185  * the corresponding function of the XmlDataManager then
186  * subclasses of the ZorbaException class are thrown to report
187  * errors.
188  *
189  * @param aDiagnosticHandler DiagnosticHandler to which errors
190  * are reported. The caller retains ownership over the
191  * DiagnosticHandler passed as parameter.
192  */
193  void registerDiagnosticHandler(DiagnosticHandler *aDiagnosticHandler );
194 };
195 
196 #endif
blog comments powered by Disqus