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 * </p> 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 * <p> 074 * This class is Not ThreadSafe 075 * </p> 076 * @since 1.6 077 */ 078public class BeiderMorseEncoder implements StringEncoder { 079 // Implementation note: This class is a spring-friendly facade to PhoneticEngine. It allows read/write configuration 080 // of an immutable PhoneticEngine instance that will be delegated to for the actual encoding. 081 082 // a cached object 083 private PhoneticEngine engine = new PhoneticEngine(NameType.GENERIC, RuleType.APPROX, true); 084 085 @Override 086 public Object encode(final Object source) throws EncoderException { 087 if (!(source instanceof String)) { 088 throw new EncoderException("BeiderMorseEncoder encode parameter is not of type String"); 089 } 090 return encode((String) source); 091 } 092 093 @Override 094 public String encode(final String source) throws EncoderException { 095 if (source == null) { 096 return null; 097 } 098 return this.engine.encode(source); 099 } 100 101 /** 102 * Gets the name type currently in operation. 103 * 104 * @return the NameType currently being used 105 */ 106 public NameType getNameType() { 107 return this.engine.getNameType(); 108 } 109 110 /** 111 * Gets the rule type currently in operation. 112 * 113 * @return the RuleType currently being used 114 */ 115 public RuleType getRuleType() { 116 return this.engine.getRuleType(); 117 } 118 119 /** 120 * Discovers if multiple possible encodings are concatenated. 121 * 122 * @return true if multiple encodings are concatenated, false if just the first one is returned 123 */ 124 public boolean isConcat() { 125 return this.engine.isConcat(); 126 } 127 128 /** 129 * Sets how multiple possible phonetic encodings are combined. 130 * 131 * @param concat 132 * true if multiple encodings are to be combined with a '|', false if just the first one is 133 * to be considered 134 */ 135 public void setConcat(final boolean concat) { 136 this.engine = new PhoneticEngine(this.engine.getNameType(), 137 this.engine.getRuleType(), 138 concat, 139 this.engine.getMaxPhonemes()); 140 } 141 142 /** 143 * Sets the type of name. Use {@link NameType#GENERIC} unless you specifically want phonetic encodings 144 * optimized for Ashkenazi or Sephardic Jewish family names. 145 * 146 * @param nameType 147 * the NameType in use 148 */ 149 public void setNameType(final NameType nameType) { 150 this.engine = new PhoneticEngine(nameType, 151 this.engine.getRuleType(), 152 this.engine.isConcat(), 153 this.engine.getMaxPhonemes()); 154 } 155 156 /** 157 * Sets the rule type to apply. This will widen or narrow the range of phonetic encodings considered. 158 * 159 * @param ruleType 160 * {@link RuleType#APPROX} or {@link RuleType#EXACT} for approximate or exact phonetic matches 161 */ 162 public void setRuleType(final RuleType ruleType) { 163 this.engine = new PhoneticEngine(this.engine.getNameType(), 164 ruleType, 165 this.engine.isConcat(), 166 this.engine.getMaxPhonemes()); 167 } 168 169 /** 170 * Sets the number of maximum of phonemes that shall be considered by the engine. 171 * 172 * @param maxPhonemes 173 * the maximum number of phonemes returned by the engine 174 * @since 1.7 175 */ 176 public void setMaxPhonemes(final int maxPhonemes) { 177 this.engine = new PhoneticEngine(this.engine.getNameType(), 178 this.engine.getRuleType(), 179 this.engine.isConcat(), 180 maxPhonemes); 181 } 182 183}