1 /*
2 * Copyright 2006 Simon Raess
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 package net.sf.beep4j;
17
18 /**
19 * A ResponseHandler is passed to the application whenever a message
20 * of type MSG is received.
21 * (see {@link ChannelHandler#receiveRequest(Channel, Message, ResponseHandler)})
22 * It allows the application to reply to the received message.
23 * According to section 2.1.1 of the BEEP specification (RFC 3080) the allowed
24 * exchange styles are:
25 *
26 * <ul>
27 * <li>MSG/RPY: positive reply, one-to-one exchange</li>
28 * <li>MSG/ERR: negative reply, one-to-one exchange</li>
29 * <li>MSG/ANS: zero or more ANS messages terminated with a NUL message, many-to-one exchange</li>
30 * </ul>
31 *
32 * @author Simon Raess
33 */
34 public interface Reply {
35
36 /**
37 * Creates a new MessageBuilder object that can be used to create
38 * one new message.
39 *
40 * @return a new MessageBuilder object
41 */
42 MessageBuilder createMessageBuilder();
43
44 /**
45 * Sends a reply of type ANS. This method can be called zero or more
46 * times. To complete the response the method {@link #sendNUL()} has
47 * to be invoked.
48 *
49 * @param message the response
50 * @throws IllegalArgumentException if the message is null
51 * @throws IllegalStateException if a response has already been sent
52 */
53 void sendANS(Message message);
54
55 /**
56 * Sends a reply of type NUL. This method must be called to complete a
57 * one-to-many exchange.
58 *
59 * @throws IllegalStateException if a response has already been sent
60 */
61 void sendNUL();
62
63 /**
64 * Sends a negative reply of type ERR. This method can only be called exactly once.
65 *
66 * @param message the response
67 * @throws IllegalArgumentException if the message is null
68 * @throws IllegalStateException if a response has already been sent
69 */
70 void sendERR(Message message);
71
72 /**
73 * Sends a positive reply of type RPY. This method can only be called exactly once.
74 *
75 * @param message the response
76 * @throws IllegalArgumentException if the message is null
77 * @throws IllegalStateException if a response has already been sent
78 */
79 void sendRPY(Message message);
80
81 }