toolchain/gcc/libjava/java/io/FileOutputStream.java

   1 /* FileOutputStream.java -- Writes to a file on disk.
   2    Copyright (C) 1998, 2001, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.io;
  40
  41 import java.nio.channels.FileChannel;
  42 import java.nio.channels.FileChannelImpl;
  43
  44 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  45  * "The Java Language Specification", ISBN 0-201-63451-1
  46  * Status:  Complete to version 1.1.
  47  */
  48
  49 /**
  50  * This classes allows a stream of data to be written to a disk file or
  51  * any open <code>FileDescriptor</code>.
  52  *
  53  * @author Aaron M. Renn <arenn@urbanophile.com>
  54  * @author Tom Tromey <tromey@cygnus.com>
  55  */
  56 public class FileOutputStream extends OutputStream
  57 {
  58   private FileDescriptor fd;
  59
  60   private FileChannel ch; /* cached associated file-channel */
  61
  62   /**
  63    * This method initializes a <code>FileOutputStream</code> object to write
  64    * to the named file.  The file is created if it does not exist, and
  65    * the bytes written are written starting at the beginning of the file if
  66    * the <code>append</code> argument is <code>false</code> or at the end
  67    * of the file if the <code>append</code> argument is true.
  68    * <p>
  69    * Before opening a file, a security check is performed by calling the
  70    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
  71    * one exists) with the name of the file to be opened.  An exception is
  72    * thrown if writing is not allowed.
  73    *
  74    * @param name The name of the file this stream should write to
  75    * @param append <code>true</code> to append bytes to the end of the file,
  76    * or <code>false</code> to write bytes to the beginning
  77    *
  78    * @exception SecurityException If write access to the file is not allowed
  79    * @exception FileNotFoundException If a non-security error occurs
  80    */
  81   public FileOutputStream (String path, boolean append)
  82     throws SecurityException, FileNotFoundException
  83   {
  84     SecurityManager s = System.getSecurityManager();
  85     if (s != null)
  86       s.checkWrite(path);
  87     fd = new FileDescriptor (path, (append
  88                                     ? FileDescriptor.WRITE
  89                                       | FileDescriptor.APPEND
  90                                     : FileDescriptor.WRITE));
  91   }
  92
  93   /**
  94    * This method initializes a <code>FileOutputStream</code> object to write
  95    * to the named file.  The file is created if it does not exist, and
  96    * the bytes written are written starting at the beginning of the file.
  97    * <p>
  98    * Before opening a file, a security check is performed by calling the
  99    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 100    * one exists) with the name of the file to be opened.  An exception is
 101    * thrown if writing is not allowed.
 102    *
 103    * @param name The name of the file this stream should write to
 104    *
 105    * @exception SecurityException If write access to the file is not allowed
 106    * @exception FileNotFoundException If a non-security error occurs
 107    */
 108   public FileOutputStream (String path)
 109     throws SecurityException, FileNotFoundException
 110   {
 111     this (path, false);
 112   }
 113
 114   /**
 115    * This method initializes a <code>FileOutputStream</code> object to write
 116    * to the specified <code>File</code> object.  The file is created if it
 117    * does not exist, and the bytes written are written starting at the
 118    * beginning of the file.
 119    * <p>
 120    * Before opening a file, a security check is performed by calling the
 121    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 122    * one exists) with the name of the file to be opened.  An exception is
 123    * thrown if writing is not allowed.
 124    *
 125    * @param file The <code>File</code> object this stream should write to
 126    *
 127    * @exception SecurityException If write access to the file is not allowed
 128    * @exception FileNotFoundException If a non-security error occurs
 129    */
 130   public FileOutputStream (File file)
 131     throws SecurityException, FileNotFoundException
 132   {
 133     this (file.getPath(), false);
 134   }
 135
 136   /**
 137    * This method initializes a <code>FileOutputStream</code> object to write
 138    * to the specified <code>File</code> object.  The file is created if it
 139    * does not exist, and the bytes written are written starting at the
 140    * beginning of the file if the <code>append</code> parameter is
 141    * <code>false</code>.  Otherwise bytes are written at the end of the
 142    * file.
 143    * <p>
 144    * Before opening a file, a security check is performed by calling the
 145    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 146    * one exists) with the name of the file to be opened.  An exception is
 147    * thrown if writing is not allowed.
 148    *
 149    * @param file The <code>File</code> object this stream should write to
 150    * @param append <code>true</code> to append bytes to the end of the file,
 151    * or <code>false</code> to write bytes to the beginning
 152    *
 153    * @exception SecurityException If write access to the file is not allowed
 154    * @exception FileNotFoundException If a non-security error occurs
 155    */
 156   public FileOutputStream (File file, boolean append)
 157     throws FileNotFoundException
 158   {
 159     this (file.getPath(), append);
 160   }
 161
 162   /**
 163    * This method initializes a <code>FileOutputStream</code> object to write
 164    * to the file represented by the specified <code>FileDescriptor</code>
 165    * object.  This method does not create any underlying disk file or
 166    * reposition the file pointer of the given descriptor.  It assumes that
 167    * this descriptor is ready for writing as is.
 168    * <p>
 169    * Before opening a file, a security check is performed by calling the
 170    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 171    * one exists) with the specified <code>FileDescriptor</code> as an argument.
 172    * An exception is thrown if writing is not allowed.
 173    *
 174    * @param file The <code>FileDescriptor</code> this stream should write to
 175    *
 176    * @exception SecurityException If write access to the file is not allowed
 177    */
 178   public FileOutputStream (FileDescriptor fdObj)
 179     throws SecurityException
 180   {
 181     // Hmm, no other exception but this one to throw, but if the descriptor
 182     // isn't valid, we surely don't have "permission" to write to it.
 183     if (!fdObj.valid())
 184       throw new SecurityException("Invalid FileDescriptor");
 185
 186     SecurityManager s = System.getSecurityManager();
 187     if (s != null)
 188       s.checkWrite(fdObj);
 189
 190     fd = fdObj;
 191   }
 192
 193   protected void finalize () throws IOException
 194   {
 195     // We don't actually need this, but we include it because it is
 196     // mentioned in the JCL.
 197   }
 198
 199   /**
 200    * This method returns a <code>FileDescriptor</code> object representing
 201    * the file that is currently being written to
 202    *
 203    * @return A <code>FileDescriptor</code> object for this stream
 204    *
 205    * @exception IOException If an error occurs
 206    */
 207   public final FileDescriptor getFD () throws IOException
 208   {
 209     if (! fd.valid())
 210       throw new IOException ();
 211     return fd;
 212   }
 213
 214   /**
 215    * This method writes a single byte of data to the file.
 216    *
 217    * @param b The byte of data to write, passed as an <code>int</code>
 218    *
 219    * @exception IOException If an error occurs
 220    */
 221   public void write (int b) throws IOException
 222   {
 223     fd.write (b);
 224   }
 225
 226   /**
 227    * This method writes all the bytes in the specified array to the
 228    * file.
 229    *
 230    * @param buf The array of bytes to write to the file
 231    *
 232    * @exception IOException If an error occurs
 233    */
 234   public void write (byte[] buf)
 235     throws IOException
 236   {
 237     write (buf, 0, buf.length);
 238   }
 239
 240   /**
 241    * This method writes <code>len</code> bytes from the byte array
 242    * <code>buf</code> to the file starting at index <code>offset</code>.
 243    *
 244    * @param buf The array of bytes to write to the file
 245    * @param offset The offset into the array to start writing bytes from
 246    * @param len The number of bytes to write to the file
 247    *
 248    * @exception IOException If an error occurs
 249    */
 250   public void write (byte[] buf, int offset, int len)
 251     throws IOException
 252   {
 253     if (offset < 0
 254         || len < 0
 255         || offset + len > buf.length)
 256       throw new ArrayIndexOutOfBoundsException ();
 257
 258     fd.write (buf, offset, len);
 259   }
 260
 261   /**
 262    * This method closes the underlying file.  Any further attempts to
 263    * write to this stream will likely generate an exception since the
 264    * file is closed.
 265    *
 266    * @exception IOException If an error occurs
 267    */
 268   public void close () throws IOException
 269   {
 270     if (fd.valid())
 271       fd.close();
 272   }
 273
 274   /**
 275    * This method creates a java.nio.channels.FileChannel.
 276    * Nio does not allow one to create a file channel directly.
 277    * A file channel must be created by first creating an instance of
 278    * Input/Output/RandomAccessFile and invoking the getChannel() method on it.
 279    */
 280   public synchronized FileChannel getChannel()
 281   {
 282     if (ch == null)
 283       ch = new FileChannelImpl (fd, true, this);
 284
 285     return ch;
 286   }
 287
 288 } // class FileOutputStream
 289