libjava/java/io/FileOutputStream.java

   1 /* FileOutputStream.java -- Writes to a file on disk.
   2    Copyright (C) 1998, 2001, 2003, 2004, 2005  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 gnu.java.nio.channels.FileChannelImpl;
  42
  43 import java.nio.channels.FileChannel;
  44
  45 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  46  * "The Java Language Specification", ISBN 0-201-63451-1
  47  * Status:  Complete to version 1.1.
  48  */
  49
  50 /**
  51  * This classes allows a stream of data to be written to a disk file or
  52  * any open <code>FileDescriptor</code>.
  53  *
  54  * @author Aaron M. Renn (arenn@urbanophile.com)
  55  * @author Tom Tromey (tromey@cygnus.com)
  56  */
  57 public class FileOutputStream extends OutputStream
  58 {
  59   private FileDescriptor fd;
  60
  61   private FileChannelImpl ch;
  62
  63   /**
  64    * This method initializes a <code>FileOutputStream</code> object to write
  65    * to the named file.  The file is created if it does not exist, and
  66    * the bytes written are written starting at the beginning of the file if
  67    * the <code>append</code> argument is <code>false</code> or at the end
  68    * of the file if the <code>append</code> argument is true.
  69    * <p>
  70    * Before opening a file, a security check is performed by calling the
  71    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
  72    * one exists) with the name of the file to be opened.  An exception is
  73    * thrown if writing is not allowed.
  74    *
  75    * @param path The name of the file this stream should write to
  76    * @param append <code>true</code> to append bytes to the end of the file,
  77    * or <code>false</code> to write bytes to the beginning
  78    *
  79    * @exception SecurityException If write access to the file is not allowed
  80    * @exception FileNotFoundException If a non-security error occurs
  81    */
  82   public FileOutputStream (String path, boolean append)
  83     throws SecurityException, FileNotFoundException
  84   {
  85     this (new File(path), append);
  86   }
  87
  88   /**
  89    * This method initializes a <code>FileOutputStream</code> object to write
  90    * to the named file.  The file is created if it does not exist, and
  91    * the bytes written are written starting at the beginning of the file.
  92    * <p>
  93    * Before opening a file, a security check is performed by calling the
  94    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
  95    * one exists) with the name of the file to be opened.  An exception is
  96    * thrown if writing is not allowed.
  97    *
  98    * @param path The name of the file this stream should write to
  99    *
 100    * @exception SecurityException If write access to the file is not allowed
 101    * @exception FileNotFoundException If a non-security error occurs
 102    */
 103   public FileOutputStream (String path)
 104     throws SecurityException, FileNotFoundException
 105   {
 106     this (path, false);
 107   }
 108
 109   /**
 110    * This method initializes a <code>FileOutputStream</code> object to write
 111    * to the specified <code>File</code> object.  The file is created if it
 112    * does not exist, and the bytes written are written starting at the
 113    * beginning of the file.
 114    * <p>
 115    * Before opening a file, a security check is performed by calling the
 116    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 117    * one exists) with the name of the file to be opened.  An exception is
 118    * thrown if writing is not allowed.
 119    *
 120    * @param file The <code>File</code> object this stream should write to
 121    *
 122    * @exception SecurityException If write access to the file is not allowed
 123    * @exception FileNotFoundException If a non-security error occurs
 124    */
 125   public FileOutputStream (File file)
 126     throws SecurityException, FileNotFoundException
 127   {
 128     this (file, false);
 129   }
 130
 131   /**
 132    * This method initializes a <code>FileOutputStream</code> object to write
 133    * to the specified <code>File</code> object.  The file is created if it
 134    * does not exist, and the bytes written are written starting at the
 135    * beginning of the file if the <code>append</code> parameter is
 136    * <code>false</code>.  Otherwise bytes are written at the end of the
 137    * file.
 138    * <p>
 139    * Before opening a file, a security check is performed by calling the
 140    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 141    * one exists) with the name of the file to be opened.  An exception is
 142    * thrown if writing is not allowed.
 143    *
 144    * @param file The <code>File</code> object this stream should write to
 145    * @param append <code>true</code> to append bytes to the end of the file,
 146    * or <code>false</code> to write bytes to the beginning
 147    *
 148    * @exception SecurityException If write access to the file is not allowed
 149    * @exception FileNotFoundException If a non-security error occurs
 150    */
 151   public FileOutputStream (File file, boolean append)
 152     throws FileNotFoundException
 153   {
 154     SecurityManager s = System.getSecurityManager();
 155     if (s != null)
 156       s.checkWrite(file.getPath());
 157
 158     if (file.isDirectory())
 159       throw new FileNotFoundException(file.getPath() + " is a directory");
 160
 161    ch = new FileChannelImpl (file.getPath(), (append
 162                                      ? FileChannelImpl.WRITE
 163                                      | FileChannelImpl.APPEND
 164                                      : FileChannelImpl.WRITE));
 165   }
 166
 167   /**
 168    * This method initializes a <code>FileOutputStream</code> object to write
 169    * to the file represented by the specified <code>FileDescriptor</code>
 170    * object.  This method does not create any underlying disk file or
 171    * reposition the file pointer of the given descriptor.  It assumes that
 172    * this descriptor is ready for writing as is.
 173    * <p>
 174    * Before opening a file, a security check is performed by calling the
 175    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 176    * one exists) with the specified <code>FileDescriptor</code> as an argument.
 177    * An exception is thrown if writing is not allowed.
 178    *
 179    * @param fdObj The <code>FileDescriptor</code> this stream should write to
 180    *
 181    * @exception SecurityException If write access to the file is not allowed
 182    */
 183   public FileOutputStream (FileDescriptor fdObj)
 184     throws SecurityException
 185   {
 186     // Hmm, no other exception but this one to throw, but if the descriptor
 187     // isn't valid, we surely don't have "permission" to write to it.
 188     if (!fdObj.valid())
 189       throw new SecurityException("Invalid FileDescriptor");
 190
 191     SecurityManager s = System.getSecurityManager();
 192     if (s != null)
 193       s.checkWrite(fdObj);
 194
 195     fd = fdObj;
 196     ch = (FileChannelImpl) fdObj.channel;
 197   }
 198
 199   FileOutputStream(FileChannelImpl ch)
 200   {
 201     this.ch = ch;
 202   }
 203
 204   protected void finalize () throws IOException
 205   {
 206     // We don't actually need this, but we include it because it is
 207     // mentioned in the JCL.
 208   }
 209
 210   /**
 211    * This method returns a <code>FileDescriptor</code> object representing
 212    * the file that is currently being written to
 213    *
 214    * @return A <code>FileDescriptor</code> object for this stream
 215    *
 216    * @exception IOException If an error occurs
 217    */
 218   public final FileDescriptor getFD () throws IOException
 219   {
 220     synchronized (this)
 221       {
 222         if (fd == null)
 223           fd = new FileDescriptor (ch);
 224         return fd;
 225       }
 226   }
 227
 228   /**
 229    * This method writes a single byte of data to the file.
 230    *
 231    * @param b The byte of data to write, passed as an <code>int</code>
 232    *
 233    * @exception IOException If an error occurs
 234    */
 235   public void write (int b) throws IOException
 236   {
 237     ch.write (b);
 238   }
 239
 240   /**
 241    * This method writes all the bytes in the specified array to the
 242    * file.
 243    *
 244    * @param buf The array of bytes to write to the file
 245    *
 246    * @exception IOException If an error occurs
 247    */
 248   public void write (byte[] buf)
 249     throws IOException
 250   {
 251     write (buf, 0, buf.length);
 252   }
 253
 254   /**
 255    * This method writes <code>len</code> bytes from the byte array
 256    * <code>buf</code> to the file starting at index <code>offset</code>.
 257    *
 258    * @param buf The array of bytes to write to the file
 259    * @param offset The offset into the array to start writing bytes from
 260    * @param len The number of bytes to write to the file
 261    *
 262    * @exception IOException If an error occurs
 263    */
 264   public void write (byte[] buf, int offset, int len)
 265     throws IOException
 266   {
 267     if (offset < 0
 268         || len < 0
 269         || offset + len > buf.length)
 270       throw new ArrayIndexOutOfBoundsException ();
 271
 272     ch.write (buf, offset, len);
 273   }
 274
 275   /**
 276    * This method closes the underlying file.  Any further attempts to
 277    * write to this stream will likely generate an exception since the
 278    * file is closed.
 279    *
 280    * @exception IOException If an error occurs
 281    */
 282   public void close () throws IOException
 283   {
 284     ch.close();
 285   }
 286
 287   /**
 288    * This method creates a java.nio.channels.FileChannel.
 289    * Nio does not allow one to create a file channel directly.
 290    * A file channel must be created by first creating an instance of
 291    * Input/Output/RandomAccessFile and invoking the getChannel() method on it.
 292    */
 293   public synchronized FileChannel getChannel()
 294   {
 295     return ch;
 296   }
 297
 298 } // class FileOutputStream
 299