Page History

The contracts of the read methods for {{InputStream}} and {{Reader}} classes and their subclasses are complicated with regard to filling byte or character arrays.  According to the Java API \[[API 2006|AA. Bibliography#API 06]\] for the class {{InputStream}}, the {{read(byte\[\] b, int off, int len)}} method provides the following behavior:

...

However, the {{read(byte\[\])}} method:

reads some number of bytes from the input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. The number of bytes read is, at most, equal to the length of b.

...

This noncompliant code example attempts to read 1024 bytes encoded in UTF-8 from an InputStream and to return them as a String. It explicitly specifies the character encoding used to build the string, in compliance with rule IDS13-J. Use compatible encodings on both sides of file or network IO.

...

The programmer's misunderstanding of the general contract of the read() method can result in failure to read the intended data in full. It is possible that the data is less than 1024 bytes long , with and that additional data is available from the InputStreaminput stream.

Compliant Solution (Multiple Calls to read())

...

The no-argument and one-argument readFully() methods of the DataInputStream class guarantee that they read either all of the requested data is read or throw an exception is thrown. These methods throw EOFException if they detect the end of input before the required number of bytes have been read; they throw IOException if some other I/O error occurs.

public static String readBytes(FileInputStream fis)
                               throws IOException {
  byte[] data = new byte[1024];
  DataInputStream dis = new DataInputStream(fis);
  dis.readFully(data);
  String str = new String(data, "UTF-8");
  return str;
}

Risk Assessment

Failure to comply with this rule Incorrect use of the read() method can result in the wrong number of bytes being read or character sequences being interpreted incorrectly.

...

...