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 00017 #ifndef ZORBA_THESAURUS_API_H 00018 #define ZORBA_THESAURUS_API_H 00019 00020 #include <zorba/config.h> 00021 00022 #ifndef ZORBA_NO_FULL_TEXT 00023 00024 #include <zorba/internal/unique_ptr.h> 00025 #include <zorba/internal/ztd.h> 00026 #include <zorba/locale.h> 00027 #include <zorba/uri_resolvers.h> 00028 #include <zorba/zorba_string.h> 00029 00030 namespace zorba { 00031 00032 /////////////////////////////////////////////////////////////////////////////// 00033 00034 /** 00035 * Contains additional data for URIMappers and URLResolvers 00036 * when mapping/resolving a Thesaurus URI. 00037 */ 00038 class ZORBA_DLL_PUBLIC ThesaurusEntityData : public EntityData { 00039 public: 00040 /** 00041 * Gets the language for which a thesaurus is being requested. 00042 * 00043 * @return said language. 00044 */ 00045 virtual locale::iso639_1::type getLanguage() const = 0; 00046 }; 00047 00048 /** 00049 * A %Thesaurus is-a Resource for thesaurus implementations. 00050 */ 00051 class ZORBA_DLL_PUBLIC Thesaurus : public Resource { 00052 public: 00053 typedef std::unique_ptr<Thesaurus,internal::ztd::destroy_delete<Thesaurus> > 00054 ptr; 00055 00056 /** 00057 * The integral type for "at least" and "at most" values. 00058 */ 00059 typedef unsigned range_type; 00060 00061 /** 00062 * An %iterator is used to iterate over lookup results. 00063 */ 00064 class iterator { 00065 public: 00066 typedef std::unique_ptr<iterator,internal::ztd::destroy_delete<iterator> > 00067 ptr; 00068 00069 /** 00070 * Destroys this iterator. 00071 */ 00072 virtual void destroy() const = 0; 00073 00074 /** 00075 * Gets the next synonym. This function must always include the original 00076 * phrase that was looked up in its results. 00077 * 00078 * @param synonym A pointer to the string to receive the next synonym. 00079 * @return Returns \c true only if there is a next synonym. 00080 */ 00081 virtual bool next( String *synonym ) = 0; 00082 00083 protected: 00084 virtual ~iterator() { } 00085 }; 00086 00087 /** 00088 * Destroys this %Thesaurus. 00089 * This function is called by Zorba when the %Thesaurus is no longer needed. 00090 * 00091 * If your URLResolver dynamically allocates %Thesaurus objects, then the 00092 * implementation can simply be (and usually is) <code>delete this</code>. 00093 * 00094 * If your URLResolver returns a pointer to a static %Thesaurus object, then 00095 * the implementation should do nothing. 00096 */ 00097 virtual void destroy() const = 0; 00098 00099 /** 00100 * Looks-up the given phrase. 00101 * 00102 * @param phrase The phrase to look up. 00103 * @param relationship The relationship the synonyms are to have to the given 00104 * \a phrase. 00105 * @param at_least The minimum number of levels within the thesaurus to be 00106 * traversed. 00107 * @param at_most The maximum number of levels within the thesaurus to be 00108 * traversed. 00109 * @return Returns a pointer to an iterator for the results or \c NULL if the 00110 * phrase was not found. 00111 */ 00112 virtual iterator::ptr 00113 lookup( String const &phrase, String const &relationship, 00114 range_type at_least, range_type at_most ) const = 0; 00115 00116 protected: 00117 virtual ~Thesaurus(); 00118 }; 00119 00120 /////////////////////////////////////////////////////////////////////////////// 00121 00122 } // namespace zorba 00123 #endif /* ZORBA_NO_FULL_TEXT */ 00124 #endif /* ZORBA_THESAURUS_API_H */ 00125 /* vim:set et sw=2 ts=2: */