thesaurus.h
Go to the documentation of this file.
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: */
blog comments powered by Disqus