Data Conversion Streams
Home ] Up ] Files and Directories ] I/O Exceptions ] Streams and Stream Classification ] Character Streams ] Byte Streams ] [ Data Conversion Streams ] Filter Streams ] Message Formatting ] Tokenizers ] Zip & Jar Files ] Random Access ]

 

 

There are two streams that support data conversion:

  • DataInputStream
  • DataOutputStream

Each of these streams implements one of two interfaces:

  • DataInput
  • DataOutput

The DataInput Interface

The DataInput interface contains the following methods:

Method Description
public boolean readBoolean()
throws IOException
Reads a boolean value from the input stream.
public byte readByte()
throws IOException
Reads a signed 8-bit value from the input stream.
public char readChar()
throws IOException
Reads a Unicode char value from the input stream.
public double readDouble()
throws IOException
Reads a double value from the input stream.
public float readFloat()
throws IOException
Reads a float value from the input stream.
public void readFully(byte[] b,
int off, int len)
throws IOException
Reads b.length bytes into the byte array. This method blocks until all the bytes are read.
public void readFully(byte[] b)
throws IOException
Reads b.length bytes into the byte array. This method blocks until all the bytes are read.
public int readInt()
throws IOException
Reads an int value from the input stream.
public String readLine()
throws IOException
Reads the next line of text from the input stream.
(deprecated)
public long readLong()
throws IOException
Reads a long value from the input stream.
public short readShort()
throws IOException
Reads a 16-bit value from the input stream.
public int readUnsignedByte() throws IOException Reads an unsigned 8-bit value from the input stream.
public int readUnsignedShort() throws IOException Reads an unsigned 16-bit value from the input stream.
public String readUTF()
throws IOException
Reads in a string that has been encoded using a modified UTF-8 format.
For an exact description of this method, see the discussion in Gosling, Joy, and Steele, The Java Language Specification.
public int skipBytes(int n)
throws IOException
Skips exactly n bytes of input.

Note: All of the above methods throw an EOFException if the stream reaches its end before reading all the information required for the method.

Note: readLine() is deprecated in byte streams. This method does not properly convert bytes to characters. Starting with JDK 1.1, the preferred way to read lines of text is via the BufferedReader.readLine() method. Programs that use the DataInputStream class to read lines can be converted to use the BufferedReader class by replacing code of the form:
DataInputStream d = new DataInputStream(in);
with:
BufferedReader d = 
   BufferedReader( InputStreamReader(in) );

The DataInputStream Class

A data input stream lets an application read primitive Java data types from an underlying input stream in a machine-independent way. It implements all the methods required by the DataInput interface, plus the following:

Method Description
public DataInputStream(InputStream in) Creates a new data input stream to read data from the specified input stream.
public final int read(byte[] b,
int off, int len)
throws IOException
Reads up to len bytes of data from this data input stream into an array of bytes. This method blocks until some input is available.
The read method of DataInputStream calls the read method of its underlying input stream with the same arguments and returns whatever value that method returns.
public final int read(byte[] b) throws IOException Reads up to b.length bytes of data from this data input stream into an array of bytes. This method blocks until some input is available.
The read method of DataInputStream calls the read method of its underlying input stream with the three arguments b, 0, and b.length and returns whatever value that method returns.
public static final String readUTF(DataInput in)
throws IOException
Reads in a string from the specified data input stream. The string has been encoded using a modified UTF-8 format.
The first two bytes are read as if by readUnsignedShort. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.
This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

The DataOutput Interface

The DataOutput interface contains the following methods:

Method Description
public void write(byte[] b,
int off, int len)
throws IOException
Writes len bytes from the specified byte array starting at offset off to this output stream.
public void write(byte[] b)
throws IOException
Writes b.length bytes from the specified byte array to this output stream.
public void write(int b)
throws IOException
Writes the specified byte to this data output stream.
public void writeBoolean(boolean v)
throws IOException
Writes a boolean value to this output stream.
public void writeByte(int v)
throws IOException
Writes an 8-bit value to this output stream.
public void writeBytes(String s)
throws IOException
Writes a string to this output stream.
public void writeChar(int v)
throws IOException
Writes a char value to this output stream.
public void writeChars(String s)
throws IOException
Writes a string to this output stream.
public void writeDouble(double v) throws IOException Writes a double value to this output stream.
public void writeFloat(float v)
throws IOException
Writes a float value to this output stream.
public void writeInt(int v)
throws IOException
Writes an int value to this output stream.
public void writeLong(long v)
throws IOException
Writes a long value to this output stream.
public void writeShort(int v)
throws IOException
Writes a 16-bit value to this output stream.
public void writeUTF(String str)
throws IOException
Writes a Unicode string by encoding it using modified UTF-8 format.

The DataOutputStream Class

A data output stream lets an application write primitive Java data types to an output stream in a portable way. It implements all the methods required by the DataOutput interface, plus the following:

Method Description
public DataOutputStream(OutputStream out) Creates a new data output stream to write data to the specified underlying output stream.
public void flush()
throws IOException
Flushes this data output stream. This forces any buffered output bytes to be written out to the stream.
The flush method of DataOutputStream calls the flush method of its underlying output stream.
public final int size() Returns the number of bytes written to this data output stream.

An Example

Here's an example of the use of these data conversion classes. It shows how one could take an instance of a class (in this case, Employee, with a member class Address) write it out to a file, and then read it back in again into a fresh instance of Employee.

Note: This program shows writing and reading from within the same program, but it is important to realize that the reading could have been done from another program, even one running on a different platform.

package inputOutput;

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.EOFException;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;

/**
 *  This class demonstrates the ability to write data
 *  out to a file and read it back again, using DataInputStream
 *  and DataOutputStream classes.
 *
 *  @author Bryan J. Higgs
 */
public class EmployeeDataConverter
{
    public static void main(String[] args)
    {
        // Create two valued employee records
        Employee[] emps = new Employee[2];
        emps[0] = new Employee("John Smith",
                            new Address("11 Main St.",
                                        "Nashua", 
                                        "NH", "03060",
                                        "USA"),
                            32,
                            56000.00,
                            false);
        emps[1] = new Employee("Rhonda Schoenberger",
                            new Address("20345 BelAire",
                                        "Silicon Gulch",
                                        "CA", "97210",
                                        "USA"),
                            35,
                            89000.00,
                            true);
            
        try
        {
            // Create a DataOutputStream to output the
            // records to a file.
            DataOutputStream out = new DataOutputStream(
                                        new BufferedOutputStream(
                                            new FileOutputStream(
                                                    "employees.lst")));
            for (int emp = 0; emp < emps.length; emp++)
            {
                emps[emp].outputData(out);
            }
            out.close();
        }
        catch (IOException e)
        {
            e.printStackTrace();
            return;
        }
        
        try
        {
            // Create a DataInputStream to input the records back
            // from the file we just wrote.
            DataInputStream in = new DataInputStream(
                                    new BufferedInputStream(
                                        new FileInputStream(
                                                "employees.lst")));
            PrintWriter writer = new PrintWriter(
                                    new OutputStreamWriter(
                                        System.out));
            try
            {
                for (int emp = 0; emp < emps.length; emp++)
                {
                    Employee e = new Employee();
                    e.inputData(in);
                    writer.println("---Employee---");
                    e.print(writer);
                    writer.flush();
                }
            }
            catch (EOFException e)
            {
                // End of stream
            }
            in.close();
            writer.close();
        }
        catch (FileNotFoundException e)
        {
            // Should never happen
            e.printStackTrace();
        }
        catch (IOException e)
        {
            e.printStackTrace();
        }
    }
}

class Employee
{
    Employee()
    {
        m_address = new Address();
    }
    
    Employee(String name, Address address, int age,
             double salary, boolean isManager)
    {
        m_name = name;
        m_address = address;
        m_age = age;
        m_salary = salary;
        m_isManager = isManager;
    }
    
    void print(PrintWriter out)
    {
        out.println("Name: " + m_name);
        out.println("Address: ");
        m_address.print(out);
        out.println("Age: " + m_age);
        out.println("Salary: " + m_salary);
        out.println("Manager: " + m_isManager);
    }
    
    void outputData(DataOutputStream out)
        throws IOException
    {
        out.writeUTF(m_name);
        m_address.outputData(out);
        out.writeInt(m_age);
        out.writeDouble(m_salary);
        out.writeBoolean(m_isManager);
    }
    
    void inputData(DataInputStream in)
        throws IOException
    {
        m_name = in.readUTF();
        m_address.inputData(in);
        m_age = in.readInt();
        m_salary = in.readDouble();
        m_isManager = in.readBoolean();
    }
    
    /// Private data ///
    private String  m_name;
    private Address m_address;
    private int     m_age;
    private double  m_salary;
    private boolean m_isManager;
}

class Address
{
    Address()
    {}
    
    Address(String street, String city, String state, 
            String postalCode, String country)
    {
        m_street = street;
        m_city = city;
        m_state = state;
        m_postalCode = postalCode;
        m_country = country;
    }
    
    void print(PrintWriter out)
    {
        out.println(m_street);
        out.println(m_city);
        out.println(m_state + " " + m_postalCode);
        out.println(m_country);
    }
    
    void outputData(DataOutputStream out)
        throws IOException
    {
        out.writeUTF(m_street);
        out.writeUTF(m_city);
        out.writeUTF(m_state);
        out.writeUTF(m_postalCode);
        out.writeUTF(m_country);
    }
    
    void inputData(DataInputStream in)
        throws IOException
    {
        m_street = in.readUTF();
        m_city = in.readUTF();
        m_state = in.readUTF();
        m_postalCode = in.readUTF();
        m_country = in.readUTF();
    }
    
    /// Private data ///
    private String  m_street;
    private String  m_city;
    private String  m_state;
    private String  m_postalCode;
    private String  m_country;
}

This produces a file that contains the following:

(as displayed by one editor).  Clearly, the data stored is not pure text -- which is what we expected.

Here is what the program outputs:

---Employee---
Name: John Smith
Address: 
11 Main St.
Nashua
NH 03060
USA
Age: 32
Salary: 56000.0
Manager: false
---Employee---
Name: Rhonda Schoenberger
Address: 
20345 BelAire
Silicon Gulch
CA 97210
USA
Age: 35
Salary: 89000.0
Manager: true
 
The page was last updated February 19, 2008