KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jdesktop > swing > data > 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 JavaDoc encode(Object JavaDoc value, Object JavaDoc 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 JavaDoc decode(String JavaDoc value, Object JavaDoc format) throws ConversionException;
57 }
58
Popular Tags