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    }