001: /* Licensed to the Apache Software Foundation (ASF) under one or more
002: * contributor license agreements. See the NOTICE file distributed with
003: * this work for additional information regarding copyright ownership.
004: * The ASF licenses this file to You under the Apache License, Version 2.0
005: * (the "License"); you may not use this file except in compliance with
006: * the License. You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package java.lang;
018:
019: import java.io.IOException;
020:
021: /**
022: * Appendable is an object used to append character or character sequence. Any
023: * class implements this interface can receive data formatted by
024: * <code>Formatter</code>. The appended character or character sequence
025: * should be valid according to the rules described
026: * <code>Unicode Character Representation</code>.
027: * <p>
028: * Appendable itself does not guarantee thread safety. This responsibility is up
029: * to the implementing class.
030: * </p>
031: * <p>
032: * The implementing class can choose different exception handling mechanism. It
033: * can choose to throw exceptions other than IOException but which must be
034: * compatible with IOException, or does not throw any exceptions at all and use
035: * error code instead. All in all, the implementing class does not guarantee to
036: * propagate the exception declared by this interface.
037: * </p>
038: */
039: public interface Appendable {
040:
041: /**
042: * Append the given character.
043: *
044: * @param c
045: * the character to append
046: * @return this <code>Appendable</code>
047: * @throws IOException
048: * if some I/O operation fails
049: */
050: Appendable append(char c) throws IOException;
051:
052: /**
053: * Append the given <code>CharSequence</code>.
054: * <p>
055: * The behaviour of this method depends on the implementation class of
056: * <code>Appendable</code>.
057: * </p>
058: * <p>
059: * If the give <code>CharSequence</code> is null, the sequence is treated
060: * as String "null".
061: * </p>
062: *
063: * @param csq
064: * the <code>CharSequence</code> to be append
065: * @return this <code>Appendable</code>
066: * @throws IOException
067: * if some I/O operation fails
068: */
069: Appendable append(CharSequence csq) throws IOException;
070:
071: /**
072: * Append part of the given <code>CharSequence</code>.
073: *
074: * If the given <code>CharSequence</code> is not null, this method behaves
075: * same as the following statement:
076: *
077: * <pre>
078: * out.append(csq.subSequence(start, end))
079: * </pre>
080: *
081: * If the give <code>CharSequence</code> is null, the sequence is treated
082: * as String "null".
083: *
084: * @param csq
085: * the <code>CharSequence</code> to be append
086: * @param start
087: * the index to specify the start position of
088: * <code>CharSequence</code> to be append, must be
089: * non-negative, and not larger than the <code>end</code>
090: * @param end
091: * the index to specify the end position of
092: * <code>CharSequence</code> to be append, must be
093: * non-negative, and not larger than the size of <code>csq</code>
094: * @return this <code>Appendable</code>
095: * @throws IOException
096: * if some I/O operation fails
097: * @throws IndexOutOfBoundsException
098: * if the start or end is illegal
099: */
100: Appendable append(CharSequence csq, int start, int end)
101: throws IOException;
102: }
|