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 import java.io.OutputStream;
19 import java.io.Writer;
20 import java.nio.ByteBuffer;
21
22 /**
23 * A MessageBuilder allows to easily create Message objects. It has methods
24 * to set MIME headers. The content type and character encoding can be
25 * set with convenience methods.
26 *
27 * <p>To write something into the message you can either get the output
28 * stream or a writer. If you want to write binary data you should use
29 * the output stream. Otherwise, use the writer as it uses the correct
30 * charset encoder.</p>
31 *
32 * <p>Finally, you can retrieve the completed message with the
33 * {@link #getMessage()} method.</p>
34 *
35 * <p>An example of a common use case is given below:</p>
36 *
37 * <pre>
38 * MessageBuilder builder = ...;
39 * builder.setContentType("application", "beep+xml");
40 * builder.setCharacterEncoding("UTF-8");
41 * PrintWriter writer = new PrintWriter(builder.getWriter());
42 * writer.println("<ok />");
43 * Message message = writer.getMessage();
44 * </pre>
45 *
46 * @author Simon Raess
47 */
48 public interface MessageBuilder {
49
50 /**
51 * Sets the content type of the message.
52 *
53 * @param type the type
54 * @param subtype the subtype
55 */
56 void setContentType(String type, String subtype);
57
58 /**
59 * Sets the character encoding used by the message.
60 *
61 * @param charset the charset
62 */
63 void setCharsetName(String charset);
64
65 /**
66 * Adds an arbitrary header field.
67 *
68 * @param name the name of the header
69 * @param value the value
70 */
71 void addHeader(String name, String value);
72
73 /**
74 * Gets the underlying OutputStream that can be used to write
75 * binary messages.
76 *
77 * @return the OutputStream
78 */
79 OutputStream getOutputStream();
80
81 /**
82 * Gets the underlying Writer that can be used to write textual
83 * messages.
84 *
85 * @return the Writer
86 */
87 Writer getWriter();
88
89 /**
90 * Allocates a ByteBuffer into which the message content can be
91 * written.
92 *
93 * @param size the size of the ByteBuffer
94 * @return an allocated ByteBuffer
95 */
96 ByteBuffer getContentBuffer(int size);
97
98 /**
99 * Retrieves the resulting message object.
100 *
101 * @return the Message object
102 */
103 Message getMessage();
104
105 }