< prev index next >

src/java.base/share/classes/java/io/FileOutputStream.java

Print this page

 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.io;
 27 
 28 import java.nio.channels.FileChannel;
 29 import jdk.internal.access.SharedSecrets;
 30 import jdk.internal.access.JavaIOFileDescriptorAccess;

 31 import sun.nio.ch.FileChannelImpl;
 32 
 33 
 34 /**
 35  * A file output stream is an output stream for writing data to a
 36  * {@code File} or to a {@code FileDescriptor}. Whether or not
 37  * a file is available or may be created depends upon the underlying
 38  * platform.  Some platforms, in particular, allow a file to be opened
 39  * for writing by only one {@code FileOutputStream} (or other
 40  * file-writing object) at a time.  In such situations the constructors in
 41  * this class will fail if the file involved is already open.
 42  *
 43  * <p>{@code FileOutputStream} is meant for writing streams of raw bytes
 44  * such as image data. For writing streams of characters, consider using
 45  * {@code FileWriter}.
 46  *
 47  * @apiNote
 48  * To release resources used by this stream {@link #close} should be called
 49  * directly or by try-with-resources. Subclasses are responsible for the cleanup
 50  * of resources acquired by the subclass.

271         this.fd = fdObj;
272         this.path = null;
273 
274         fd.attach(this);
275     }
276 
277     /**
278      * Opens a file, with the specified name, for overwriting or appending.
279      * @param name name of file to be opened
280      * @param append whether the file is to be opened in append mode
281      */
282     private native void open0(String name, boolean append)
283         throws FileNotFoundException;
284 
285     // wrap native call to allow instrumentation
286     /**
287      * Opens a file, with the specified name, for overwriting or appending.
288      * @param name name of file to be opened
289      * @param append whether the file is to be opened in append mode
290      */
291     private void open(String name, boolean append)
292         throws FileNotFoundException {
293         open0(name, append);



294     }
295 
296     /**
297      * Writes the specified byte to this file output stream.
298      *
299      * @param   b   the byte to be written.
300      * @param   append   {@code true} if the write operation first
301      *     advances the position to the end of file
302      */
303     private native void write(int b, boolean append) throws IOException;
304 
305     /**
306      * Writes the specified byte to this file output stream. Implements
307      * the {@code write} method of {@code OutputStream}.
308      *
309      * @param      b   the byte to be written.
310      * @throws     IOException  if an I/O error occurs.
311      */
312     public void write(int b) throws IOException {
313         write(b, fdAccess.getAppend(fd));





314     }
315 
316     /**
317      * Writes a sub array as a sequence of bytes.
318      * @param b the data to be written
319      * @param off the start offset in the data
320      * @param len the number of bytes that are written
321      * @param append {@code true} to first advance the position to the
322      *     end of file
323      * @throws    IOException If an I/O error has occurred.
324      */
325     private native void writeBytes(byte[] b, int off, int len, boolean append)
326         throws IOException;
327 
328     /**
329      * Writes {@code b.length} bytes from the specified byte array
330      * to this file output stream.
331      *
332      * @param      b   the data.
333      * @throws     IOException  if an I/O error occurs.
334      */
335     public void write(byte[] b) throws IOException {
336         writeBytes(b, 0, b.length, fdAccess.getAppend(fd));





337     }
338 
339     /**
340      * Writes {@code len} bytes from the specified byte array
341      * starting at offset {@code off} to this file output stream.
342      *
343      * @param      b     the data.
344      * @param      off   the start offset in the data.
345      * @param      len   the number of bytes to write.
346      * @throws     IOException  if an I/O error occurs.
347      */
348     public void write(byte[] b, int off, int len) throws IOException {
349         writeBytes(b, off, len, fdAccess.getAppend(fd));





350     }
351 
352     /**
353      * Closes this file output stream and releases any system resources
354      * associated with this stream. This file output stream may no longer
355      * be used for writing bytes.
356      *
357      * <p> If this stream has an associated channel then the channel is closed
358      * as well.
359      *
360      * @apiNote
361      * Overriding {@link #close} to perform cleanup actions is reliable
362      * only when called directly or when called by try-with-resources.
363      * Do not depend on finalization to invoke {@code close};
364      * finalization is not reliable and is deprecated.
365      * If cleanup of native resources is needed, other mechanisms such as
366      * {@linkplain java.lang.ref.Cleaner} should be used.
367      *
368      * @throws     IOException  if an I/O error occurs.
369      *

 11  * This code is distributed in the hope that it will be useful, but WITHOUT
 12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 14  * version 2 for more details (a copy is included in the LICENSE file that
 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.io;
 27 
 28 import java.nio.channels.FileChannel;
 29 import jdk.internal.access.SharedSecrets;
 30 import jdk.internal.access.JavaIOFileDescriptorAccess;
 31 import jdk.internal.misc.Blocker;
 32 import sun.nio.ch.FileChannelImpl;
 33 
 34 
 35 /**
 36  * A file output stream is an output stream for writing data to a
 37  * {@code File} or to a {@code FileDescriptor}. Whether or not
 38  * a file is available or may be created depends upon the underlying
 39  * platform.  Some platforms, in particular, allow a file to be opened
 40  * for writing by only one {@code FileOutputStream} (or other
 41  * file-writing object) at a time.  In such situations the constructors in
 42  * this class will fail if the file involved is already open.
 43  *
 44  * <p>{@code FileOutputStream} is meant for writing streams of raw bytes
 45  * such as image data. For writing streams of characters, consider using
 46  * {@code FileWriter}.
 47  *
 48  * @apiNote
 49  * To release resources used by this stream {@link #close} should be called
 50  * directly or by try-with-resources. Subclasses are responsible for the cleanup
 51  * of resources acquired by the subclass.

272         this.fd = fdObj;
273         this.path = null;
274 
275         fd.attach(this);
276     }
277 
278     /**
279      * Opens a file, with the specified name, for overwriting or appending.
280      * @param name name of file to be opened
281      * @param append whether the file is to be opened in append mode
282      */
283     private native void open0(String name, boolean append)
284         throws FileNotFoundException;
285 
286     // wrap native call to allow instrumentation
287     /**
288      * Opens a file, with the specified name, for overwriting or appending.
289      * @param name name of file to be opened
290      * @param append whether the file is to be opened in append mode
291      */
292     private void open(String name, boolean append) throws FileNotFoundException {
293         if (Thread.currentThread().isVirtual()) {
294             Blocker.managedBlock(() -> open0(name, append));
295         } else {
296             open0(name, append);
297         }
298     }
299 
300     /**
301      * Writes the specified byte to this file output stream.
302      *
303      * @param   b   the byte to be written.
304      * @param   append   {@code true} if the write operation first
305      *     advances the position to the end of file
306      */
307     private native void write(int b, boolean append) throws IOException;
308 
309     /**
310      * Writes the specified byte to this file output stream. Implements
311      * the {@code write} method of {@code OutputStream}.
312      *
313      * @param      b   the byte to be written.
314      * @throws     IOException  if an I/O error occurs.
315      */
316     public void write(int b) throws IOException {
317         boolean append = fdAccess.getAppend(fd);
318         if (Thread.currentThread().isVirtual()) {
319             Blocker.managedBlock(() -> write(b, append));
320         } else {
321             write(b, append);
322         }
323     }
324 
325     /**
326      * Writes a sub array as a sequence of bytes.
327      * @param b the data to be written
328      * @param off the start offset in the data
329      * @param len the number of bytes that are written
330      * @param append {@code true} to first advance the position to the
331      *     end of file
332      * @throws    IOException If an I/O error has occurred.
333      */
334     private native void writeBytes(byte[] b, int off, int len, boolean append)
335         throws IOException;
336 
337     /**
338      * Writes {@code b.length} bytes from the specified byte array
339      * to this file output stream.
340      *
341      * @param      b   the data.
342      * @throws     IOException  if an I/O error occurs.
343      */
344     public void write(byte[] b) throws IOException {
345         boolean append = fdAccess.getAppend(fd);
346         if (Thread.currentThread().isVirtual()) {
347             Blocker.managedBlock(() -> writeBytes(b, 0, b.length, append));
348         } else {
349             writeBytes(b, 0, b.length, append);
350         }
351     }
352 
353     /**
354      * Writes {@code len} bytes from the specified byte array
355      * starting at offset {@code off} to this file output stream.
356      *
357      * @param      b     the data.
358      * @param      off   the start offset in the data.
359      * @param      len   the number of bytes to write.
360      * @throws     IOException  if an I/O error occurs.
361      */
362     public void write(byte[] b, int off, int len) throws IOException {
363         boolean append = fdAccess.getAppend(fd);
364         if (Thread.currentThread().isVirtual()) {
365             Blocker.managedBlock(() -> writeBytes(b, off, len, append));
366         } else {
367             writeBytes(b, off, len, append);
368         }
369     }
370 
371     /**
372      * Closes this file output stream and releases any system resources
373      * associated with this stream. This file output stream may no longer
374      * be used for writing bytes.
375      *
376      * <p> If this stream has an associated channel then the channel is closed
377      * as well.
378      *
379      * @apiNote
380      * Overriding {@link #close} to perform cleanup actions is reliable
381      * only when called directly or when called by try-with-resources.
382      * Do not depend on finalization to invoke {@code close};
383      * finalization is not reliable and is deprecated.
384      * If cleanup of native resources is needed, other mechanisms such as
385      * {@linkplain java.lang.ref.Cleaner} should be used.
386      *
387      * @throws     IOException  if an I/O error occurs.
388      *
< prev index next >