01: /* ====================================================================
02: The Jicarilla Software License
03:
04: Copyright (c) 2003 Leo Simons.
05: All rights reserved.
06:
07: Permission is hereby granted, free of charge, to any person obtaining
08: a copy of this software and associated documentation files (the
09: "Software"), to deal in the Software without restriction, including
10: without limitation the rights to use, copy, modify, merge, publish,
11: distribute, sublicense, and/or sell copies of the Software, and to
12: permit persons to whom the Software is furnished to do so, subject to
13: the following conditions:
14:
15: The above copyright notice and this permission notice shall be
16: included in all copies or substantial portions of the Software.
17:
18: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
21: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
22: CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23: TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
24: SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25: ==================================================================== */
26: package org.jicarilla.plumbing;
27:
28: import org.jicarilla.lang.Selector;
29:
30: /**
31: * <p>Redirects received messages to other sinks based on a selection algoritm
32: * that is determined by the set of selectors provided for each of the
33: * targettable sinks. In diagram form:</p>
34: *
35: * <pre>
36: * +------------------------+
37: * |Screener |
38: * addSink() | +---------++---------+|
39: * ------> |/-|Selector ||Sink ||
40: * || +---------++---------+|
41: * || +---------++---------+|
42: * put() / offer() --->-|Selector ||Sink ||
43: * || +---------++---------+|
44: * || +---------++---------+|
45: * |\-|Selector ||Sink ||
46: * | +---------++---------+|
47: * +------------------------+
48: * </pre>
49: *
50: * <p>In other words, the <code>Screener</code> is a generic multiway
51: * redirector.</p>
52: *
53: * <p>Care should be taken to make sure that the Selectors used can work with
54: * the messages that will be fed through the screener (of course).</p>
55: *
56: * <p>Note that the <code>Screener</code> is very similar to the {@link
57: * Multicaster Multicaster}: where the multicaster sends a received message to
58: * all connected sinks, the Screener sends it to only one sink.</p>
59: *
60: * <p>Also note that the <code>Alternator</code> is also very similar to the
61: * {@link Screener screener}: where the alternator decides which connected sink
62: * should receive the message randomly, the screener does so based on a
63: * user-provided configuration.</p>
64: *
65: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
66: * @version $Id: Screener.java,v 1.2 2004/03/23 13:37:58 lsimons Exp $
67: */
68: public interface Screener extends Sink {
69: /**
70: * <p>Add a sink that will receive messages from this screener. A sink may
71: * receive messages sent to this screener if and only if the provided
72: * selector returns true upon calling its select() method with the message
73: * being the argument, but it is not guaranteed that it will always receive
74: * those messages.</p>
75: *
76: * <p>The policy used for determining to what selector/sink pair an
77: * particular message will be sent is implementation-dependent.</p>
78: *
79: * @param selector the selector that governs what messages the sink will
80: * receive
81: * @param sink the sink that will receive messages
82: */
83: void addSink(Selector selector, Sink sink);
84: }
|