001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.codec.language.bm;
019
020import org.apache.commons.codec.EncoderException;
021import org.apache.commons.codec.StringEncoder;
022
023/**
024 * Encodes strings into their Beider-Morse phonetic encoding.
025 * <p>
026 * Beider-Morse phonetic encodings are optimised for family names. However, they may be useful for a wide range of
027 * words.
028 * <p>
029 * This encoder is intentionally mutable to allow dynamic configuration through bean properties. As such, it is mutable,
030 * and may not be thread-safe. If you require a guaranteed thread-safe encoding then use {@link PhoneticEngine}
031 * directly.
032 * <p>
033 * <b>Encoding overview</b>
034 * <p>
035 * Beider-Morse phonetic encodings is a multi-step process. Firstly, a table of rules is consulted to guess what
036 * language the word comes from. For example, if it ends in "<code>ault</code>" then it infers that the word is French.
037 * Next, the word is translated into a phonetic representation using a language-specific phonetics table. Some runs of
038 * letters can be pronounced in multiple ways, and a single run of letters may be potentially broken up into phonemes at
039 * different places, so this stage results in a set of possible language-specific phonetic representations. Lastly, this
040 * language-specific phonetic representation is processed by a table of rules that re-writes it phonetically taking into
041 * account systematic pronunciation differences between languages, to move it towards a pan-indo-european phonetic
042 * representation. Again, sometimes there are multiple ways this could be done and sometimes things that can be
043 * pronounced in several ways in the source language have only one way to represent them in this average phonetic
044 * language, so the result is again a set of phonetic spellings.
045 * <p>
046 * Some names are treated as having multiple parts. This can be due to two things. Firstly, they may be hyphenated. In
047 * this case, each individual hyphenated word is encoded, and then these are combined end-to-end for the final encoding.
048 * Secondly, some names have standard prefixes, for example, "<code>Mac/Mc</code>" in Scottish (English) names. As
049 * sometimes it is ambiguous whether the prefix is intended or is an accident of the spelling, the word is encoded once
050 * with the prefix and once without it. The resulting encoding contains one and then the other result.
051 * <p>
052 * <b>Encoding format</b>
053 * <p>
054 * Individual phonetic spellings of an input word are represented in upper- and lower-case roman characters. Where there
055 * are multiple possible phonetic representations, these are joined with a pipe (<code>|</code>) character. If multiple
056 * hyphenated words where found, or if the word may contain a name prefix, each encoded word is placed in elipses and
057 * these blocks are then joined with hyphens. For example, "<code>d'ortley</code>" has a possible prefix. The form
058 * without prefix encodes to "<code>ortlaj|ortlej</code>", while the form with prefix encodes to "
059 * <code>dortlaj|dortlej</code>". Thus, the full, combined encoding is "<code>(ortlaj|ortlej)-(dortlaj|dortlej)</code>".
060 * <p>
061 * The encoded forms are often quite a bit longer than the input strings. This is because a single input may have many
062 * potential phonetic interpretations. For example, "<code>Renault</code>" encodes to "
063 * <code>rYnDlt|rYnalt|rYnult|rinDlt|rinalt|rinult</code>". The <code>APPROX</code> rules will tend to produce larger
064 * encodings as they consider a wider range of possible, approximate phonetic interpretations of the original word.
065 * Down-stream applications may wish to further process the encoding for indexing or lookup purposes, for example, by
066 * splitting on pipe (<code>|</code>) and indexing under each of these alternatives.
067 * <p>
068 * <b>Note</b>: this version of the Beider-Morse encoding is equivalent with v3.4 of the reference implementation.
069 *
070 * @see <a href="http://stevemorse.org/phonetics/bmpm.htm">Beider-Morse Phonetic Matching</a>
071 * @see <a href="http://stevemorse.org/phoneticinfo.htm">Reference implementation</a>
072 *
073 * @since 1.6
074 * @version $Id: BeiderMorseEncoder.java 1636703 2014-11-04 19:49:40Z tn $
075 */
076public class BeiderMorseEncoder implements StringEncoder {
077    // Implementation note: This class is a spring-friendly facade to PhoneticEngine. It allows read/write configuration
078    // of an immutable PhoneticEngine instance that will be delegated to for the actual encoding.
079
080    // a cached object
081    private PhoneticEngine engine = new PhoneticEngine(NameType.GENERIC, RuleType.APPROX, true);
082
083    @Override
084    public Object encode(final Object source) throws EncoderException {
085        if (!(source instanceof String)) {
086            throw new EncoderException("BeiderMorseEncoder encode parameter is not of type String");
087        }
088        return encode((String) source);
089    }
090
091    @Override
092    public String encode(final String source) throws EncoderException {
093        if (source == null) {
094            return null;
095        }
096        return this.engine.encode(source);
097    }
098
099    /**
100     * Gets the name type currently in operation.
101     *
102     * @return the NameType currently being used
103     */
104    public NameType getNameType() {
105        return this.engine.getNameType();
106    }
107
108    /**
109     * Gets the rule type currently in operation.
110     *
111     * @return the RuleType currently being used
112     */
113    public RuleType getRuleType() {
114        return this.engine.getRuleType();
115    }
116
117    /**
118     * Discovers if multiple possible encodings are concatenated.
119     *
120     * @return true if multiple encodings are concatenated, false if just the first one is returned
121     */
122    public boolean isConcat() {
123        return this.engine.isConcat();
124    }
125
126    /**
127     * Sets how multiple possible phonetic encodings are combined.
128     *
129     * @param concat
130     *            true if multiple encodings are to be combined with a '|', false if just the first one is
131     *            to be considered
132     */
133    public void setConcat(final boolean concat) {
134        this.engine = new PhoneticEngine(this.engine.getNameType(),
135                                         this.engine.getRuleType(),
136                                         concat,
137                                         this.engine.getMaxPhonemes());
138    }
139
140    /**
141     * Sets the type of name. Use {@link NameType#GENERIC} unless you specifically want phonetic encodings
142     * optimized for Ashkenazi or Sephardic Jewish family names.
143     *
144     * @param nameType
145     *            the NameType in use
146     */
147    public void setNameType(final NameType nameType) {
148        this.engine = new PhoneticEngine(nameType,
149                                         this.engine.getRuleType(),
150                                         this.engine.isConcat(),
151                                         this.engine.getMaxPhonemes());
152    }
153
154    /**
155     * Sets the rule type to apply. This will widen or narrow the range of phonetic encodings considered.
156     *
157     * @param ruleType
158     *            {@link RuleType#APPROX} or {@link RuleType#EXACT} for approximate or exact phonetic matches
159     */
160    public void setRuleType(final RuleType ruleType) {
161        this.engine = new PhoneticEngine(this.engine.getNameType(),
162                                         ruleType,
163                                         this.engine.isConcat(),
164                                         this.engine.getMaxPhonemes());
165    }
166
167    /**
168     * Sets the number of maximum of phonemes that shall be considered by the engine.
169     *
170     * @param maxPhonemes
171     *            the maximum number of phonemes returned by the engine
172     * @since 1.7
173     */
174    public void setMaxPhonemes(final int maxPhonemes) {
175        this.engine = new PhoneticEngine(this.engine.getNameType(),
176                                         this.engine.getRuleType(),
177                                         this.engine.isConcat(),
178                                         maxPhonemes);
179    }
180
181}