001/*
002 * $Id: ObjectToStringConverter.java 4045 2011-07-19 18:39:17Z kschaefe $
003 *
004 * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle,
005 * Santa Clara, California 95054, U.S.A. All rights reserved.
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this library; if not, write to the Free Software
019 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
020 */
021package org.jdesktop.swingx.autocomplete;
022
023/**
024 * <p>
025 * This class is used to provide string representations for objects when
026 * doing automatic completion.
027 * </p><p>
028 * A class inherited from this class could be used, when the object's
029 * <tt>toString</tt> method is not appropriate for automatic completion.
030 * </p><p>
031 * An example for i18n:
032 * </p><p>
033 * <code><pre>
034 * public class I18NStringConverter extends ObjectToStringConverter {
035 *   ResourceBundle bundle;
036 *
037 *   public I18NStringConverter(ResourceBundle bundle) {
038 *     this.bundle = bundle;
039 *   }
040 *
041 *   public String getPreferredStringForItem(Object item) {
042 *     return item==null ? null : bundle.getString(item.toString());
043 *   }
044 * }
045 * </code></pre>
046 * </p><p>
047 * It's also possible to return more than one string representation. The
048 * following example shows a converter that will allow a user to choose an
049 * airport using either the airport's full description (<tt>toString()</tt>) or
050 * its ICAO/IATA code:
051 * </p><p>
052 * <pre><code>
053 * public class AirportConverter extends ObjectToStringConverter {
054 *
055 *   public String[] getPossibleStringsForItem(Object item) {
056 *     if (item==null) return new String[0];
057 *     if (!(item instanceof Airport)) throw new IllegalArgumentException();
058 *     Airport airport = (Airport) item;
059 *     return new String[]{airport.toString(), airport.icaoCode, airport.iataCode};
060 *   }
061 *       
062 *   public String getPreferredStringForItem(Object item) {
063 *     return item==null?null:getPossibleStringsForItem(item)[0];
064 *   }
065 * }
066 * </code></pre>
067 * </p>
068 * @author Thomas Bierhance
069 */
070public abstract class ObjectToStringConverter {
071    
072    /**
073     * Returns all possible <tt>String</tt> representations for a given item.
074     * The default implementation wraps the method <tt>getPreferredStringForItem</tt>.
075     * It returns an empty array, if the wrapped method returns <tt>null</tt>. Otherwise
076     * it returns a one dimensional array containing the wrapped method's return value.
077     *
078     * @param item the item to convert
079     * @return possible <tt>String</tt> representation for the given item.
080     */
081    public String[] getPossibleStringsForItem(Object item) {
082        String preferred = getPreferredStringForItem(item);
083        return preferred == null ? new String[0] : new String[] { preferred };
084    }
085    
086    /**
087     * Returns the preferred <tt>String</tt> representations for a given item.
088     * @param item the item to convert
089     * @return the preferred <tt>String</tt> representation for the given item.
090     */
091    public abstract String getPreferredStringForItem(Object item);
092    
093    /**
094     * This field contains the default implementation, that returns <tt>item.toString()</tt>
095     * for any item <tt>!=null</tt>. For any item <tt>==null</tt>, it returns <tt>null</tt> as well.
096     */
097    public static final ObjectToStringConverter DEFAULT_IMPLEMENTATION = new DefaultObjectToStringConverter();
098    
099    private static class DefaultObjectToStringConverter extends ObjectToStringConverter {
100        @Override
101        public String getPreferredStringForItem(Object item) {
102            return item==null ? null : item.toString();
103        }
104    }    
105}