001 /*
002 * $Id: ObjectToStringConverter.java 3100 2008-10-14 22:33:10Z rah003 $
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 */
021 package 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 */
070 public 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 public String getPreferredStringForItem(Object item) {
101 return item==null ? null : item.toString();
102 }
103 }
104 }