1 // Copyright 2010-2018, Google Inc.
2 // All rights reserved.
3 //
4 // Redistribution and use in source and binary forms, with or without
5 // modification, are permitted provided that the following conditions are
6 // met:
7 //
8 //     * Redistributions of source code must retain the above copyright
9 // notice, this list of conditions and the following disclaimer.
10 //     * Redistributions in binary form must reproduce the above
11 // copyright notice, this list of conditions and the following disclaimer
12 // in the documentation and/or other materials provided with the
13 // distribution.
14 //     * Neither the name of Google Inc. nor the names of its
15 // contributors may be used to endorse or promote products derived from
16 // this software without specific prior written permission.
17 //
18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 
30 #ifndef MOZC_DICTIONARY_DICTIONARY_INTERFACE_H_
31 #define MOZC_DICTIONARY_DICTIONARY_INTERFACE_H_
32 
33 #include <string>
34 #include <vector>
35 
36 #include "base/port.h"
37 #include "base/string_piece.h"
38 #include "dictionary/dictionary_token.h"
39 #include "request/conversion_request.h"
40 
41 namespace mozc {
42 namespace dictionary {
43 
44 class DictionaryInterface {
45  public:
46   // Callback interface for dictionary traversal (currently implemented only for
47   // prefix and exact search). Each method is called in the following manner:
48   //
49   // for (each key found) {
50   //   OnKey(key);
51   //   OnActualKey(key, actual_key, key != actual_key);
52   //   for (each token in the token array for the key) {
53   //     OnToken(key, actual_key, token);
54   //   }
55   // }
56   //
57   // Using the return value of each call of the three methods, you can tell the
58   // traverser how to proceed. The meanings of the four values are as follows:
59   //   1) TRAVERSE_DONE
60   //       Quit the traversal, i.e., no more callbacks for keys and/or tokens.
61   //   2) TRAVERSE_NEXT_KEY
62   //       Finish the traversal for the current key and search for the next key.
63   //       If returned from OnToken(), the remaining tokens are discarded.
64   //   3) TRAVERSE_CULL
65   //       Similar to TRAVERSE_NEXT_KEY, finish the traversal for the current
66   //       key but search for the next key by using search culling. Namely,
67   //       traversal of the subtree starting with the current key is skipped,
68   //       which is the difference from TRAVERSE_NEXT_KEY.
69   //   4) TRAVERSE_CONTINUE
70   //       Continue the traversal for the current key or tokens, namely:
71   //         - If returned from OnKey(), OnActualKey() will be called back.
72   //         - If returned from OnActualKey(), a series of OnToken()'s will be
73   //           called back.
74   //         - If returned from OnToken(), OnToken() will be called back again
75   //           with the next token, provided that it exists. Proceed to the next
76   //           key if there's no more token.
77   class Callback {
78    public:
79     enum ResultType {
80       TRAVERSE_DONE,
81       TRAVERSE_NEXT_KEY,
82       TRAVERSE_CULL,
83       TRAVERSE_CONTINUE,
84     };
85 
~Callback()86     virtual ~Callback() {}
87 
88     // Called back when key is found.
OnKey(StringPiece key)89     virtual ResultType OnKey(StringPiece key) {
90       return TRAVERSE_CONTINUE;
91     }
92 
93     // Called back when actual key is decoded. The third argument is guaranteed
94     // to be (key != actual_key) but computed in an efficient way.
OnActualKey(StringPiece key,StringPiece actual_key,bool is_expanded)95     virtual ResultType OnActualKey(
96         StringPiece key, StringPiece actual_key, bool is_expanded) {
97       return TRAVERSE_CONTINUE;
98     }
99 
100     // Called back when a token is decoded.
OnToken(StringPiece key,StringPiece expanded_key,const Token & token_info)101     virtual ResultType OnToken(StringPiece key,
102                                StringPiece expanded_key,
103                                const Token &token_info) {
104       return TRAVERSE_CONTINUE;
105     }
106 
107    protected:
Callback()108     Callback() {}
109   };
110 
~DictionaryInterface()111   virtual ~DictionaryInterface() {}
112 
113   // Returns true if the dictionary has an entry for the given key.
114   virtual bool HasKey(StringPiece key) const = 0;
115 
116   // Returns true if the dictionary has an entry for the given value.
117   virtual bool HasValue(StringPiece value) const = 0;
118 
119   virtual void LookupPredictive(StringPiece key,
120                                 const ConversionRequest &conversion_request,
121                                 Callback *callback) const = 0;
122 
123   virtual void LookupPrefix(StringPiece key,
124                             const ConversionRequest &conversion_request,
125                             Callback *callback) const = 0;
126 
127   virtual void LookupExact(StringPiece key,
128                            const ConversionRequest &conversion_request,
129                            Callback *callback) const = 0;
130 
131   // For reverse lookup, the reading is stored in Token::value and the word
132   // is stored in Token::key.
133   virtual void LookupReverse(StringPiece str,
134                              const ConversionRequest &conversion_request,
135                              Callback *callback) const = 0;
136 
137   // Looks up a user comment from a pair of key and value.  When (key, value)
138   // doesn't exist in this dictionary or user comment is empty, bool is
139   // returned and string is kept as-is.
LookupComment(StringPiece key,StringPiece value,const ConversionRequest & conversion_request,string * comment)140   virtual bool LookupComment(StringPiece key, StringPiece value,
141                              const ConversionRequest &conversion_request,
142                              string *comment) const { return false; }
143 
144   // Populates cache for LookupReverse().
145   // TODO(noriyukit): These cache initialize/finalize mechanism shouldn't be a
146   // part of the interface.
PopulateReverseLookupCache(StringPiece str)147   virtual void PopulateReverseLookupCache(StringPiece str) const {}
ClearReverseLookupCache()148   virtual void ClearReverseLookupCache() const {}
149 
150   // Sync mutable dictionary data into local disk.
Sync()151   virtual bool Sync() { return true; }
152 
153   // Reload dictionary data from local disk.
Reload()154   virtual bool Reload() { return true; }
155 
156  protected:
157   // Do not allow instantiation
DictionaryInterface()158   DictionaryInterface() {}
159 };
160 
161 }  // namespace dictionary
162 }  // namespace mozc
163 
164 #endif  // MOZC_DICTIONARY_DICTIONARY_INTERFACE_H_
165