View Javadoc

1   //  Copyright 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  package org.jph.channels.router;
15  
16  import org.jph.channels.OutputChannel;
17  import org.jph.collections.predicate.Predicate;
18  
19  import java.util.Iterator;
20  
21  /***
22   * The RoutingOutputChannel is an OutputChannel that receives messages and publishes them
23   * to one or more subscribing outputchannels.
24   * <p/>
25   * Every subscribing outputchannel is registered with a MessagePredicate that checks
26   * if the subscriber wants the message .
27   * <p/>
28   * If there are multiple subscribers for a message, the timeout will decrease after
29   * every offer. So if the original timeout was 1000ms, and the first took 300ms,
30   * 700 ms remains for the second. If the second took 500ms, 200ms remains for the third.
31   * If the third takes 300ms, a timeout will occur (what happens next?)
32   * if the third takes 200ms, 0ms remains for the other ones.
33   * So if the timeout is reduced to 0ms, all the next subscribers will be called with
34   * 0ms.
35   *
36   * @author Peter Veentjer.
37   */
38  public interface RoutingOutputChannel<M> extends OutputChannel<M> {
39  
40  	/***
41  	 * Returns true if this RoutingOutputChannel should stop sending messages to other
42  	 * receivers if one receiver succesfully has received a message.
43  	 */
44  	boolean isStopAfterFirst();
45  
46  	/***
47  	 * Returns the OutputChannel that is used if a message could not be send to a receiver.
48  	 */
49  	OutputChannel<M> getFailOutputChannel();
50  
51  	/***
52  	 * Returns all the OutRouterEntries.
53  	 */
54  	Iterator<OutRouterEntry<M>> entries();
55  
56  	/***
57  	 * @param entry
58  	 * @throws NullPointerException if entry is null.
59  	 */
60  	void add(OutRouterEntry<M> entry);
61  
62  	/***
63  	 * Adds the subscriber to this RoutingOutputChannel. The subscriber will
64  	 * receive all messages this RoutingOutputChannel receives.
65  	 *
66  	 * @param subscriber the subscriber to add. If the subscriber already is a subscriber for
67  	 *                   this RoutingOutputChannel, it is not added again.
68  	 * @throws NullPointerException if subscriber is null.
69  	 */
70  	void subscribe(OutputChannel<M> subscriber);
71  
72  	/***
73  	 * Adds a subscriber to this RoutingOutputChannel. The subscriber only receives
74  	 * messages that where checked by a MessagePredicate. This way you can listen
75  	 * to certain messages.
76  	 *
77  	 * @param predicate  if the predicate is null, the TrueMessagePredicate is used by default.
78  	 * @param subscriber
79  	 * @throws NullPointerException subscriber is null.
80  	 */
81  	void subscribe(Predicate predicate, OutputChannel<M> subscriber);
82  }