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}