1 /* FileOutputStream.java -- Writes to a file on disk.
2 Copyright (C) 1998, 2001, 2003, 2004, 2005 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
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)
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.
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
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
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. */
41 import gnu.java.nio.channels.FileChannelImpl;
43 import java.nio.channels.FileChannel;
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.
51 * This classes allows a stream of data to be written to a disk file or
52 * any open <code>FileDescriptor</code>.
54 * @author Aaron M. Renn (arenn@urbanophile.com)
55 * @author Tom Tromey (tromey@cygnus.com)
57 public class FileOutputStream extends OutputStream
59 private FileDescriptor fd;
61 private FileChannelImpl ch;
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.
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.
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
79 * @exception SecurityException If write access to the file is not allowed
80 * @exception FileNotFoundException If a non-security error occurs
82 public FileOutputStream (String path, boolean append)
83 throws SecurityException, FileNotFoundException
85 this (new File(path), append);
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.
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.
98 * @param path The name of the file this stream should write to
100 * @exception SecurityException If write access to the file is not allowed
101 * @exception FileNotFoundException If a non-security error occurs
103 public FileOutputStream (String path)
104 throws SecurityException, FileNotFoundException
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.
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.
120 * @param file The <code>File</code> object this stream should write to
122 * @exception SecurityException If write access to the file is not allowed
123 * @exception FileNotFoundException If a non-security error occurs
125 public FileOutputStream (File file)
126 throws SecurityException, FileNotFoundException
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
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.
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
148 * @exception SecurityException If write access to the file is not allowed
149 * @exception FileNotFoundException If a non-security error occurs
151 public FileOutputStream (File file, boolean append)
152 throws FileNotFoundException
154 SecurityManager s = System.getSecurityManager();
156 s.checkWrite(file.getPath());
158 ch = FileChannelImpl.create(file, (append
159 ? FileChannelImpl.WRITE
160 | FileChannelImpl.APPEND
161 : FileChannelImpl.WRITE));
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.
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.
176 * @param fdObj The <code>FileDescriptor</code> this stream should write to
178 * @exception SecurityException If write access to the file is not allowed
180 public FileOutputStream (FileDescriptor fdObj)
181 throws SecurityException
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.
186 throw new SecurityException("Invalid FileDescriptor");
188 SecurityManager s = System.getSecurityManager();
193 ch = (FileChannelImpl) fdObj.channel;
196 FileOutputStream(FileChannelImpl ch)
201 protected void finalize () throws IOException
203 // We don't actually need this, but we include it because it is
204 // mentioned in the JCL.
208 * This method returns a <code>FileDescriptor</code> object representing
209 * the file that is currently being written to
211 * @return A <code>FileDescriptor</code> object for this stream
213 * @exception IOException If an error occurs
215 public final FileDescriptor getFD () throws IOException
220 fd = new FileDescriptor (ch);
226 * This method writes a single byte of data to the file.
228 * @param b The byte of data to write, passed as an <code>int</code>
230 * @exception IOException If an error occurs
232 public void write (int b) throws IOException
238 * This method writes all the bytes in the specified array to the
241 * @param buf The array of bytes to write to the file
243 * @exception IOException If an error occurs
245 public void write (byte[] buf)
248 write (buf, 0, buf.length);
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>.
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
259 * @exception IOException If an error occurs
261 public void write (byte[] buf, int offset, int len)
266 || offset + len > buf.length)
267 throw new ArrayIndexOutOfBoundsException ();
269 ch.write (buf, offset, len);
273 * This method closes the underlying file. Any further attempts to
274 * write to this stream will likely generate an exception since the
277 * @exception IOException If an error occurs
279 public void close () throws IOException
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.
290 public synchronized FileChannel getChannel()
295 } // class FileOutputStream