Converter


1   /*
2    * $Id: Converter.java,v 1.2 2004/09/07 18:16:01 davidson1 Exp $
3    *
4    * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle,
5    * Santa Clara, California 95054, U.S.A. All rights reserved.
6    */
7   
8   package org.jdesktop.swing.data;
9   
10  /**
11   * Interface for defining objects which perform bi-directional conversion
12   * between string values and Java objects.  A unified conversion interface
13   * is required for serializing and de-serializing data values to and from
14   * a textual representation, which is a common requirement when interacting
15   * with a network or web-based data source.
16   * <p>
17   * For many Java classes (Date, Color, etc), an instance may be
18   * represented in a variety of string formats, hence both conversion methods
19   * take an optional <code>format</code> parameter for specifying an
20   * unambiguous string format to use during conversion.  A Converter class
21   * must document the format classes it supports and must also accept a
22   * <code>null</code> value for the <code>format</code> parameter,
23   * in which case a suitable and well-documented default should be used.
24   * Converters should support standard formats whenever possible.</p>
25   *
26   * @see Converters#get
27   *
28   * @author Amy Fowler
29   * @version 1.0
30   */
31  public interface Converter {
32      /**@todo aim: should converters honor null/"" values? */
33      /**
34       * Converts the specified Object value to a string representation.
35       * The value must be an instance of the class associated with
36       * this converter, else an exception will be thrown.
37       * @param value the object to be converted
38       * @param format object containing string format information, or null
39       *        if format information is either not relevant or unspecified
40       * @return String containing the converted string representation of the
41       *         value
42       * @throws ConversionException if the conversion could not be performed
43       */
44      String   encode(Object   value, Object   format) throws ConversionException;
45  
46      /**
47       * Converts the specified String value to an object that is an
48       * instance of the class associated with this converter instance.
49       * @param value String object to be converted
50       * @param format object containing string format information, or null
51       *        if format information is either not relevant or unspecified
52       * @return Object which contains the converted value as an instance of
53       *         the class associated with this converter
54       * @throws ConversionException if the conversion could not be performed
55       */
56      Object   decode(String   value, Object   format) throws ConversionException;
57  }
58
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags