jaroslav@59: /* jaroslav@59: * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved. jaroslav@59: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@59: * jaroslav@59: * This code is free software; you can redistribute it and/or modify it jaroslav@59: * under the terms of the GNU General Public License version 2 only, as jaroslav@59: * published by the Free Software Foundation. Oracle designates this jaroslav@59: * particular file as subject to the "Classpath" exception as provided jaroslav@59: * by Oracle in the LICENSE file that accompanied this code. jaroslav@59: * jaroslav@59: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@59: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@59: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@59: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@59: * accompanied this code). jaroslav@59: * jaroslav@59: * You should have received a copy of the GNU General Public License version jaroslav@59: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@59: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@59: * jaroslav@59: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@59: * or visit www.oracle.com if you need additional information or have any jaroslav@59: * questions. jaroslav@59: */ jaroslav@59: jaroslav@59: package java.lang; jaroslav@59: jaroslav@59: import java.io.IOException; jaroslav@59: jaroslav@59: /** jaroslav@59: * An object to which char sequences and values can be appended. The jaroslav@59: * Appendable interface must be implemented by any class whose jaroslav@59: * instances are intended to receive formatted output from a {@link jaroslav@59: * java.util.Formatter}. jaroslav@59: * jaroslav@59: *

The characters to be appended should be valid Unicode characters as jaroslav@59: * described in Unicode Character jaroslav@59: * Representation. Note that supplementary characters may be composed of jaroslav@59: * multiple 16-bit char values. jaroslav@59: * jaroslav@59: *

Appendables are not necessarily safe for multithreaded access. Thread jaroslav@59: * safety is the responsibility of classes that extend and implement this jaroslav@59: * interface. jaroslav@59: * jaroslav@59: *

Since this interface may be implemented by existing classes jaroslav@59: * with different styles of error handling there is no guarantee that jaroslav@59: * errors will be propagated to the invoker. jaroslav@59: * jaroslav@59: * @since 1.5 jaroslav@59: */ jaroslav@59: public interface Appendable { jaroslav@59: jaroslav@59: /** jaroslav@59: * Appends the specified character sequence to this Appendable. jaroslav@59: * jaroslav@59: *

Depending on which class implements the character sequence jaroslav@59: * csq, the entire sequence may not be appended. For jaroslav@59: * instance, if csq is a {@link java.nio.CharBuffer} then jaroslav@59: * the subsequence to append is defined by the buffer's position and limit. jaroslav@59: * jaroslav@59: * @param csq jaroslav@59: * The character sequence to append. If csq is jaroslav@59: * null, then the four characters "null" are jaroslav@59: * appended to this Appendable. jaroslav@59: * jaroslav@59: * @return A reference to this Appendable jaroslav@59: * jaroslav@59: * @throws IOException jaroslav@59: * If an I/O error occurs jaroslav@59: */ jaroslav@59: Appendable append(CharSequence csq) throws IOException; jaroslav@59: jaroslav@59: /** jaroslav@59: * Appends a subsequence of the specified character sequence to this jaroslav@59: * Appendable. jaroslav@59: * jaroslav@59: *

An invocation of this method of the form out.append(csq, start, jaroslav@59: * end) when csq is not null, behaves in jaroslav@59: * exactly the same way as the invocation jaroslav@59: * jaroslav@59: * 

jaroslav@59:      *     out.append(csq.subSequence(start, end))
jaroslav@59: * jaroslav@59: * @param csq jaroslav@59: * The character sequence from which a subsequence will be jaroslav@59: * appended. If csq is null, then characters jaroslav@59: * will be appended as if csq contained the four jaroslav@59: * characters "null". jaroslav@59: * jaroslav@59: * @param start jaroslav@59: * The index of the first character in the subsequence jaroslav@59: * jaroslav@59: * @param end jaroslav@59: * The index of the character following the last character in the jaroslav@59: * subsequence jaroslav@59: * jaroslav@59: * @return A reference to this Appendable jaroslav@59: * jaroslav@59: * @throws IndexOutOfBoundsException jaroslav@59: * If start or end are negative, start jaroslav@59: * is greater than end, or end is greater than jaroslav@59: * csq.length() jaroslav@59: * jaroslav@59: * @throws IOException jaroslav@59: * If an I/O error occurs jaroslav@59: */ jaroslav@59: Appendable append(CharSequence csq, int start, int end) throws IOException; jaroslav@59: jaroslav@59: /** jaroslav@59: * Appends the specified character to this Appendable. jaroslav@59: * jaroslav@59: * @param c jaroslav@59: * The character to append jaroslav@59: * jaroslav@59: * @return A reference to this Appendable jaroslav@59: * jaroslav@59: * @throws IOException jaroslav@59: * If an I/O error occurs jaroslav@59: */ jaroslav@59: Appendable append(char c) throws IOException; jaroslav@59: }