View Javadoc

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 }