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.html 928559 2014-11-10 02:53:54Z ggregory $ 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}