1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.io; 19 20 import java.util.Arrays; 21 22 /** 23 * A writable sink for bytes. 24 * 25 * <p>Most clients will use output streams that write data to the file system 26 * ({@link FileOutputStream}), the network ({@link java.net.Socket#getOutputStream()}/{@link 27 * java.net.HttpURLConnection#getOutputStream()}), or to an in-memory byte array 28 * ({@link ByteArrayOutputStream}). 29 * 30 * <p>Use {@link OutputStreamWriter} to adapt a byte stream like this one into a 31 * character stream. 32 * 33 * <p>Most clients should wrap their output stream with {@link 34 * BufferedOutputStream}. Callers that do only bulk writes may omit buffering. 35 * 36 * <h3>Subclassing OutputStream</h3> 37 * Subclasses that decorate another output stream should consider subclassing 38 * {@link FilterOutputStream}, which delegates all calls to the target output 39 * stream. 40 * 41 * <p>All output stream subclasses should override <strong>both</strong> {@link 42 * #write(int)} and {@link #write(byte[],int,int) write(byte[],int,int)}. The 43 * three argument overload is necessary for bulk access to the data. This is 44 * much more efficient than byte-by-byte access. 45 * 46 * @see InputStream 47 */ 48 public abstract class OutputStream implements Closeable, Flushable { 49 50 /** 51 * Default constructor. 52 */ OutputStream()53 public OutputStream() { 54 } 55 56 /** 57 * Closes this stream. Implementations of this method should free any 58 * resources used by the stream. This implementation does nothing. 59 * 60 * @throws IOException 61 * if an error occurs while closing this stream. 62 */ close()63 public void close() throws IOException { 64 /* empty */ 65 } 66 67 /** 68 * Flushes this stream. Implementations of this method should ensure that 69 * any buffered data is written out. This implementation does nothing. 70 * 71 * @throws IOException 72 * if an error occurs while flushing this stream. 73 */ flush()74 public void flush() throws IOException { 75 /* empty */ 76 } 77 78 /** 79 * Equivalent to {@code write(buffer, 0, buffer.length)}. 80 */ write(byte[] buffer)81 public void write(byte[] buffer) throws IOException { 82 write(buffer, 0, buffer.length); 83 } 84 85 /** 86 * Writes {@code count} bytes from the byte array {@code buffer} starting at 87 * position {@code offset} to this stream. 88 * 89 * @param buffer 90 * the buffer to be written. 91 * @param offset 92 * the start position in {@code buffer} from where to get bytes. 93 * @param count 94 * the number of bytes from {@code buffer} to write to this 95 * stream. 96 * @throws IOException 97 * if an error occurs while writing to this stream. 98 * @throws IndexOutOfBoundsException 99 * if {@code offset < 0} or {@code count < 0}, or if 100 * {@code offset + count} is bigger than the length of 101 * {@code buffer}. 102 */ write(byte[] buffer, int offset, int count)103 public void write(byte[] buffer, int offset, int count) throws IOException { 104 Arrays.checkOffsetAndCount(buffer.length, offset, count); 105 for (int i = offset; i < offset + count; i++) { 106 write(buffer[i]); 107 } 108 } 109 110 /** 111 * Writes a single byte to this stream. Only the least significant byte of 112 * the integer {@code oneByte} is written to the stream. 113 * 114 * @param oneByte 115 * the byte to be written. 116 * @throws IOException 117 * if an error occurs while writing to this stream. 118 */ write(int oneByte)119 public abstract void write(int oneByte) throws IOException; 120 121 /** 122 * Returns true if this writer has encountered and suppressed an error. Used 123 * by PrintStreams as an alternative to checked exceptions. 124 */ checkError()125 boolean checkError() { 126 return false; 127 } 128 } 129