OutputStream.java revision a1603838fe9e865575c87982e32c6343740e464c
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 18package java.io; 19 20import java.util.Arrays; 21 22/** 23 * The base class for all output streams. An output stream is a means of writing 24 * data to a target in a byte-wise manner. Most output streams expect the 25 * {@link #flush()} method to be called before closing the stream, to ensure all 26 * data is actually written through. 27 * <p> 28 * This abstract class does not provide a fully working implementation, so it 29 * needs to be subclassed, and at least the {@link #write(int)} method needs to 30 * be overridden. Overriding some of the non-abstract methods is also often 31 * advised, since it might result in higher efficiency. 32 * <p> 33 * Many specialized output streams for purposes like writing to a file already 34 * exist in this package. 35 * 36 * @see InputStream 37 */ 38public abstract class OutputStream implements Closeable, Flushable { 39 40 /** 41 * Default constructor. 42 */ 43 public OutputStream() { 44 super(); 45 } 46 47 /** 48 * Closes this stream. Implementations of this method should free any 49 * resources used by the stream. This implementation does nothing. 50 * 51 * @throws IOException 52 * if an error occurs while closing this stream. 53 */ 54 public void close() throws IOException { 55 /* empty */ 56 } 57 58 /** 59 * Flushes this stream. Implementations of this method should ensure that 60 * any buffered data is written out. This implementation does nothing. 61 * 62 * @throws IOException 63 * if an error occurs while flushing this stream. 64 */ 65 public void flush() throws IOException { 66 /* empty */ 67 } 68 69 /** 70 * Writes the entire contents of the byte array {@code buffer} to this 71 * stream. 72 * 73 * @param buffer 74 * the buffer to be written. 75 * @throws IOException 76 * if an error occurs while writing to this stream. 77 */ 78 public void write(byte[] buffer) throws IOException { 79 // BEGIN android-note 80 // changed array notation to be consistent with the rest of harmony 81 // END android-note 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 */ 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 */ 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 */ 125 boolean checkError() { 126 return false; 127 } 128} 129