java.io
Class FileOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.FileOutputStream

All Implemented Interfaces:

Closeable, Flushable

public class FileOutputStream
extends OutputStream

This classes allows a stream of data to be written to a disk file or any open FileDescriptor.

Constructor Summary

FileOutputStream(File file)
This method initializes a FileOutputStream object to write to the specified File object.

FileOutputStream(File file, boolean append)
This method initializes a FileOutputStream object to write to the specified File object.

FileOutputStream(FileDescriptor fdObj)
This method initializes a FileOutputStream object to write to the file represented by the specified FileDescriptor object.

FileOutputStream(String path)
This method initializes a FileOutputStream object to write to the named file.

FileOutputStream(String path, boolean append)
This method initializes a FileOutputStream object to write to the named file.

Method Summary

void	close() This method closes the underlying file.
protected void	finalize() finalize may be called by the memory management of the virtual machine when it determined that this instance's memory is unreachable and can be reclaimed.
FileChannel	getChannel() This method creates a java.nio.channels.FileChannel.
FileDescriptor	getFD() This method returns a FileDescriptor object representing the file that is currently being written to
void	write(byte[] buf) This method writes all the bytes in the specified array to the file.
void	write(byte[] buf, int offset, int len) This method writes len bytes from the byte array buf to the file starting at index offset.
void	write(int b) This method writes a single byte of data to the file.

Methods inherited from class java.io.OutputStream

flush

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileOutputStream

public FileOutputStream(String path,
                        boolean append)
                 throws SecurityException,
                        FileNotFoundException

This method initializes a FileOutputStream object to write to the named file. The file is created if it does not exist, and the bytes written are written starting at the beginning of the file if the append argument is false or at the end of the file if the append argument is true.

Before opening a file, a security check is performed by calling the checkWrite method of the SecurityManager (if one exists) with the name of the file to be opened. An exception is thrown if writing is not allowed.

Parameters:

path - The name of the file this stream should write to

append - true to append bytes to the end of the file, or false to write bytes to the beginning

Throws:

SecurityException - If write access to the file is not allowed

FileNotFoundException - If a non-security error occurs

FileOutputStream

public FileOutputStream(String path)
                 throws SecurityException,
                        FileNotFoundException

This method initializes a FileOutputStream object to write to the named file. The file is created if it does not exist, and the bytes written are written starting at the beginning of the file.

Before opening a file, a security check is performed by calling the checkWrite method of the SecurityManager (if one exists) with the name of the file to be opened. An exception is thrown if writing is not allowed.

Parameters:

path - The name of the file this stream should write to

Throws:

SecurityException - If write access to the file is not allowed

FileNotFoundException - If a non-security error occurs

FileOutputStream

public FileOutputStream(File file)
                 throws SecurityException,
                        FileNotFoundException

This method initializes a FileOutputStream object to write to the specified File object. The file is created if it does not exist, and the bytes written are written starting at the beginning of the file.

Before opening a file, a security check is performed by calling the checkWrite method of the SecurityManager (if one exists) with the name of the file to be opened. An exception is thrown if writing is not allowed.

Parameters:

file - The File object this stream should write to

Throws:

SecurityException - If write access to the file is not allowed

FileNotFoundException - If a non-security error occurs

FileOutputStream

public FileOutputStream(File file,
                        boolean append)
                 throws FileNotFoundException

This method initializes a FileOutputStream object to write to the specified File object. The file is created if it does not exist, and the bytes written are written starting at the beginning of the file if the append parameter is false. Otherwise bytes are written at the end of the file.

Before opening a file, a security check is performed by calling the checkWrite method of the SecurityManager (if one exists) with the name of the file to be opened. An exception is thrown if writing is not allowed.

Parameters:

file - The File object this stream should write to

append - true to append bytes to the end of the file, or false to write bytes to the beginning

Throws:

SecurityException - If write access to the file is not allowed

FileNotFoundException - If a non-security error occurs

FileOutputStream

public FileOutputStream(FileDescriptor fdObj)
                 throws SecurityException

This method initializes a FileOutputStream object to write to the file represented by the specified FileDescriptor object. This method does not create any underlying disk file or reposition the file pointer of the given descriptor. It assumes that this descriptor is ready for writing as is.

Before opening a file, a security check is performed by calling the checkWrite method of the SecurityManager (if one exists) with the specified FileDescriptor as an argument. An exception is thrown if writing is not allowed.

Parameters:

fdObj - The FileDescriptor this stream should write to

Throws:

SecurityException - If write access to the file is not allowed

Method Detail

finalize

protected void finalize()
                 throws IOException

Description copied from class: Object

finalize may be called by the memory management of the virtual machine when it determined that this instance's memory is unreachable and can be reclaimed.

NOTE: The use of finalize() is strongly discouraged for realtime or safety-critical code. This method should only be used for debugging purposes. If used as a last resort to reclaim non-memory resouces, finalize() should indicate the resource leak with a loud error message.

There is no guarantee that finalize() will be called, the memory management may decide not to reclaim this object's memory or to delay the call to finalize() to an unspecified point in time. It is therefore recommended never to use the finalize method to release any resources (files, network connections, non-Java memory, etc.) since releasing of these resource may be delayed perpetually.

The order of finalization is not specified, i.e., the finalize method of any two objects that become unreachable may be called in an arbitrary order. It therefore has to be assumed that when finalize() is called on an object, that the finalize() method of any object that is only reachable through this object() has been called as well or is called simultaneously by another thread.

The presence of a finalize-method in any sub-class of Object causes the reclamation of the memory of this object to be delayed until the finalize() method has been executed. The finalize() method is typically executed by the finalizer thread (that may run at a low priority) or by a call to Runtime.runFinalization().

Any code sequence that creates instances of a class that defines a finalize() method must therefore ensure that sufficient CPU time is allocated to the finalizer thread or that Runtime.runFinalization() is called regularly such that the finalize() methods can be executed and the object's memory can be reclaimed.

The finalize method itself should never block or run for long times since it would otherwise block the finalizer thread or the thread that called Runtime.runFinalization() and prevent the execution other finalize() method and consequently prevent the reclamation of these object's memory.

For objects that are allocated in a javax.realtime.ScopedMemory, the finalize() methods will be called when this scoped memory is exited by the last thread. Unlike HeapMemory, which is controlled by the garbage collector, ScopedMemory provides a defined execution point for the finalize() mehods and it is therefore safer to use finalize() here.

Overrides:

finalize in class Object

Throws:

IOException

getFD

public final FileDescriptor getFD()
                           throws IOException

This method returns a FileDescriptor object representing the file that is currently being written to

Returns:

A FileDescriptor object for this stream

Throws:

IOException - If an error occurs

write

public void write(int b)
           throws IOException

This method writes a single byte of data to the file.

Specified by:

write in class OutputStream

Parameters:

b - The byte of data to write, passed as an int

Throws:

IOException - If an error occurs

write

public void write(byte[] buf)
           throws IOException

This method writes all the bytes in the specified array to the file.

Overrides:

write in class OutputStream

Parameters:

buf - The array of bytes to write to the file

Throws:

IOException - If an error occurs

write

public void write(byte[] buf,
                  int offset,
                  int len)
           throws IOException

This method writes len bytes from the byte array buf to the file starting at index offset.

Overrides:

write in class OutputStream

Parameters:

buf - The array of bytes to write to the file

offset - The offset into the array to start writing bytes from

len - The number of bytes to write to the file

Throws:

IOException - If an error occurs

close

public void close()
           throws IOException

This method closes the underlying file. Any further attempts to write to this stream will likely generate an exception since the file is closed.

Specified by:

close in interface Closeable

Overrides:

close in class OutputStream

Throws:

IOException - If an error occurs

getChannel

public FileChannel getChannel()

This method creates a java.nio.channels.FileChannel. Nio does not allow one to create a file channel directly. A file channel must be created by first creating an instance of Input/Output/RandomAccessFile and invoking the getChannel() method on it.