1 /* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. 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 17 package java.lang; 18 19 import java.io.IOException; 20 21 /** 22 * Declares methods to append characters or character sequences. Any class that 23 * implements this interface can receive data formatted by a 24 * {@link java.util.Formatter}. The appended character or character sequence 25 * should be valid according to the rules described in 26 * {@link Character Unicode Character Representation}. 27 * <p> 28 * {@code Appendable} itself does not guarantee thread safety. This 29 * responsibility is up to the implementing class. 30 * <p> 31 * Implementing classes can choose different exception handling mechanism. They 32 * can choose to throw exceptions other than {@code IOException} or they do not 33 * throw any exceptions at all and use error codes instead. 34 */ 35 public interface Appendable { 36 37 /** 38 * Appends the specified character. 39 * 40 * @param c 41 * the character to append. 42 * @return this {@code Appendable}. 43 * @throws IOException 44 * if an I/O error occurs. 45 */ 46 Appendable append(char c) throws IOException; 47 48 /** 49 * Appends the character sequence {@code csq}. Implementation classes may 50 * not append the whole sequence, for example if the target is a buffer with 51 * limited size. 52 * <p> 53 * If {@code csq} is {@code null}, the characters "null" are appended. 54 * 55 * @param csq 56 * the character sequence to append. 57 * @return this {@code Appendable}. 58 * @throws IOException 59 * if an I/O error occurs. 60 */ 61 Appendable append(CharSequence csq) throws IOException; 62 63 /** 64 * Appends a subsequence of {@code csq}. 65 * <p> 66 * If {@code csq} is not {@code null} then calling this method is equivalent 67 * to calling {@code append(csq.subSequence(start, end))}. 68 * <p> 69 * If {@code csq} is {@code null}, the characters "null" are appended. 70 * 71 * @param csq 72 * the character sequence to append. 73 * @param start 74 * the first index of the subsequence of {@code csq} that is 75 * appended. 76 * @param end 77 * the last index of the subsequence of {@code csq} that is 78 * appended. 79 * @return this {@code Appendable}. 80 * @throws IndexOutOfBoundsException 81 * if {@code start < 0}, {@code end < 0}, {@code start > end} 82 * or {@code end} is greater than the length of {@code csq}. 83 * @throws IOException 84 * if an I/O error occurs. 85 */ 86 Appendable append(CharSequence csq, int start, int end) throws IOException; 87 } 88
