The characters to be appended should be valid Unicode characters as + * described in Unicode Character + * Representation. Note that supplementary characters may be composed of + * multiple 16-bit char values. + * + *
Appendables are not necessarily safe for multithreaded access. Thread + * safety is the responsibility of classes that extend and implement this + * interface. + * + *
Since this interface may be implemented by existing classes + * with different styles of error handling there is no guarantee that + * errors will be propagated to the invoker. + * + * @since 1.5 + */ +public interface Appendable { + + /** + * Appends the specified character sequence to this Appendable. + * + *
Depending on which class implements the character sequence + * csq, the entire sequence may not be appended. For + * instance, if csq is a {@link java.nio.CharBuffer} then + * the subsequence to append is defined by the buffer's position and limit. + * + * @param csq + * The character sequence to append. If csq is + * null, then the four characters "null" are + * appended to this Appendable. + * + * @return A reference to this Appendable + * + * @throws IOException + * If an I/O error occurs + */ + Appendable append(CharSequence csq) throws IOException; + + /** + * Appends a subsequence of the specified character sequence to this + * Appendable. + * + *
An invocation of this method of the form out.append(csq, start, + * end) when csq is not null, behaves in + * exactly the same way as the invocation + * + *
+ * out.append(csq.subSequence(start, end))+ * + * @param csq + * The character sequence from which a subsequence will be + * appended. If csq is null, then characters + * will be appended as if csq contained the four + * characters "null". + * + * @param start + * The index of the first character in the subsequence + * + * @param end + * The index of the character following the last character in the + * subsequence + * + * @return A reference to this Appendable + * + * @throws IndexOutOfBoundsException + * If start or end are negative, start + * is greater than end, or end is greater than + * csq.length() + * + * @throws IOException + * If an I/O error occurs + */ + Appendable append(CharSequence csq, int start, int end) throws IOException; + + /** + * Appends the specified character to this Appendable. + * + * @param c + * The character to append + * + * @return A reference to this Appendable + * + * @throws IOException + * If an I/O error occurs + */ + Appendable append(char c) throws IOException; +}