hunt.stomp.MessageChannel source code

1 /*
2  * Copyright 2002-2016 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 module hunt.stomp.MessageChannel;
18 
19 import hunt.stomp.Message;
20 
21 /**
22  * Defines methods for sending messages.
23  *
24  * @author Mark Fisher
25  * @since 4.0
26  */
27 // 
28 interface MessageChannel {
29 
30 	/**
31 	 * Constant for sending a message without a prescribed timeout.
32 	 */
33 	enum long INDEFINITE_TIMEOUT = -1;
34 
35 
36 	/**
37 	 * Send a {@link Message} to this channel. If the message is sent successfully,
38 	 * the method returns {@code true}. If the message cannot be sent due to a
39 	 * non-fatal reason, the method returns {@code false}. The method may also
40 	 * throw a RuntimeException in case of non-recoverable errors.
41 	 * <p>This method may block indefinitely, depending on the implementation.
42 	 * To provide a maximum wait time, use {@link #send(Message, long)}.
43 	 * @param message the message to send
44 	 * @return whether or not the message was sent
45 	 */
46 	final bool send(MessageBase message) {
47 		return send(message, INDEFINITE_TIMEOUT);
48 	}
49 
50 	/**
51 	 * Send a message, blocking until either the message is accepted or the
52 	 * specified timeout period elapses.
53 	 * @param message the message to send
54 	 * @param timeout the timeout in milliseconds or {@link #INDEFINITE_TIMEOUT}
55 	 * @return {@code true} if the message is sent, {@code false} if not
56 	 * including a timeout of an interrupt of the send
57 	 */
58 	bool send(MessageBase message, long timeout);
59 
60 }
61 
62 
63 
64 /**
65  * A {@link MessageChannel} from which messages may be actively received through polling.
66  *
67  * @author Mark Fisher
68  * @since 4.0
69  */
70 interface PollableChannel : MessageChannel {
71 
72 	/**
73 	 * Receive a message from this channel, blocking indefinitely if necessary.
74 	 * @return the next available {@link Message} or {@code null} if interrupted
75 	 */
76 	
77 	MessageBase receive();
78 
79 	/**
80 	 * Receive a message from this channel, blocking until either a message is available
81 	 * or the specified timeout period elapses.
82 	 * @param timeout the timeout in milliseconds or {@link MessageChannel#INDEFINITE_TIMEOUT}.
83 	 * @return the next available {@link Message} or {@code null} if the specified timeout
84 	 * period elapses or the message reception is interrupted
85 	 */
86 	
87 	MessageBase receive(long timeout);
88 }
89 
90 
91 
92 /**
93  * A {@link MessageChannel} that maintains a registry of subscribers and invokes
94  * them to handle messages sent through this channel.
95  *
96  * @author Mark Fisher
97  * @since 4.0
98  */
99 interface SubscribableChannel : MessageChannel {
100 
101 	/**
102 	 * Register a message handler.
103 	 * @return {@code true} if the handler was subscribed or {@code false} if it
104 	 * was already subscribed.
105 	 */
106 	bool subscribe(MessageHandler handler);
107 
108 	/**
109 	 * Un-register a message handler.
110 	 * @return {@code true} if the handler was un-registered, or {@code false}
111 	 * if was not registered.
112 	 */
113 	bool unsubscribe(MessageHandler handler);
114 
115 }