001 /* OutputStream.java -- Base class for byte output streams
002 Copyright (C) 1998, 1999, 2001, 2004, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.io;
040
041 /**
042 * This abstract class forms the base of the hierarchy of classes that
043 * write output as a stream of bytes. It provides a common set of methods
044 * for writing bytes to stream. Subclasses implement and/or extend these
045 * methods to write bytes in a particular manner or to a particular
046 * destination such as a file on disk or network connection.
047 *
048 * @author Aaron M. Renn (arenn@urbanophile.com)
049 * @author Tom Tromey (tromey@cygnus.com)
050 */
051 public abstract class OutputStream implements Closeable, Flushable
052 {
053 /**
054 * This is the default no-argument constructor for this class. This method
055 * does nothing in this class.
056 */
057 public OutputStream ()
058 {
059 }
060
061 /**
062 * This method writes a single byte to the output stream. The byte written
063 * is the low eight bits of the <code>int</code> passed and a argument.
064 * <p>
065 * Subclasses must provide an implementation of this abstract method
066 *
067 * @param b The byte to be written to the output stream, passed as
068 * the low eight bits of an <code>int</code>
069 *
070 * @exception IOException If an error occurs
071 */
072 public abstract void write (int b) throws IOException;
073
074 /**
075 * This method all the writes bytes from the passed array to the
076 * output stream. This method is equivalent to <code>write(b, 0,
077 * buf.length)</code> which is exactly how it is implemented in this
078 * class.
079 *
080 * @param b The array of bytes to write
081 *
082 * @exception IOException If an error occurs
083 */
084 public void write (byte[] b) throws IOException, NullPointerException
085 {
086 write (b, 0, b.length);
087 }
088
089 /**
090 * This method writes <code>len</code> bytes from the specified array
091 * <code>b</code> starting at index <code>off</code> into the array.
092 * <p>
093 * This method in this class calls the single byte <code>write()</code>
094 * method in a loop until all bytes have been written. Subclasses should
095 * override this method if possible in order to provide a more efficent
096 * implementation.
097 *
098 * @param b The array of bytes to write from
099 * @param off The index into the array to start writing from
100 * @param len The number of bytes to write
101 *
102 * @exception IOException If an error occurs
103 */
104 public void write (byte[] b, int off, int len)
105 throws IOException, NullPointerException, IndexOutOfBoundsException
106 {
107 if (off < 0 || len < 0 || off + len > b.length)
108 throw new ArrayIndexOutOfBoundsException ();
109 for (int i = 0; i < len; ++i)
110 write (b[off + i]);
111 }
112
113 /**
114 * This method forces any data that may have been buffered to be written
115 * to the underlying output device. Please note that the host environment
116 * might perform its own buffering unbeknowst to Java. In that case, a
117 * write made (for example, to a disk drive) might be cached in OS
118 * buffers instead of actually being written to disk.
119 * <p>
120 * This method in this class does nothing.
121 *
122 * @exception IOException If an error occurs
123 */
124 public void flush () throws IOException
125 {
126 }
127
128 /**
129 * This method closes the stream. Any internal or native resources
130 * associated with this stream are freed. Any subsequent attempt to
131 * access the stream might throw an exception.
132 * <p>
133 * This method in this class does nothing.
134 *
135 * @exception IOException If an error occurs
136 */
137 public void close () throws IOException
138 {
139 }
140 }