Editing Java Platform, Standard Edition (section)

=== java.io ===
The {{Javadoc:SE|package=java.io|java/io}} package contains classes that support [[input/output|input and output]].  The classes in the package are primarily [[stream (computing)|stream-oriented]]; however, a class for [[random access]] [[Computer file|files]] is also provided. The central classes in the package are {{Javadoc:SE|java/io|InputStream}} and {{Javadoc:SE|java/io|OutputStream}}, which are [[Class (computer science)#Concrete classes|abstract]] base classes for reading from and writing to [[byte stream]]s, respectively.  The related classes {{Javadoc:SE|java/io|Reader}} and {{Javadoc:SE|java/io|Writer}} are abstract base classes for reading from and writing to [[character (computing)|character]] streams, respectively.  The package also has a few miscellaneous classes to support interactions with the host [[file system]].

==== Streams ====
The stream classes follow the [[decorator pattern]] by extending the base subclass to add features to the stream classes. Subclasses of the base stream classes are typically named for one of the following attributes:

* the source/destination of the stream data
* the type of data written to/read from the stream
* additional processing or filtering performed on the stream data

The stream subclasses are named using the naming [[pattern]] <code>''XxxStreamType''</code> where <code>''Xxx''</code> is the name describing the feature and <code>''StreamType''</code> is one of <code>InputStream</code>, <code>OutputStream</code>, <code>Reader</code>, or <code>Writer</code>.

The following table shows the sources/destinations supported directly by the <code>java.io</code> package:

{| class="wikitable"
|-
! Source/Destination !! Name !! Stream types !! In/out !! Classes
|-
| <code>[[byte]]</code> [[Array (data type)|array]] (<code>byte[]</code>) || <code>ByteArray</code> || <code>byte</code> || in, out
| {{Javadoc:SE|java/io|ByteArrayInputStream}}, {{Javadoc:SE|java/io|ByteArrayOutputStream}}
|-
| <code>char</code> array (<code>char[]</code>) || <code>CharArray</code> || <code>char</code> || in, out
| {{Javadoc:SE|java/io|CharArrayReader}}, {{Javadoc:SE|java/io|CharArrayWriter}}
|-
| [[Computer file|file]] || <code>File</code> || <code>byte</code>, <code>char</code> || in, out
| {{Javadoc:SE|java/io|FileInputStream}}, {{Javadoc:SE|java/io|FileOutputStream}}, {{Javadoc:SE|java/io|FileReader}}, {{Javadoc:SE|java/io|FileWriter}}
|-
| [[string (computer science)|string]] (<code>[[StringBuffer and StringBuilder|StringBuffer]]</code>) || <code>String</code> || <code>char</code> || in, out
| {{Javadoc:SE|java/io|StringReader}}, {{Javadoc:SE|java/io|StringWriter}}
|-
| [[thread (computing)|thread]] (<code>Thread</code>) || <code>Piped</code> || <code>byte</code>, <code>char</code> || in, out
| {{Javadoc:SE|java/io|PipedInputStream}}, {{Javadoc:SE|java/io|PipedOutputStream}}, {{Javadoc:SE|java/io|PipedReader}}, {{Javadoc:SE|java/io|PipedWriter}}
|}

Other standard library packages provide stream implementations for other destinations, such as the <code>InputStream</code> returned by the {{Javadoc:SE|package=java.net|java/net|Socket|getInputStream()}} method or the Java EE {{Javadoc:EE|package=javax.servlet|javax/servlet|ServletOutputStream}} class.

Data type handling and processing or filtering of stream data is accomplished through stream [[filter (software)|filters]].  The filter classes all accept another compatible stream object as a parameter to the constructor and ''decorate'' the enclosed stream with additional features.  Filters are created by extending one of the base filter classes {{Javadoc:SE|java/io|FilterInputStream}}, {{Javadoc:SE|java/io|FilterOutputStream}}, {{Javadoc:SE|java/io|FilterReader}}, or {{Javadoc:SE|java/io|FilterWriter}}.

The <code>Reader</code> and <code>Writer</code> classes are really just byte streams with additional processing performed on the data stream to convert the bytes to characters.  They use the default [[character encoding]] for the platform, which as of J2SE 5.0 is represented by the {{Javadoc:SE|java/nio/charset|Charset}} returned by the {{Javadoc:SE|package=java.nio.charset|java/nio/charset|Charset|defaultCharset()}} static method.  The {{Javadoc:SE|java/io|InputStreamReader}} class converts an <code>InputStream</code> to a <code>Reader</code> and the {{Javadoc:SE|java/io|OutputStreamWriter}} class converts an <code>OutputStream</code> to a <code>Writer</code>.  Both these classes have constructors that support specifying the character encoding to use. If no encoding is specified, the program uses the default encoding for the platform.

The following table shows the other processes and filters that the <code>java.io</code> package directly supports.  All these classes extend the corresponding <code>Filter</code> class.

{| class="wikitable"
|-
! Operation !! Name !! Stream types !! In/out !! Classes
|-
| [[buffer (computer science)|buffering]] || <code>Buffered</code> || <code>byte</code>, <code>char</code> || in, out
| {{Javadoc:SE|java/io|BufferedInputStream}}, {{Javadoc:SE|java/io|BufferedOutputStream}}, {{Javadoc:SE|java/io|BufferedReader}}, {{Javadoc:SE|java/io|BufferedWriter}}
|-
| "push back" last value read || <code>Pushback</code> || <code>byte</code>, <code>char</code> || in
| {{Javadoc:SE|java/io|PushbackInputStream}}, {{Javadoc:SE|java/io|PushbackReader}}
|-
| read/write [[primitive type]]s || <code>Data</code> || <code>byte</code> || in, out
| {{Javadoc:SE|java/io|DataInputStream}}, {{Javadoc:SE|java/io|DataOutputStream}}
|-
| [[object serialization]] (read/write objects) || <code>Object</code> || byte || in, out
| {{Javadoc:SE|java/io|ObjectInputStream}}, {{Javadoc:SE|java/io|ObjectOutputStream}}
|}

==== Random access ====
The {{Javadoc:SE|java/io|RandomAccessFile}} class supports ''[[random access]]'' reading and writing of files.  The class uses a ''[[Data file#File pointers and random access|file pointer]]'' that represents a byte-offset within the file for the next read or write operation.  The file pointer is moved implicitly by reading or writing and explicitly by calling the {{Javadoc:SE|name=seek(long)|java/io|RandomAccessFile|seek(long)}} or {{Javadoc:SE|name=skipBytes(int)|java/io|RandomAccessFile|skipBytes(int)}} methods.  The current position of the file pointer is returned by the {{Javadoc:SE|name=getFilePointer()|java/io|RandomAccessFile|getFilePointer()}} method.

==== File system ====
The {{Javadoc:SE|java/io|File}} class represents a [[Computer file|file]] or [[directory (file systems)|directory]] [[path (computing)|path]] in a [[file system]].  <code>File</code> objects support the creation, deletion and renaming of files and directories and the manipulation of [[file attribute]]s such as ''read-only'' and ''last modified timestamp''.  <code>File</code> objects that represent directories can be used to get a list of all the contained files and directories.

The {{Javadoc:SE|java/io|FileDescriptor}} class is a [[file descriptor]] that represents a source or sink (destination) of bytes.  Typically this is a file, but can also be a [[System console|console]] or [[network socket]].  <code>FileDescriptor</code> objects are used to create <code>File</code> streams.  They are obtained from <code>File</code> streams and <code>java.net</code> sockets and datagram sockets.