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.plumbing.Multicaster;
29: import org.jicarilla.plumbing.Sink;
30:
31: /**
32: * <p>Distribute messages across multiple sinks, choosing which sink to send
33: * any particular message to randomly, but weighing in the relative sink
34: * priority. Exactly how that weighing is done is implementation-dependent. In
35: * diagram form:</p>
36: *
37: * <pre>
38: * +-------------+
39: * |Alternator |
40: * addSink() | +---------+|
41: * ------> |/-|Sink ||
42: * || +---------+|
43: * || +---------+|
44: * put() / offer() --->-|Sink ||
45: * || +---------+|
46: * || +---------+|
47: * |\-|Sink ||
48: * | +---------+|
49: * +-------------+
50: * </pre>
51: *
52: * <p>Note that the <code>Alternator</code> is very similar to the {@link
53: * Multicaster Multicaster}: where the multicaster sends a received message to
54: * all connected sinks, the Alternator sends it to only one sink.</p>
55: *
56: * <p>Also note that the <code>Alternator</code> is also very similar to the
57: * {@link org.jicarilla.plumbing.Screener screener}: where the alternator decides which connected sink
58: * should receive the message randomly, the screener does so based on a
59: * user-provided configuration.</p>
60: *
61: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
62: * @version $Id: Alternator.java,v 1.1 2004/03/22 21:20:13 lsimons Exp $
63: */
64: public interface Alternator extends Multicaster {
65: /** The minimum priority of any sink. */
66: public final static int MIN_PRIORITY = 1;
67: /** The maximum priority of any sink. */
68: public final static int MAX_PRIORITY = 10;
69: /** The priority assigned to any sink by default. */
70: public final static int DEFAULT_PRIORITY = 5;
71:
72: /**
73: * Add a sink which will be a recipient of some of the messages this
74: * alternator receives (as determined by the 'randomness' algorithm of this
75: * alternator).
76: *
77: * @param sink the sink that will receive some of the messages
78: */
79: void addSink(Sink sink);
80:
81: /**
82: * Add a sink (which will be a recipient of messages), with the
83: * 'randomness' algorithm of this alternator influenced by the specified
84: * priority.
85: *
86: * @param sink
87: * @param priority number specifying the relative priority of this sink.
88: * Bigger number means higher priority. Minimum value of 1, maximum value
89: * of 10.
90: */
91: void addSink(Sink sink, int priority);
92: }
|