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.beans.PropertyVetoException;
23 import java.util.Map;
24
25 import com.cosylab.gui.displayers.DataSource;
26
27 /**
28 * <code>DataSourceJoint</code> combines several DataSources and dispatch all
29 * their data in a prescribed manner. Each DataSource should be added to this
30 * joint together with an identifer that specifies what this joint should do
31 * with the data received from that particular source. The first DataSource in
32 * the joint should always have an identifier FIRST_IN_A_ROW, following by data
33 * sources with any other operation identifier. There can be only one source
34 * with identifier FIRST_IN_A_ROW.
35 * <p>
36 * When a new <code>DataSource</code> is added it should be the last in the
37 * chain of all data sources if not specified otherwise. Value from each
38 * <code>DataSource</code> should meet an arythmetic operation with the value
39 * calculated from sources that are higher up in the chain (were added to this
40 * joint earlier).
41 * </p>
42 * <p>
43 * addDataSource(source1, FIRST_IN_A_ROW);
44 * addDataSource(source2, ADD);
45 * addDataSource(source3, MULTIPLY);
46 * should give a result of (source1 + source2)* source3.
47 * </p>
48 *
49 * @author Jaka Bobnar, Cosylab
50 *
51 * @param <T> type of DataSources added to this joint
52 */
53 public interface DataSourceJoint<T extends DataSource> extends DataSource {
54
55 /** Identifier for the first DataSource */
56 public static final String FIRST_IN_A_ROW = "first";
57
58 /** Identifier for multiplication */
59 public static final String MULTIPLY = "multiply";
60
61 /** Identifier for division */
62 public static final String DIVIDE = "divide";
63
64 /** Identifier for addition */
65 public static final String ADD = "add";
66
67 /** Identifier for substraction */
68 public static final String SUBSTRACT = "substract";
69
70 /**
71 * Adds a <code>DataSource</code> to the chain of source as the last
72 * dataSource. The operation between added DataSource and the existing chain
73 * is specified by operation parameter, which can be one of the public
74 * identifiers.
75 *
76 * @param dataSource
77 * @param operation
78 * @throws IllegalArgumentException
79 * when a given datasource have operation FIRST_IN_A_ROW and a
80 * DataSource with this identifier already exists
81 */
82 public void addDataSource(T dataSource, String operation)
83 throws IllegalArgumentException, PropertyVetoException;
84
85 /**
86 * Adds a <code>DataSource</code> to the chain of source at the position
87 * specified by index. The operation between added DataSource and the
88 * existing chain is specified by operation parameter, which can be one of
89 * the public identifiers. The FIRST_IN_A_ROW is specified by index 0. If a
90 * DataSource is added as first in a row it would replace the existing first
91 * DataSource and its identifier should be automatically changed to
92 * FIRST_IN_A_ROW if a different one is given.
93 *
94 * @param dataSource
95 * @param operation
96 * @param index
97 * @throws IllegalArgumentException
98 * when a given index is invalid (larger than the number of data
99 * sources in this joint)
100 */
101 public void addDataSource(T dataSource, String operation, int index)
102 throws IllegalArgumentException, PropertyVetoException;
103
104 /**
105 * Removes the dataSource from this joint. When a single
106 * <code>DataSource</code> is removed, it should not have any effects on
107 * the complete chain of sources. The sources that are further down in the
108 * chain should be moves upward. Method should return identifier of the
109 * operation associated with the removed data source.
110 *
111 * @param dataSource DataSource to be removed
112 * @return operation associated with the data source
113 */
114 public String removeDataSource(T dataSource);
115
116 /**
117 * Returns a Map of all dataSources and their identifiers. The map is
118 * expected to use data sources as keys and operation identifiers as values.
119 * The order of data sources should be preserved.
120 *
121 * @return a map of all data sources
122 */
123 public Map<T, String> getDataSources();
124 }