Source for java.io.FileOutputStream

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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:    ch = FileChannelImpl.create(file, (append
 159:                     ? FileChannelImpl.WRITE
 160:                     | FileChannelImpl.APPEND
 161:                     : FileChannelImpl.WRITE));
 162:   }
 163: 
 164:   /**
 165:    * This method initializes a <code>FileOutputStream</code> object to write
 166:    * to the file represented by the specified <code>FileDescriptor</code>
 167:    * object.  This method does not create any underlying disk file or
 168:    * reposition the file pointer of the given descriptor.  It assumes that
 169:    * this descriptor is ready for writing as is.
 170:    * <p>
 171:    * Before opening a file, a security check is performed by calling the
 172:    * <code>checkWrite</code> method of the <code>SecurityManager</code> (if
 173:    * one exists) with the specified <code>FileDescriptor</code> as an argument.
 174:    * An exception is thrown if writing is not allowed. 
 175:    *
 176:    * @param fdObj The <code>FileDescriptor</code> this stream should write to
 177:    *
 178:    * @exception SecurityException If write access to the file is not allowed
 179:    */
 180:   public FileOutputStream (FileDescriptor fdObj)
 181:     throws SecurityException
 182:   {
 183:     // Hmm, no other exception but this one to throw, but if the descriptor
 184:     // isn't valid, we surely don't have "permission" to write to it.
 185:     if (!fdObj.valid())
 186:       throw new SecurityException("Invalid FileDescriptor");
 187: 
 188:     SecurityManager s = System.getSecurityManager();
 189:     if (s != null)
 190:       s.checkWrite(fdObj);
 191: 
 192:     fd = fdObj;
 193:     ch = (FileChannelImpl) fdObj.channel;
 194:   }
 195: 
 196:   FileOutputStream(FileChannelImpl ch)
 197:   {
 198:     this.ch = ch;
 199:   }
 200: 
 201:   protected void finalize () throws IOException
 202:   {
 203:     // We don't actually need this, but we include it because it is
 204:     // mentioned in the JCL.
 205:   }
 206: 
 207:   /**
 208:    * This method returns a <code>FileDescriptor</code> object representing
 209:    * the file that is currently being written to
 210:    *
 211:    * @return A <code>FileDescriptor</code> object for this stream
 212:    *
 213:    * @exception IOException If an error occurs
 214:    */
 215:   public final FileDescriptor getFD () throws IOException
 216:   {
 217:     synchronized (this)
 218:       {
 219:     if (fd == null)
 220:       fd = new FileDescriptor (ch);
 221:     return fd;
 222:       }
 223:   }
 224: 
 225:   /**
 226:    * This method writes a single byte of data to the file.  
 227:    *
 228:    * @param b The byte of data to write, passed as an <code>int</code>
 229:    *
 230:    * @exception IOException If an error occurs
 231:    */
 232:   public void write (int b) throws IOException
 233:   {
 234:     ch.write (b);
 235:   }
 236: 
 237:   /**
 238:    * This method writes all the bytes in the specified array to the
 239:    * file.
 240:    *
 241:    * @param buf The array of bytes to write to the file
 242:    *
 243:    * @exception IOException If an error occurs
 244:    */
 245:   public void write (byte[] buf)
 246:     throws IOException
 247:   {
 248:     write (buf, 0, buf.length);
 249:   }
 250: 
 251:   /**
 252:    * This method writes <code>len</code> bytes from the byte array 
 253:    * <code>buf</code> to the file starting at index <code>offset</code>.
 254:    *
 255:    * @param buf The array of bytes to write to the file
 256:    * @param offset The offset into the array to start writing bytes from
 257:    * @param len The number of bytes to write to the file
 258:    *
 259:    * @exception IOException If an error occurs
 260:    */
 261:   public void write (byte[] buf, int offset, int len)
 262:     throws IOException
 263:   {
 264:     if (offset < 0
 265:         || len < 0
 266:         || offset + len > buf.length)
 267:       throw new ArrayIndexOutOfBoundsException ();
 268:     
 269:     ch.write (buf, offset, len);
 270:   }
 271: 
 272:   /**
 273:    * This method closes the underlying file.  Any further attempts to
 274:    * write to this stream will likely generate an exception since the
 275:    * file is closed.
 276:    *
 277:    * @exception IOException If an error occurs
 278:    */
 279:   public void close () throws IOException
 280:   {
 281:     ch.close();
 282:   }
 283: 
 284:   /**
 285:    * This method creates a java.nio.channels.FileChannel.
 286:    * Nio does not allow one to create a file channel directly.
 287:    * A file channel must be created by first creating an instance of
 288:    * Input/Output/RandomAccessFile and invoking the getChannel() method on it.
 289:    */
 290:   public synchronized FileChannel getChannel() 
 291:   {
 292:     return ch;
 293:   }
 294: 
 295: } // class FileOutputStream