OutputStream.java revision fd6bb3510c2f94d636f3572dcf5f7f4dcd1a2726
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 org.apache.harmony.luni.util.Msg; 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 // BEGIN android-note 105 // changed array notation to be consistent with the rest of harmony 106 // END android-note 107 // avoid int overflow, check null buffer 108 // BEGIN android-changed 109 // Exception priorities (in case of multiple errors) differ from 110 // RI, but are spec-compliant. 111 // removed redundant check, made implicit null check explicit, 112 // used (offset | count) < 0 instead of (offset < 0) || (count < 0) 113 // to safe one operation 114 if (buffer == null) { 115 throw new NullPointerException(Msg.getString("K0047")); 116 } 117 if ((offset | count) < 0 || count > buffer.length - offset) { 118 throw new IndexOutOfBoundsException(Msg.getString("K002f")); 119 } 120 // END android-changed 121 for (int i = offset; i < offset + count; i++) { 122 write(buffer[i]); 123 } 124 } 125 126 /** 127 * Writes a single byte to this stream. Only the least significant byte of 128 * the integer {@code oneByte} is written to the stream. 129 * 130 * @param oneByte 131 * the byte to be written. 132 * @throws IOException 133 * if an error occurs while writing to this stream. 134 */ 135 public abstract void write(int oneByte) throws IOException; 136 137 /** 138 * Returns true if this writer has encountered and suppressed an error. Used 139 * by PrintStreams as an alternative to checked exceptions. 140 */ 141 boolean checkError() { 142 return false; 143 } 144} 145