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.displayers;
21
22 import java.util.Map;
23
24
25 /**
26 * <p>
27 * <code>DataConsumer</code> interface defines receiver for udates of
28 *
29 * <ul>
30 * <li>
31 * dynamic value change
32 * </li>
33 * <li>
34 * dynamic value quality (or state) change
35 * </li>
36 * <li>
37 * dynamic value characteristics
38 * </li>
39 * </ul>
40 * </p>
41 *
42 * <p>
43 * Combunation of daata consumer and data source is data pipe. It could be used
44 * for data riltering or editing.
45 * </p>
46 *
47 * <p>
48 * By default all data consumers are synchronous: they returns method call when
49 * update was successfull of fail with exception.
50 * </p>
51 *
52 * @author <a href="mailto:igor.kriznar@cosylab.com">Igor Kriznar</a>
53 * @version $Id: DataConsumer.java,v 1.4 2008-04-22 12:31:02 jbobnar Exp $
54 *
55 * @since Nov 24, 2003.
56 */
57 public interface DataConsumer
58 {
59 /**
60 * <p>
61 * Returns data consumer for requested data consumer type. If this data
62 * consumer does not support required data consumer, <code>null</code> is
63 * returned.
64 * </p>
65 *
66 * <p>
67 * If this data cosnumer does not support specific data consumer type, then
68 * it means, that it is not desirable to cast data of that type to any by
69 * this consumer supported data consumer types.
70 * </p>
71 *
72 * @param type Class of specific data consumer (e.g. DoubleConsumer)
73 *
74 * @return implementation of required data consumer or <code>null</code> if
75 * not supported
76 */
77 public <D extends DataConsumer> D getDataConsumer(Class<D> type);
78
79 /**
80 * Returns the implementation of default consumer type supported by this
81 * data consumer.
82 *
83 * @return the implementation of default consumer type supported by this
84 * data consumer
85 */
86 public DataConsumer getDefaultDataConsumer();
87
88 /**
89 * Push data state (quality) update change for dynamic value. Usually
90 * called by data source.
91 *
92 * @param state new data state(quality) descriptor
93 */
94 public void updateDataState(DataState state);
95
96 /**
97 * Sets new dynamic value characteristics to this data consumer. This is
98 * usually called only at initializaation, before first data state or
99 * value is updated. Usually carries characteristics such as value minimum
100 * or maximum. Name and meaning of atributes is defined with contract
101 * betwean data consumer and source implementation.
102 *
103 * @param characteristics the <code>Map</code> with attri
104 */
105 public void setCharacteristics(Map characteristics);
106
107 /**
108 * Returns name of this data consumer.
109 *
110 * @return the name of this data consumer
111 */
112 public String getName();
113
114 /**
115 * Resturns array with names of supported characteristics. Data source can
116 * use this method to optimize setting characteristics to this data
117 * consumer. If arrray of length 0 is return, then consumer does not need
118 * or support any characteristic. If <code>null</code> is returned, than
119 * consumer expect all existing characteristics from data source.
120 *
121 * @return array with names of supported characteristics
122 */
123 public String[] getSupportedCharacteristics();
124
125 /**
126 * Returns array of supported data consumer types, which can be used as
127 * parameter and returnned with <code>getDataCosnumer(Class)</code>
128 * method.
129 *
130 * @return array of supported data consumer types
131 */
132 public Class<DataConsumer>[] getSupportedConsumerTypes();
133 }
134
135 /* __oOo__ */