1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of CosyBeans.
5 *
6 * CosyBeans is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * CosyBeans is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with CosyBeans. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.gui.adapters;
21
22 import java.io.Serializable;
23
24 import com.cosylab.gui.displayers.DataConsumer;
25 import com.cosylab.gui.displayers.DataSource;
26
27
28 /**
29 * <code>Converter</code> interface distinguishes objects that wish to act as
30 * data converters for data flow betwean some arbitrary
31 * <code>DataSource</code> and <code>DataConsumer</code>. To accomplish this
32 * they must represent itself as data consumer to peer data source, thus
33 * implementing <code>DataConsumer</code> interface, and on the other side
34 * accept peer data consumer as data source, thus implementing at the same
35 * time <code>DataSource</code> interface. With such approach it is possible
36 * to chain multiple <code>Converter</code>s in a single data flow line from
37 * source to consumer.
38 *
39 * <p>
40 * Besides implementing <code>DataSource</code> and <code>DataConsumer</code>
41 * interfaces converter must comply to the following contract:
42 * </p>
43 *
44 * <ul>
45 * <li>
46 * When implementing method
47 * <code>DataCosnumer::addConsumer(DataConsumer)</code> the consumer parameter
48 * must be examined for the following:
49 *
50 * <ul>
51 * <li>
52 * If the consumer is <code>NonblockingNumberConsumer</code>, then it comes
53 * from peer data source and wants to receive notifications from this
54 * converter as data source of feedback requests. See <code>Displayer</code>
55 * documentation for details. At the moment only
56 * <code>NonblockingNumberConsumer</code> is supported, later will be also
57 * other <code>Nonblocking<TYPPE>Consumer</code>,
58 * <code>Synchronous<TYPPE>Consumer</code> and
59 * <code>Asynchronous<TYPPE>Consumer</code> interfaces from
60 * <code>con.cosylab.gui.displayers</code> package.
61 * </li>
62 * <li>
63 * Any other consumer is treated as it would normaly be in data source:
64 * </li>
65 * <li>
66 * consumer is added to the list of consumers which will be notified about data
67 * flow events.
68 * </li>
69 * <li>
70 * if consumer implements <code>DataSource</code> interface we must add
71 * <code>NonblockingNumberConsumer</code> implementation, which will dispatch
72 * value change notifications to set of consumers of same type, the ones that
73 * was mentioned above in first bullet.
74 * </li>
75 * </ul>
76 *
77 * </li>
78 * </ul>
79 *
80 * <p>
81 * To clear the things there is simple exemplatory implementation
82 * <code>MultiplierConverter</code>. This example is fully functional and
83 * performs convertions in which any incoming number is multiplied by some
84 * user defined factor. To see how this example converter is used run
85 * <code>con.cosylab.showcase.CalculationPanel</code> showcase demo.
86 * </p>
87 *
88 * <p>
89 * The <code>SimpleConverterSupport</code> class could be used as
90 * implementation base for most of transformations.
91 * </p>
92 *
93 * @author <a href="mailto:igor.kriznar@cosylab.com">Igor Kriznar</a>
94 * @version $Id: Converter.java,v 1.10 2008-04-22 12:31:02 jbobnar Exp $
95 *
96 * @see com.cosylab.gui.displayers.Displayer
97 * @see com.cosylab.gui.displayers.DataSource
98 * @see com.cosylab.gui.displayers.DataConsumer
99 * @see com.cosylab.gui.adapters.SimpleConverterSupport
100 * @see com.cosylab.gui.adapters.MultiplierConverter
101 * @since Feb 14, 2004.
102 */
103 public interface Converter extends DataSource, DataConsumer, Cloneable, Serializable
104 {
105 public Object clone() throws CloneNotSupportedException;
106 }
107
108 /* __oOo__ */