uri_resolvers.h
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2011 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 ZORBA_URI_RESOLVERS_API_H
17 #define ZORBA_URI_RESOLVERS_API_H
18 
19 #include <istream>
20 #include <vector>
21 #include <map>
22 
23 #include <zorba/config.h>
24 #include <zorba/api_shared_types.h>
25 #include <zorba/item.h>
26 #include <zorba/zorba_string.h>
27 #include <zorba/streams.h>
28 #include <zorba/locale.h>
30 #include <zorba/internal/ztd.h>
31 
32 /**
33  * @file uri_resolvers.h
34  * @brief This header file defines all uri resolvers.
35  *
36  * %Zorba has a very flexible uri resolver mechanism.
37  *
38  * QQQ Complete documentation
39  * QQQ file should be renamed uri_resolver.h
40  */
41 
42 namespace zorba {
43 
44 /**
45  * @brief The class representing the result of URL resolution.
46  *
47  * This class is the final output of the URI resolution process. All
48  * URL resolvers return results using subclasses of this class.
49  */
50 class ZORBA_DLL_PUBLIC Resource
51 {
52 public:
54  ptr;
55 
56  virtual ~Resource() = 0;
57 
58  /**
59  * @brief Destroy/clean up this Resource.
60  *
61  * Zorba will call this method when it no longer needs the Resource. It
62  * is the responsibility of subclasses to clean up appropriate when
63  * this method is called, including calling "delete this" if the Resource
64  * was allocated with "new".
65  */
66  virtual void destroy() const = 0;
67 };
68 
69 /**
70  * @brief Concrete Resource subclass representing access to an entity
71  * via a stream.
72  */
73 class ZORBA_DLL_PUBLIC StreamResource : public Resource
74 {
75 public:
76 
77  /**
78  * @brief Public factory method from istream.
79  *
80  * The Resource object will take memory ownership of the istream. Zorba will
81  * pass it to aStreamReleaser when it is no longer needed, so that the
82  * original client may delete it.
83  * @param aStream An istream whence to read the string's content.
84  * @param aStreamReleaser A function pointer which is invoked once
85  * the StreamResource is destroyed. Normally this function will delete
86  * the std::istream object passed to it.
87  * @param aIsStreamSeekable Determines whether the given stream is arbitrarily
88  * seekable without throwing errors.
89  */
90  static StreamResource* create(std::istream* aStream,
91  StreamReleaser aStreamReleaser,
92  bool aIsStreamSeekable = false);
93 
94  /**
95  * @brief Retrieve the istream associated with this Resource.
96  */
97  virtual std::istream* getStream() = 0;
98 
99  /**
100  * @brief Retrieve the stream-releaser function.
101  */
102  virtual StreamReleaser getStreamReleaser() = 0;
103 
104  virtual ~StreamResource() = 0;
105 
106  virtual bool isStreamSeekable() const = 0;
107 };
108 
109 /**
110  * @brief The class containing data which may be of use to URIMappers
111  * and URLResolvers when mapping/resolving a URI.
112  *
113  * This base class specifies the kind of entity for which this URI is being
114  * resolved - for instance, a schema URI or a module URI. Subclasses of
115  * this class will provide additional data for specific kinds of entities.
116  */
117 class ZORBA_DLL_PUBLIC EntityData
118 {
119 public:
120  /**
121  * @brief enum listing the kinds of entities that may be represented
122  * by URIs, and hence may be looked up via the URI resolution
123  * mechanism.
124  */
125  enum Kind {
132  SOME_CONTENT
133  };
134 
135  /**
136  * @brief Return the Kind of Entity for which this URI is being resolved.
137  */
138  virtual Kind getKind() const = 0;
139 
140  virtual ~EntityData() = 0;
141 };
142 
143 /**
144  * @brief Interface for URL resolving.
145  *
146  * Subclass this to provide a URL resolver to the method
147  * StaticContext::addURLResolver().
148  */
149 class ZORBA_DLL_PUBLIC URLResolver
150 {
151  public:
152 
153  URLResolver();
154  virtual ~URLResolver();
155 
156  /**
157  * @brief Transforms an input URL into a Resource.
158  *
159  * The "aEntityData" parameter informs the URLResolver what kind of
160  * entity is being referenced by the URL. URLResolvers may choose to
161  * make use of this information to alter their behaviour.
162  * URLResolvers must ensure that they return a concrete subclass of
163  * Resource which is compatible with the entity kind being resolved.
164  *
165  * Implementers of this method should do nothing if they do not know
166  * how to resolve the URL. They should create and return a Resource
167  * if they were successfully able to resolve the URL.
168  *
169  * Implementers may throw any exception if they believe that they
170  * are canonical for the URL and yet had some error arise attempting
171  * to resolve it. Note that because there may be several possible
172  * URLs attempted, Zorba will catch any exceptions thrown and
173  * continue until all all URLs have failed. Zorba will not re-throw
174  * any of these exceptions directly. However, if the exception
175  * thrown extends std::exception, Zorba will make efforts to ensure
176  * that its error message is included in the exception which is
177  * ultimately thrown. For any other thrown objects, only the fact
178  * that an exception occurred will be remembered; the exception
179  * object itself will be discarded.
180  *
181  * In any case, if they create a Resource, Zorba will take memory
182  * ownership of the Resource and delete it (by calling destroy() on it)
183  * when it is no longer needed.
184  */
185  virtual Resource* resolveURL(const zorba::String& aUrl,
186  EntityData const* aEntityData) = 0;
187 };
188 
189 /**
190  * @brief Interface for URI mapping.
191  *
192  * Subclass this to provide a URI mapper to the method
193  * StaticContext::addURIMapper().
194  */
195 class ZORBA_DLL_PUBLIC URIMapper
196 {
197  public:
198 
199  URIMapper();
200  virtual ~URIMapper();
201 
202  /**
203  * @brief Transform an input URI into a set of output URIs.
204  *
205  * The "aEntityData" parameter informs the URIMapper what kind of
206  * entity is being referenced by URI. URIMappers may choose to make
207  * use of this information to alter their behaviour.
208  *
209  * Implementers of this method should provide output URIs by adding
210  * them to the oUris output parameter, using the push_back()
211  * method. They should not otherwise view or manipulate this vector.
212  *
213  * If a URIMapper does not wish to provide any output URIs for the
214  * given input URI, they should simply do nothing and return. In
215  * this case, Zorba will continue with the original, unmapped URI.
216  */
217  virtual void mapURI(const zorba::String aUri,
218  EntityData const* aEntityData, std::vector<zorba::String>& oUris)
219  = 0;
220 
221  /**
222  * @brief enum defining legal return values for mapperKind().
223  */
224  enum Kind {
226  CANDIDATE
227  };
228 
229  /**
230  * @brief Declare whether this is a "component" or "candidate" URI
231  * mapper.
232  *
233  * Zorba supports two different kinds of URI mapping. The first,
234  * "component URI mapping", is to allow mapping from an input URI to
235  * a set of URIs which, taken together, comprise the entire entity
236  * to be resolved. This is currently only supported for module
237  * import, where it can be used to load a module which is physically
238  * stored in multiple library module files.
239  *
240  * "Candidate URI mapping" is to allow mapping from an input URI to
241  * a set or URIs which are *potential* identifiers of the entity
242  * being resolved. Each of these URIs will be treated to any
243  * subsequent URI mappers, and then treated as URLs and passed in
244  * turn to all registered URLResolvers. This type of URI mapping is
245  * supported for all uses of URIs in Zorba. It can be used for
246  * example to redirect http: URIs to locally-cached file: URLs, or
247  * to provide several alternative locations for a given resource.
248  *
249  * If you do not override this method, the default is "candidate".
250  */
251  virtual Kind mapperKind();
252 
253  /**
254  * @brief Constant indicating that Zorba should deny access to the
255  * given URI.
256  *
257  * If any kind of URIMapper returns this value at any point in the
258  * vector of URIs, Zorba will cause the resolution of this URI to be
259  * denied with an error. This can be used, for example, to suppress
260  * importing particular modules by URI.
261  */
263 };
264 
265 
266 /**
267  * Convenience implementation of a mapper that maps URIs to other
268  * single URIs. Will only map for one specific Entity Kind.
269  */
270 class ZORBA_DLL_PUBLIC OneToOneURIMapper : public URIMapper {
271 
272 public:
273 
274  /**
275  * Constructor. Specify the Entity Kind you wish to map. Optionally,
276  * specify whether this should be a CANDIDATE or COMPONENT mapper;
277  * default is CANDIDATE.
278  */
280  URIMapper::Kind aMapperKind = URIMapper::CANDIDATE);
281 
282  /**
283  * Add a mapping from a given URI to another URI.
284  */
285  void
286  addMapping(const String& aUri, const String& aMappedUri);
287 
288  virtual Kind mapperKind();
289 
290  virtual void mapURI(const zorba::String aUri,
291  EntityData const* aEntityData, std::vector<zorba::String>& oUris);
292 
293 private:
294 
295  EntityData::Kind const theEntityKind;
296  URIMapper::Kind const theMapperKind;
297  typedef std::map<String, String> Mapping_t;
298  typedef Mapping_t::const_iterator MappingIter_t;
299  Mapping_t theMappings;
300 };
301 
302 } /* namespace zorba */
303 
304 #endif
305 /* vim:set et sw=2 ts=2: */
Kind
enum listing the kinds of entities that may be represented by URIs, and hence may be looked up via th...
Interface for URI mapping.
void(* StreamReleaser)(std::istream *)
Definition: streams.h:21
The class containing data which may be of use to URIMappers and URLResolvers when mapping/resolving a...
Kind
enum defining legal return values for mapperKind().
Interface for URL resolving.
The Zorba string class.
Definition: zorba_string.h:33
Convenience implementation of a mapper that maps URIs to other single URIs.
Concrete Resource subclass representing access to an entity via a stream.
Definition: uri_resolvers.h:73
std::unique_ptr< Resource, internal::ztd::destroy_delete< Resource > > ptr
Definition: uri_resolvers.h:54
static const zorba::String DENY_ACCESS
Constant indicating that Zorba should deny access to the given URI.
The class representing the result of URL resolution.
Definition: uri_resolvers.h:50