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: */