001/* OutputStream.java -- Base class for byte output streams
002   Copyright (C) 1998, 1999, 2001, 2004, 2005 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010 
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package 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  */
051public 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}