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    
018    package org.apache.commons.codec;
019    
020    import java.util.Comparator;
021    
022    /**
023     * Compares Strings using a {@link StringEncoder}. This comparator is used to sort Strings by an encoding scheme such as
024     * Soundex, Metaphone, etc. This class can come in handy if one need to sort Strings by an encoded form of a name such
025     * as Soundex.
026     * 
027     * @author Apache Software Foundation
028     * @version $Id: StringEncoderComparator.java 1080701 2011-03-11 17:52:27Z ggregory $
029     */
030    public class StringEncoderComparator implements Comparator {
031    
032        /**
033         * Internal encoder instance.
034         */
035        private final StringEncoder stringEncoder;
036    
037        /**
038         * Constructs a new instance.
039         * 
040         * @deprecated Creating an instance without a {@link StringEncoder} leads to a {@link NullPointerException}. Will be
041         *             removed in 2.0.
042         */
043        public StringEncoderComparator() {
044            this.stringEncoder = null; // Trying to use this will cause things to break
045        }
046    
047        /**
048         * Constructs a new instance with the given algorithm.
049         * 
050         * @param stringEncoder
051         *            the StringEncoder used for comparisons.
052         */
053        public StringEncoderComparator(StringEncoder stringEncoder) {
054            this.stringEncoder = stringEncoder;
055        }
056    
057        /**
058         * Compares two strings based not on the strings themselves, but on an encoding of the two strings using the
059         * StringEncoder this Comparator was created with.
060         * 
061         * If an {@link EncoderException} is encountered, return <code>0</code>.
062         * 
063         * @param o1
064         *            the object to compare
065         * @param o2
066         *            the object to compare to
067         * @return the Comparable.compareTo() return code or 0 if an encoding error was caught.
068         * @see Comparable
069         */
070        public int compare(Object o1, Object o2) {
071    
072            int compareCode = 0;
073    
074            try {
075                Comparable s1 = (Comparable) this.stringEncoder.encode(o1);
076                Comparable s2 = (Comparable) this.stringEncoder.encode(o2);
077                compareCode = s1.compareTo(s2);
078            } catch (EncoderException ee) {
079                compareCode = 0;
080            }
081            return compareCode;
082        }
083    
084    }