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 }