Home | History | Annotate | Download | only in openwnn
      1 /*
      2  * Copyright (C) 2008-2012  OMRON SOFTWARE Co., Ltd.
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package jp.co.omronsoft.openwnn;
     18 
     19 
     20 /**
     21  * The interface of dictionary searcher used by {@link OpenWnn}.
     22  *
     23  * @author Copyright (C) 2008-2009, OMRON SOFTWARE CO., LTD.  All Rights Reserved.
     24  */
     25 public interface WnnDictionary {
     26     /*
     27      * DEFINITION OF CONSTANTS
     28      */
     29     /**
     30      * Predefined approximate pattern set (capital letters from small letters).
     31      *
     32      * This pattern includes the rules for ambiguous searching capital letters from small letters.<br>
     33      * ex. "a" to "A", "b" to "B", ... , "z" to "Z"
     34      */
     35     public static final int APPROX_PATTERN_EN_TOUPPER               = 0;
     36     /**
     37      * Predefined approximate pattern set (small letters from capital letters).
     38      *
     39      * This pattern includes the rules for ambiguous searching small letters from capital letters.<br>
     40      * ex. "A" to "a", "B" to "b", ... , "Z" to "z"
     41      */
     42     public static final int APPROX_PATTERN_EN_TOLOWER               = 1;
     43     /**
     44      * Predefined approximate pattern set (QWERTY neighbor keys).
     45      *
     46      * This pattern includes the rules for ambiguous searching neighbor keys on QWERTY keyboard.
     47      * Only alphabet letters are defined; numerical or symbol letters are not defined as the rules.<br>
     48      * ex. "a" to "q"/"w"/"s"/"z", "b" to "v"/"g"/"h"/"n", ... ,"z" to "a"/"s"/"x"
     49      */
     50     public static final int APPROX_PATTERN_EN_QWERTY_NEAR           = 2;
     51     /**
     52      * Predefined approximate pattern set (QWERTY neighbor keys/capital letters).
     53      *
     54      * This pattern includes the rules for ambiguous searching capital letters of neighbor keys on QWERTY keyboard.
     55      * Only alphabet letters are defined; numerical or symbol letters are not defined as the rules.<br>
     56      * ex. "a" to "Q"/"W"/"S"/"Z", "b" to "V"/"G"/"H"/"N", ... ,"z" to "A"/"S"/"X"
     57      */
     58     public static final int APPROX_PATTERN_EN_QWERTY_NEAR_UPPER     = 3;
     59     /**
     60      * Predefined approximate pattern set (for Japanese 12-key keyboard).
     61      *
     62      * This pattern includes the standard rules for Japanese multi-tap 12-key keyboard.
     63      * ex. "&#x306F;" to "&#x3070;"/"&#x3071;", "&#x3064;" to "&#x3063;"/"&#x3065;"
     64      */
     65     public static final int APPROX_PATTERN_JAJP_12KEY_NORMAL        = 4;
     66 
     67     /** Search operation mode (exact matching). */
     68     public static final int SEARCH_EXACT                            = 0;
     69     /** Search operation mode (prefix matching). */
     70     public static final int SEARCH_PREFIX                           = 1;
     71     /** Search operation mode (link search). */
     72     public static final int SEARCH_LINK                             = 2;
     73 
     74     /** Sort order (frequency in descending). */
     75     public static final int ORDER_BY_FREQUENCY                      = 0;
     76     /** Sort order (character code of key string in ascending). */
     77     public static final int ORDER_BY_KEY                            = 1;
     78 
     79     /** Type of a part of speech (V1) */
     80     public static final int POS_TYPE_V1                             = 0;
     81     /** Type of a part of speech (V2) */
     82     public static final int POS_TYPE_V2                             = 1;
     83     /** Type of a part of speech (V3) */
     84     public static final int POS_TYPE_V3                             = 2;
     85     /** Type of a part of speech (Top of sentence) */
     86     public static final int POS_TYPE_BUNTOU                         = 3;
     87     /** Type of a part of speech (Single Chinese character) */
     88     public static final int POS_TYPE_TANKANJI                       = 4;
     89     /** Type of a part of speech (Numeric) */
     90     public static final int POS_TYPE_SUUJI                          = 5;
     91     /** Type of a part of speech (Noun) */
     92     public static final int POS_TYPE_MEISI                          = 6;
     93     /** Type of a part of speech (Person's name) */
     94     public static final int POS_TYPE_JINMEI                         = 7;
     95     /** Type of a part of speech (Place name) */
     96     public static final int POS_TYPE_CHIMEI                         = 8;
     97     /** Type of a part of speech (Symbol) */
     98     public static final int POS_TYPE_KIGOU                          = 9;
     99 
    100     /** Index of the user dictionary for {@link #setDictionary(int, int, int)} */
    101     public static final int INDEX_USER_DICTIONARY                   = -1;
    102     /** Index of the learn dictionary for {@link #setDictionary(int, int, int)} */
    103     public static final int INDEX_LEARN_DICTIONARY                  = -2;
    104 
    105 
    106     /**
    107      * Whether this dictionary module is active.
    108      * @return {@code true} if this dictionary module is active; {@code false} if not.
    109      */
    110     public boolean isActive();
    111 
    112     /**
    113      * Set "in use" state.
    114      *
    115      * When the flag set true, the user dictionary is locked.
    116      *
    117      * @param flag      {@code true} if the user dictionary is locked; {@code false} if the user dictionary is unlocked.
    118      */
    119     public void setInUseState( boolean flag );
    120 
    121     /**
    122      * Clear all dictionary settings.
    123      *
    124      * All the dictionaries are set to be unused.
    125      *
    126      * @return          0 if success; minus value(error code) if fail.
    127      */
    128     public int clearDictionary( );
    129 
    130     /**
    131      * Sets a dictionary information for using specified dictionary.
    132      *
    133      * <p>
    134      * A dictionary information contains parameters:<br>
    135      * {@code base} is the bias of frequency for the dictionary.<br>
    136      * {@code high} is the upper limit of frequency for the dictionary.
    137      * </p>
    138      * Searched word's frequency in the dictionary is mapped to the range from {@code base} to {@code high}.
    139      * <br>
    140      * The maximum value of {@code base} and {@code high} is 1000.
    141      * To set a dictionary unused, specify -1 to {@code base} and {@code high}.
    142      *
    143      * @param index     A dictionary index
    144      * @param base      The base frequency for the dictionary
    145      * @param high      The maximum frequency for the dictionary
    146      * @return          0 if success; minus value(error code) if fail.
    147      */
    148     public int setDictionary(int index, int base, int high );
    149 
    150     /**
    151      * Clears approximate patterns.
    152      *
    153      * This clears all approximate search patterns in the search condition.
    154      */
    155     public void clearApproxPattern( );
    156 
    157     /**
    158      * Sets a approximate pattern.
    159      *
    160      * This adds an approximate search pattern(replacement of character) to the search condition.
    161      * The pattern rule is defined as replacing a character({@code src}) to characters({@code dst}).
    162      * <br>
    163      * The length of {@code src} must be 1 and the length of {@code dst} must be lower than 4.<br>
    164      * The maximum count of approximate patterns is 255.
    165      *
    166      * @param src       A character replace from
    167      * @param dst       Characters replace to
    168      * @return          0 if success; minus value(error code) if fail.
    169      */
    170     public int setApproxPattern( String src, String dst );
    171 
    172     /**
    173      * Sets a predefined approximate pattern.
    174      *
    175      * The patterns included predefined approximate search pattern set specified by
    176      * {@code approxPattern} are added to the search condition.
    177      *
    178      * @param approxPattern     A predefined approximate pattern set
    179      * @see jp.co.omronsoft.openwnn.WnnDictionary#APPROX_PATTERN_EN_TOUPPER
    180      * @see jp.co.omronsoft.openwnn.WnnDictionary#APPROX_PATTERN_EN_TOLOWER
    181      * @see jp.co.omronsoft.openwnn.WnnDictionary#APPROX_PATTERN_EN_QWERTY_NEAR
    182      * @see jp.co.omronsoft.openwnn.WnnDictionary#APPROX_PATTERN_EN_QWERTY_NEAR_UPPER
    183      *
    184      * @return                  0 if success; minus value(error code) if fail.
    185      */
    186     public int setApproxPattern( int approxPattern );
    187 
    188     /**
    189      * Search words from dictionaries with specified conditions.
    190      * <p>
    191      * To get the searched word's information, use {@link #getNextWord()}.<br>
    192      * If a same word existed in the set of dictionary, the search result may contain some same words.<br>
    193      * <br>
    194      * If approximate patterns were set, the first word in search
    195      * results is the highest approximation word which contains best
    196      * matched character in the key string. <br>
    197      * For example, If a key string is "bbc", a approximate pattern
    198      * "b" to "a" is specified and the dictionary includes "abc
    199      * (frequency 10)" "bbcd (frequency 1)" "aac (frequency 5)"; the
    200      * result of prefix search is output by following order: "bbcd",
    201      * "abc", "aac".
    202      * </p>
    203      * <p>
    204      * The supported combination of parameters is:
    205      * <table>
    206      * <th><td>Search Mode</td><td>Sort Order</td><td>Ambiguous Search</td></th>
    207      * <tr><td>exact matching</td><td>frequency descending</td><td>no</td></tr>
    208      * <tr><td>prefix matching</td><td>frequency descending</td><td>no</td></tr>
    209      * <tr><td>prefix matching</td><td>frequency descending</td><td>yes</td></tr>
    210      * <tr><td>prefix matching</td><td>character code ascending</td><td>no</td></tr>
    211      * </table>
    212      * </p>
    213      *
    214      * @param operation     The search operation
    215      * @see jp.co.omronsoft.openwnn.WnnDictionary#SEARCH_EXACT
    216      * @see jp.co.omronsoft.openwnn.WnnDictionary#SEARCH_PREFIX
    217      * @param order         The sort order
    218      * @see jp.co.omronsoft.openwnn.WnnDictionary#ORDER_BY_FREQUENCY
    219      * @see jp.co.omronsoft.openwnn.WnnDictionary#ORDER_BY_KEY
    220      * @param keyString     The key string
    221      *
    222      * @see jp.co.omronsoft.openwnn.WnnDictionary#getNextWord
    223      *
    224      * @return              0 if no word is found; 1 if some words found; minus value if a error occurs.
    225      */
    226     public int searchWord(int operation, int order, String keyString );
    227 
    228     /**
    229      * Search words from dictionaries with specified conditions and previous word.
    230      * <p>
    231      * For using link search function, specify the {@code wnnWord} as previous word and
    232      * set {@code SEARCH_LINK} mode to {@code operation}. The other arguments are
    233      * the same as {@link #searchWord(int operation, int order, String keyString)}.
    234      * <p>
    235      * If the prediction dictionary for reading is set to use, the previous word must contain
    236      * the {@code stroke} and the {@code candidate} information. If the prediction dictionary
    237      * for part of speech is set to use, the previous word must contain the {@code partOfSpeech} information.
    238      *
    239      * @param wnnWord       The previous word
    240      * @see jp.co.omronsoft.openwnn.WnnDictionary#searchWord
    241      *
    242      * @return              0 if no word is found; 1 if some words found; minus value if a error occurs.
    243      */
    244     public int searchWord(int operation, int order, String keyString, WnnWord wnnWord );
    245 
    246     /**
    247      * Retrieve a searched word information.
    248      *
    249      * It returns a word information from top of the {@code searchWord()}'s result.
    250      * To get all word's information of the result, call this method repeatedly until it returns null.
    251      *
    252      * @return              An instance of WnnWord; null if no result or an error occurs.
    253      */
    254     public WnnWord getNextWord( );
    255 
    256     /**
    257      * Retrieve a searched word information with condition of length.
    258      *
    259      * It returns a word information from top of the {@code searchWord()}'s result.
    260      * To get all word's information of the result, call this method repeatedly until it returns null.
    261      *
    262      * @param length    >0 if only the result of specified length is retrieved; 0 if no condition exist
    263      * @return          An instance of WnnWord; null if no result or an error occurs.
    264      */
    265     public WnnWord getNextWord( int length );
    266 
    267     /**
    268      * Retrieve all word in the user dictionary.
    269      *
    270      * @return          The array of WnnWord objects.
    271      */
    272     public WnnWord[] getUserDictionaryWords( );
    273 
    274     /**
    275      * Retrieve the connect matrix.
    276      *
    277      * @return          The array of the connect matrix; null if an error occurs.
    278      */
    279     public byte[][] getConnectMatrix( );
    280 
    281     /**
    282      * Retrieve the part of speech information specified POS type.
    283      *
    284      * @param type      The type of a part of speech
    285      * @return          The part of speech information; null if invalid type is specified or  an error occurs.
    286      *
    287      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_V1
    288      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_V2
    289      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_V3
    290      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_BUNTOU
    291      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_TANKANJI
    292      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_SUUJI
    293      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_MEISI
    294      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_JINMEI
    295      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_CHIMEI
    296      * @see jp.co.omronsoft.openwnn.WnnDictionary#POS_TYPE_KIGOU
    297     */
    298     public WnnPOS getPOS( int type );
    299 
    300     /**
    301      * Clear the user dictionary.
    302      *
    303      * @return      0 if no error occur; <0 if an error occur
    304      */
    305     public int clearUserDictionary();
    306     /**
    307      * Clear the learn dictionary.
    308      *
    309      * @return      0 if no error occur; <0 if an error occur
    310      */
    311     public int clearLearnDictionary();
    312 
    313     /**
    314      * Add the words to user dictionary.
    315      *
    316      * @param word      The array of word
    317      * @return          0 if no error occur; <0 if an error occur
    318      */
    319     public int addWordToUserDictionary( WnnWord[] word );
    320     /**
    321      * Add the word to user dictionary.
    322      *
    323      * @param word      The word
    324      * @return          0 if no error occur; <0 if an error occur
    325      */
    326     public int addWordToUserDictionary( WnnWord word );
    327 
    328     /**
    329      * Remove the words from user dictionary.
    330      *
    331      * @param word      The array of word
    332      * @return          0 if no error occur; <0 if an error occur
    333      */
    334     public int removeWordFromUserDictionary( WnnWord[] word );
    335     /**
    336      * Remove the word from user dictionary.
    337      *
    338      * @param word      The word
    339      * @return          0 if no error occur; <0 if an error occur
    340      */
    341     public int removeWordFromUserDictionary( WnnWord word );
    342 
    343     /**
    344      * Learn the word.
    345      *
    346      * @param word      The word for learning
    347      * @return          0 if no error occur; <0 if an error occur
    348      */
    349     public int learnWord( WnnWord word );
    350 
    351     /**
    352      * Learn the word with connection.
    353      *
    354      * @param word              The word for learning
    355      * @param previousWord      The word for link learning
    356      * @return                  0 if no error occur; <0 if an error occur
    357      */
    358     public int learnWord( WnnWord word, WnnWord previousWord );
    359 }
    360 
    361