1 /* 2 * @(#)Appendable.java 1.3 04/07/16 3 * 4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.lang; 9 10 import java.io.IOException; 11 12 /** 13 * An object to which <tt>char</tt> sequences and values can be appended. The 14 * <tt>Appendable</tt> interface must be implemented by any class whose 15 * instances are intended to receive formatted output from a {@link 16 * java.util.Formatter}. 17 * 18 * <p> The characters to be appended should be valid Unicode characters as 19 * described in <a HREF="Character.html#unicode">Unicode Character 20 * Representation</a>. Note that supplementary characters may be composed of 21 * multiple 16-bit <tt>char</tt> values. 22 * 23 * <p> Appendables are not necessarily safe for multithreaded access. Thread 24 * safety is the responsibility of classes that extend and implement this 25 * interface. 26 * 27 * <p> Since this interface may be implemented by existing classes 28 * with different styles of error handling there is no guarantee that 29 * errors will be propagated to the invoker. 30 * 31 * @version 1.3, 07/16/04 32 * @since 1.5 33 */ 34 public interface Appendable { 35 36 /** 37 * Appends the specified character sequence to this <tt>Appendable</tt>. 38 * 39 * <p> Depending on which class implements the character sequence 40 * <tt>csq</tt>, the entire sequence may not be appended. For 41 * instance, if <tt>csq</tt> is a {@link java.nio.CharBuffer} then 42 * the subsequence to append is defined by the buffer's position and limit. 43 * 44 * @param csq 45 * The character sequence to append. If <tt>csq</tt> is 46 * <tt>null</tt>, then the four characters <tt>"null"</tt> are 47 * appended to this Appendable. 48 * 49 * @return A reference to this <tt>Appendable</tt> 50 * 51 * @throws IOException 52 * If an I/O error occurs 53 */ 54 Appendable append(CharSequence csq) throws IOException; 55 56 /** 57 * Appends a subsequence of the specified character sequence to this 58 * <tt>Appendable</tt>. 59 * 60 * <p> An invocation of this method of the form <tt>out.append(csq, start, 61 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in 62 * exactly the same way as the invocation 63 * 64 * <pre> 65 * out.append(csq.subSequence(start, end)) </pre> 66 * 67 * @param csq 68 * The character sequence from which a subsequence will be 69 * appended. If <tt>csq</tt> is <tt>null</tt>, then characters 70 * will be appended as if <tt>csq</tt> contained the four 71 * characters <tt>"null"</tt>. 72 * 73 * @param start 74 * The index of the first character in the subsequence 75 * 76 * @param end 77 * The index of the character following the last character in the 78 * subsequence 79 * 80 * @return A reference to this <tt>Appendable</tt> 81 * 82 * @throws IndexOutOfBoundsException 83 * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt> 84 * is greater than <tt>end</tt>, or <tt>end</tt> is greater than 85 * <tt>csq.length()</tt> 86 * 87 * @throws IOException 88 * If an I/O error occurs 89 */ 90 Appendable append(CharSequence csq, int start, int end) throws IOException; 91 92 /** 93 * Appends the specified character to this <tt>Appendable</tt>. 94 * 95 * @param c 96 * The character to append 97 * 98 * @return A reference to this <tt>Appendable</tt> 99 * 100 * @throws IOException 101 * If an I/O error occurs 102 */ 103 Appendable append(char c) throws IOException; 104 } 105