uri_resolvers.h
Go to the documentation of this file.
00001 /*
00002  * Copyright 2006-2011 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_URI_RESOLVERS_API_H
00017 #define ZORBA_URI_RESOLVERS_API_H
00018 
00019 #include <istream>
00020 #include <vector>
00021 #include <map>
00022 
00023 #include <zorba/config.h>
00024 #include <zorba/api_shared_types.h>
00025 #include <zorba/item.h>
00026 #include <zorba/zorba_string.h>
00027 #include <zorba/streams.h>
00028 
00029 /**
00030  * @file uri_resolvers.h
00031  * @brief This header file defines all uri resolvers.
00032  *
00033  * %Zorba has a very flexible uri resolver mechanism.
00034  *
00035  * QQQ Complete documentation
00036  * QQQ file should be renamed uri_resolver.h
00037  */
00038 
00039 namespace zorba {
00040 
00041 /**
00042  * @brief The class representing the result of URL resolution.
00043  *
00044  * This class is the final output of the URI resolution process. All
00045  * URL resolvers return results using subclasses of this class.
00046  */
00047 class ZORBA_DLL_PUBLIC Resource
00048 {
00049 public:
00050   virtual ~Resource() = 0;
00051 };
00052 
00053 /**
00054  * @brief Concrete Resource subclass representing access to an entity
00055  * via a stream.
00056  */
00057 class ZORBA_DLL_PUBLIC StreamResource : public Resource
00058 {
00059 public:
00060 
00061   /**
00062    * @brief Public factory method from istream.
00063    *
00064    * The Resource object will take memory ownership of the istream. Zorba will
00065    * pass it to aStreamReleaser when it is no longer needed, so that the
00066    * original client may delete it.
00067    * @param aStream An istream whence to read the string's content.
00068    * @param aStreamReleaser A function pointer which is invoked once
00069    *        the StreamResource is destroyed. Normally this function will delete
00070    *        the std::istream object passed to it.
00071    */
00072   static StreamResource* create(std::istream* aStream,
00073                                 StreamReleaser aStreamReleaser);
00074   
00075   /**
00076    * @brief Retrieve the istream associated with this Resource.
00077    */
00078   virtual std::istream* getStream() = 0;
00079 
00080   /**
00081    * @brief Retrieve the stream-releaser function.
00082    */
00083   virtual StreamReleaser getStreamReleaser() = 0;
00084 
00085   virtual ~StreamResource() = 0;
00086 };
00087 
00088 /**
00089  * @brief The class containing data which may be of use to URIMappers
00090  * and URLResolvers when mapping/resolving a URI.
00091  *
00092  * This base class specifies the kind of entity for which this URI is being
00093  * resolved - for instance, a schema URI or a module URI. In the future,
00094  * there may be kind-specific subclasses containing additional information;
00095  * as yet however there are none.
00096  */
00097 class ZORBA_DLL_PUBLIC EntityData
00098 {
00099 public:
00100   /**
00101    * @brief enum listing the kinds of entities that may be represented
00102    * by URIs, and hence may be looked up via the URI resolution
00103    * mechanism.
00104    */
00105   enum Kind {
00106     SCHEMA,
00107     MODULE,
00108     THESAURUS,
00109     STOP_WORDS,
00110     COLLECTION,
00111     DOCUMENT
00112   };
00113 
00114   /**
00115    * @brief Return the Kind of Entity for which this URI is being resolved.
00116    */
00117   virtual Kind getKind() const = 0;
00118 
00119   virtual ~EntityData() = 0;
00120 };
00121 
00122 /**
00123  * @brief Interface for URL resolving.
00124  *
00125  * Subclass this to provide a URL resolver to the method
00126  * StaticContext::addURLResolver().
00127  */
00128 class ZORBA_DLL_PUBLIC URLResolver
00129 {
00130   public:
00131 
00132   URLResolver();
00133   virtual ~URLResolver();
00134 
00135   /**
00136    * @brief Transforms an input URL into a Resource.
00137    *
00138    * The "aEntityData" parameter informs the URLResolver what kind of
00139    * entity is being referenced by the URL. URLResolvers may choose to
00140    * make use of this information to alter their behaviour.
00141    * URLResolvers must ensure that they return a concrete subclass of
00142    * Resource which is compatible with the entity kind being resolved.
00143    *
00144    * Implementers of this method should do nothing if they do not know
00145    * how to resolve the URL.  They should create and return a Resource
00146    * if they were successfully able to resolve the URL.
00147    *
00148    * Implementers may throw any exception if they believe that they
00149    * are canonical for the URL and yet had some error arise attempting
00150    * to resolve it.  Note that because there may be several possible
00151    * URLs attempted, Zorba will catch any exceptions thrown and
00152    * continue until all all URLs have failed. Zorba will not re-throw
00153    * any of these exceptions directly. However, if the exception
00154    * thrown extends std::exception, Zorba will make efforts to ensure
00155    * that its error message is included in the exception which is
00156    * ultimately thrown. For any other thrown objects, only the fact
00157    * that an exception occurred will be remembered; the exception
00158    * object itself will be discarded.
00159    *
00160    * In any case, if they create a Resource, Zorba will take memory
00161    * ownership of the Resource and delete it when it is no longer
00162    * needed.
00163    */
00164   virtual Resource* resolveURL(const zorba::String& aUrl,
00165     EntityData const* aEntityData) = 0;
00166 };
00167 
00168 /**
00169  * @brief Interface for URI mapping.
00170  *
00171  * Subclass this to provide a URI mapper to the method
00172  * StaticContext::addURIMapper().
00173  */
00174 class ZORBA_DLL_PUBLIC URIMapper
00175 {
00176   public:
00177 
00178   URIMapper();
00179   virtual ~URIMapper();
00180 
00181   /**
00182    * @brief Transform an input URI into a set of output URIs.
00183    *
00184    * The "aEntityData" parameter informs the URIMapper what kind of
00185    * entity is being referenced by URI. URIMappers may choose to make
00186    * use of this information to alter their behaviour.
00187    *
00188    * Implementers of this method should provide output URIs by adding
00189    * them to the oUris output parameter, using the push_back()
00190    * method. They should not otherwise view or manipulate this vector.
00191    *
00192    * If a URIMapper does not wish to provide any output URIs for the
00193    * given input URI, they should simply do nothing and return. In
00194    * this case, Zorba will continue with the original, unmapped URI.
00195    */
00196   virtual void mapURI(const zorba::String aUri,
00197     EntityData const* aEntityData, std::vector<zorba::String>& oUris)
00198     = 0;
00199 
00200   /**
00201    * @brief enum defining legal return values for mapperKind().
00202    */
00203   enum Kind {
00204     COMPONENT,
00205     CANDIDATE
00206   };
00207 
00208   /**
00209    * @brief Declare whether this is a "component" or "candidate" URI
00210    * mapper.
00211    *
00212    * Zorba supports two different kinds of URI mapping. The first,
00213    * "component URI mapping", is to allow mapping from an input URI to
00214    * a set of URIs which, taken together, comprise the entire entity
00215    * to be resolved. This is currently only supported for module
00216    * import, where it can be used to load a module which is physically
00217    * stored in multiple library module files.
00218    *
00219    * "Candidate URI mapping" is to allow mapping from an input URI to
00220    * a set or URIs which are *potential* identifiers of the entity
00221    * being resolved. Each of these URIs will be treated to any
00222    * subsequent URI mappers, and then treated as URLs and passed in
00223    * turn to all registered URLResolvers. This type of URI mapping is
00224    * supported for all uses of URIs in Zorba. It can be used for
00225    * example to redirect http: URIs to locally-cached file: URLs, or
00226    * to provide several alternative locations for a given resource.
00227    *
00228    * If you do not override this method, the default is "candidate".
00229    */
00230   virtual Kind mapperKind();
00231 
00232   /**
00233    * @brief Constant indicating that Zorba should deny access to the
00234    * given URI.
00235    *
00236    * If any kind of URIMapper returns this value at any point in the
00237    * vector of URIs, Zorba will cause the resolution of this URI to be
00238    * denied with an error.  This can be used, for example, to suppress
00239    * importing particular modules by URI.
00240    */
00241   const static zorba::String DENY_ACCESS;
00242 };
00243 
00244 
00245 /**
00246  * Convenience implementation of a mapper that maps URIs to other
00247  * single URIs. Will only map for one specific Entity Kind.
00248  */
00249 class ZORBA_DLL_PUBLIC OneToOneURIMapper : public URIMapper {
00250 
00251 public:
00252 
00253   /**
00254    * Constructor. Specify the Entity Kind you wish to map. Optionally,
00255    * specify whether this should be a CANDIDATE or COMPONENT mapper;
00256    * default is CANDIDATE.
00257    */
00258   OneToOneURIMapper(EntityData::Kind aEntityKind,
00259                     URIMapper::Kind aMapperKind = URIMapper::CANDIDATE);
00260 
00261   /**
00262    * Add a mapping from a given URI to another URI.
00263    */
00264   void
00265   addMapping(const String& aUri, const String& aMappedUri);
00266 
00267   virtual Kind mapperKind();
00268 
00269   virtual void mapURI(const zorba::String aUri,
00270     EntityData const* aEntityData, std::vector<zorba::String>& oUris);
00271 
00272 private:
00273 
00274   EntityData::Kind const theEntityKind;
00275   URIMapper::Kind const theMapperKind;
00276   typedef std::map<String, String> Mapping_t;
00277   typedef Mapping_t::const_iterator          MappingIter_t;
00278   Mapping_t theMappings;
00279 };
00280 
00281 } /* namespace zorba */
00282 
00283 #endif
00284 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus