Java IO: FileInputStream

by ⋅ Link

Java IO: FileInputStream

original source : http://tutorials.jenkov.com/java-io/fileinputstream.html

The FileInputStream class makes it possible to read the contents of a file as a stream of bytes. The FileInputStream class is a subclass of InputStream. This means that you use the FileInputStream as an InputStream (FileInputStream behaves like an InputStream).

FileInputStream Example

Here is a simple FileInputStream example:

InputStream input = new FileInputStream("c:\data\input-text.txt");

int data = input.read();
while(data != -1) {
  //do something with data...
  doSomethingWithData(data);

  data = input.read();
}
input.close();

Note: The proper exception handling has been skipped here for the sake of clarity. To learn more about correct exception handling, go to Java IO Exception Handling.

FileInputStream Constructors

The FileInputStream class has a three different constructors you can use to create a FileInputStreaminstance. I will cover the first two here.

The first constructor takes a String as parameter. This String should contain the path in the file system to where the file to read is located. Here is a code example:

String path = "C:\user\data\thefile.txt";

FileInputStream fileInputStream = new FileInputStream(path);

Notice the path String. It needs double backslashes (\) to create a single backslash in the String, because backslash is an escape character in Java Strings. To get a single backslash you need to use the escape sequence \.

On unix the file path could have looked like this:

String path = "/home/jakobjenkov/data/thefile.txt";

Notice the use of the for-slash (the normal slash character) as directory separator. That is how you write file paths on unix. Actually, in my experience Java will also understand if you use a / as directory separator on Windows (e.g. c:/user/data/thefile.txt), but don’t take my word for it. Test it on your own system!

The second FileInputStream constructor takes a File object as parameter. The File object has to point to the file you want to read. Here is an example:

String path = "C:\user\data\thefile.txt";
File   file = new File(path);

FileInputStream fileInputStream = new FileInputStream(file);

Which of the constructors you should use depends on what form you have the path in before opening the FileInputStream. If you already have a String or File, just use that as it is. There is no particular gain in converting a String to a File, or a File to a String first.

read()

The read() method of a FileInputStream returns an int which contains the byte value of the byte read. If the read() method returns -1, there is no more data to read in the FileInputStream, and it can be closed. That is, -1 as int value, not -1 as byte value. There is a difference here!

You use the read() method just like the read() method of an InputStream.

read(byte[])

Being an InputStream the FileInputStream also has two read() methods which can read data into a bytearray. You can read more about them in my tutorial about the InputStream (see link elsewhere in this text).

close()

Just like any other InputStream a FileInputStream needs to be closed properly after use. You do that by calling the FileInputStream’s close() method. You can see that in the FileInputStream example further up this text, and remember to check the Java IO exception handling tutorial for more information about proper exception handling (link below the example further up the page)

Java IO: FileInputStream

by ⋅ Link

Java IO: FileInputStream

original source : http://tutorials.jenkov.com/java-io/fileinputstream.html

The FileInputStream class makes it possible to read the contents of a file as a stream of bytes. The FileInputStream class is a subclass of InputStream. This means that you use the FileInputStream as an InputStream (FileInputStream behaves like an InputStream).

FileInputStream Example

Here is a simple FileInputStream example:

InputStream input = new FileInputStream("c:\data\input-text.txt");

int data = input.read();
while(data != -1) {
  //do something with data...
  doSomethingWithData(data);

  data = input.read();
}
input.close();

Note: The proper exception handling has been skipped here for the sake of clarity. To learn more about correct exception handling, go to Java IO Exception Handling.

FileInputStream Constructors

The FileInputStream class has a three different constructors you can use to create a FileInputStreaminstance. I will cover the first two here.

The first constructor takes a String as parameter. This String should contain the path in the file system to where the file to read is located. Here is a code example:

String path = "C:\user\data\thefile.txt";

FileInputStream fileInputStream = new FileInputStream(path);

Notice the path String. It needs double backslashes (\) to create a single backslash in the String, because backslash is an escape character in Java Strings. To get a single backslash you need to use the escape sequence \.

On unix the file path could have looked like this:

String path = "/home/jakobjenkov/data/thefile.txt";

Notice the use of the for-slash (the normal slash character) as directory separator. That is how you write file paths on unix. Actually, in my experience Java will also understand if you use a / as directory separator on Windows (e.g. c:/user/data/thefile.txt), but don’t take my word for it. Test it on your own system!

The second FileInputStream constructor takes a File object as parameter. The File object has to point to the file you want to read. Here is an example:

String path = "C:\user\data\thefile.txt";
File   file = new File(path);

FileInputStream fileInputStream = new FileInputStream(file);

Which of the constructors you should use depends on what form you have the path in before opening the FileInputStream. If you already have a String or File, just use that as it is. There is no particular gain in converting a String to a File, or a File to a String first.

read()

The read() method of a FileInputStream returns an int which contains the byte value of the byte read. If the read() method returns -1, there is no more data to read in the FileInputStream, and it can be closed. That is, -1 as int value, not -1 as byte value. There is a difference here!

You use the read() method just like the read() method of an InputStream.

read(byte[])

Being an InputStream the FileInputStream also has two read() methods which can read data into a bytearray. You can read more about them in my tutorial about the InputStream (see link elsewhere in this text).

close()

Just like any other InputStream a FileInputStream needs to be closed properly after use. You do that by calling the FileInputStream’s close() method. You can see that in the FileInputStream example further up this text, and remember to check the Java IO exception handling tutorial for more information about proper exception handling (link below the example further up the page)

Java IO: OutputStream

by ⋅ Link

Java IO: OutputStream

original source : http://tutorials.jenkov.com/java-io/outputstream.html

The OutputStream class is the base class of all output streams in the Java IO API. Subclasses include the BufferedOutputStream and the FileOutputStream among others. To see a full list of streams, go to the bottom table of the Java IO Overview page.

OutputStream’s and Destinations

An OutputStream is typically always connected to some data destination, like a file, network connection, pipe etc. This is also explained in more detail in the Java IO Overview text. The OutputStream’s data destination is where all data written to the OutputStream will eventually end.

write(byte)

The write(byte) method is used to write a single byte to the OutputStream. The write() method of an OutputStream takes an int which contains the byte value of the byte to write. Only the first byte of the intvalue is written. The rest is ignored.

Subclasses of OutputStream may have alternative write() methods. For instance, the DataOutputStreamallows you to write Java primitives like int, long, float, double, boolean etc. with its corresponding methods writeBoolean(), writeDouble() etc.

Here is an OutputStream write() example:

OutputStream output = new FileOutputStream("c:\data\output-text.txt");

while(hasMoreData()) {
  int data = getMoreData();
  output.write(data);
}
output.close();

This OutputStream write() example first creates a FileOutputStream to which the data will be written. Then the example enters a while loop. The condition to exit the while loop is the return value of the method hasMoreData(). The implementation of hasMoreData() is not shown, but imagine that it returns true if there is more data to write, and false if not.

Inside the while loop the example calls the method getMoreData() to get the next data to write to the OutputStream, and then writes that data to the OutputStream. The while loop continues until hasMoreData()returns false.

Note: The proper exception handling has been skipped here for the sake of clarity. To learn more about correct exception handling, go to Java IO Exception Handling.

write(byte[])

The OutputStream class also has a write(byte[] bytes) method and a write(byte[] bytes, int offset, int length) which both can write an array or part of an array of bytes to the OutputStream.

The write(byte[] bytes) method writes all the bytes in the byte array to the OutputStream.

The write(byte[] bytes, int offset, int length) method writes length bytes starting from index offsetfrom the byte array to the OutputStream.

flush()

The OutputStream’s flush() method flushes all data written to the OutputStream to the underlying data destination. For instance, if the OutputStream is a FileOutputStream then bytes written to the FileOutputStream may not have been fully written to disk yet. The data might be buffered in memory somewhere, even if your Java code has written it to the FileOutputStream. By calling flush() you can assure that any buffered data will be flushed (written) to disk (or network, or whatever else the destination of your OutputStream has).

close()

Once you are done writing data to the OutputStream you should close it. You close an OutputStream by calling its close() method. Since the OutputStream’s various write() methods may throw an IOException, you should close the OutputStream inside a finally block. Here is a simple OutputStream close() example:

OutputStream output = null;

try{
  output = new FileOutputStream("c:\data\output-text.txt");

  while(hasMoreData()) {
    int data = getMoreData();
    output.write(data);
  }
} finally {
    if(output != null) {
        output.close();
    }
}

This simple example calls the OutputStream close() method inside a finally block. While this makes sure that the OutputStream is closed, it still does not provide perfect exception handling. I have covered IO exception handling in more detail in my text about Java IO exception handling.

Java IO: OutputStream

by ⋅ Link

Java IO: OutputStream

original source : http://tutorials.jenkov.com/java-io/outputstream.html

The OutputStream class is the base class of all output streams in the Java IO API. Subclasses include the BufferedOutputStream and the FileOutputStream among others. To see a full list of streams, go to the bottom table of the Java IO Overview page.

OutputStream’s and Destinations

An OutputStream is typically always connected to some data destination, like a file, network connection, pipe etc. This is also explained in more detail in the Java IO Overview text. The OutputStream’s data destination is where all data written to the OutputStream will eventually end.

write(byte)

The write(byte) method is used to write a single byte to the OutputStream. The write() method of an OutputStream takes an int which contains the byte value of the byte to write. Only the first byte of the intvalue is written. The rest is ignored.

Subclasses of OutputStream may have alternative write() methods. For instance, the DataOutputStreamallows you to write Java primitives like int, long, float, double, boolean etc. with its corresponding methods writeBoolean(), writeDouble() etc.

Here is an OutputStream write() example:

OutputStream output = new FileOutputStream("c:\data\output-text.txt");

while(hasMoreData()) {
  int data = getMoreData();
  output.write(data);
}
output.close();

This OutputStream write() example first creates a FileOutputStream to which the data will be written. Then the example enters a while loop. The condition to exit the while loop is the return value of the method hasMoreData(). The implementation of hasMoreData() is not shown, but imagine that it returns true if there is more data to write, and false if not.

Inside the while loop the example calls the method getMoreData() to get the next data to write to the OutputStream, and then writes that data to the OutputStream. The while loop continues until hasMoreData()returns false.

Note: The proper exception handling has been skipped here for the sake of clarity. To learn more about correct exception handling, go to Java IO Exception Handling.

write(byte[])

The OutputStream class also has a write(byte[] bytes) method and a write(byte[] bytes, int offset, int length) which both can write an array or part of an array of bytes to the OutputStream.

The write(byte[] bytes) method writes all the bytes in the byte array to the OutputStream.

The write(byte[] bytes, int offset, int length) method writes length bytes starting from index offsetfrom the byte array to the OutputStream.

flush()

The OutputStream’s flush() method flushes all data written to the OutputStream to the underlying data destination. For instance, if the OutputStream is a FileOutputStream then bytes written to the FileOutputStream may not have been fully written to disk yet. The data might be buffered in memory somewhere, even if your Java code has written it to the FileOutputStream. By calling flush() you can assure that any buffered data will be flushed (written) to disk (or network, or whatever else the destination of your OutputStream has).

close()

Once you are done writing data to the OutputStream you should close it. You close an OutputStream by calling its close() method. Since the OutputStream’s various write() methods may throw an IOException, you should close the OutputStream inside a finally block. Here is a simple OutputStream close() example:

OutputStream output = null;

try{
  output = new FileOutputStream("c:\data\output-text.txt");

  while(hasMoreData()) {
    int data = getMoreData();
    output.write(data);
  }
} finally {
    if(output != null) {
        output.close();
    }
}

This simple example calls the OutputStream close() method inside a finally block. While this makes sure that the OutputStream is closed, it still does not provide perfect exception handling. I have covered IO exception handling in more detail in my text about Java IO exception handling.

Java IO: Exception Handling

by ⋅ Link

Java IO: Exception Handling

original source : http://tutorials.jenkov.com/java-io/io-exception-handling.html

Streams and Readers / Writers need to be closed properly when you are done using them. This is done by calling the close() method. This requires a little thought though. Look at this code:

InputStream input = new FileInputStream("c:\data\input-text.txt");

int data = input.read();
while(data != -1) {
  //do something with data...
  doSomethingWithData(data);

  data = input.read();
}
input.close();

This piece of code looks okay at first glance. But what happens if an exception is thrown from inside the doSomethingWithData() method? That’s right! The InputStream is never closed!

To avoid this you can rewrite the code to this:

InputStream input = null;

try{
  input = new FileInputStream("c:\data\input-text.txt");

  int data = input.read();
  while(data != -1) {
      //do something with data...
      doSomethingWithData(data);

      data = input.read();
  }
}catch(IOException e){
  //do something with e... log, perhaps rethrow etc.
} finally {
  if(input != null) input.close();
}

Notice how the InputStream is now closed inside a finally clause. No matter what happens inside the try-block, the finally clause will be executed. Hence the InputStream will always be closed.

But what happens if close() throws an exception? Say the stream was already closed? Well, to catch that situation you will have to wrap the call to close() in a try-catch block too, like this:

} finally {
  try{
    if(input != null) input.close();
  } catch(IOException e){
    //do something, or ignore.
  }
}

The code to properly handle the iteration of an InputStream (or OutputStream for that matter), can bet quite ugly as you can see, once you get the correct exception handling in there too. This ugly exception handling code isn’t particularly nice to have spread throughout your code, repeated again and again. What if someone who is in a hurry cuts a corner and skips the exception handling?

Furthermore, imagine that an exception is thrown first from doSomethingWithData(). The first catch clause will catch that exception and the finally clause will then try to close the InputStream. But, what happens if an exception is also thrown from the input.close() method? Which of the two exceptions should be propagated up the call stack?

Luckily, there is a way around this problem. The solutions is called “Exception Handling Templates”. Create an exception handling template that properly closes your stream after use. This template is written once, and reused throughout your code. Nice and simple. You learn more, go to Exception Handling Templates in Java.

Java IO Exception Handling From Java 7

From Java 7 on and forward Java contains a new exception handling mechanism called “try with resources”. This exception handling mechanism is especially targeted at handling exception handling when you are using resources that need to be closed properly after use, like InputStream, OutputStreametc. You can read more about it in my tutorial about Try With Resources in Java 7.

Java IO: Exception Handling

by ⋅ Link

Java IO: Exception Handling

original source : http://tutorials.jenkov.com/java-io/io-exception-handling.html

Streams and Readers / Writers need to be closed properly when you are done using them. This is done by calling the close() method. This requires a little thought though. Look at this code:

InputStream input = new FileInputStream("c:\data\input-text.txt");

int data = input.read();
while(data != -1) {
  //do something with data...
  doSomethingWithData(data);

  data = input.read();
}
input.close();

This piece of code looks okay at first glance. But what happens if an exception is thrown from inside the doSomethingWithData() method? That’s right! The InputStream is never closed!

To avoid this you can rewrite the code to this:

InputStream input = null;

try{
  input = new FileInputStream("c:\data\input-text.txt");

  int data = input.read();
  while(data != -1) {
      //do something with data...
      doSomethingWithData(data);

      data = input.read();
  }
}catch(IOException e){
  //do something with e... log, perhaps rethrow etc.
} finally {
  if(input != null) input.close();
}

Notice how the InputStream is now closed inside a finally clause. No matter what happens inside the try-block, the finally clause will be executed. Hence the InputStream will always be closed.

But what happens if close() throws an exception? Say the stream was already closed? Well, to catch that situation you will have to wrap the call to close() in a try-catch block too, like this:

} finally {
  try{
    if(input != null) input.close();
  } catch(IOException e){
    //do something, or ignore.
  }
}

The code to properly handle the iteration of an InputStream (or OutputStream for that matter), can bet quite ugly as you can see, once you get the correct exception handling in there too. This ugly exception handling code isn’t particularly nice to have spread throughout your code, repeated again and again. What if someone who is in a hurry cuts a corner and skips the exception handling?

Furthermore, imagine that an exception is thrown first from doSomethingWithData(). The first catch clause will catch that exception and the finally clause will then try to close the InputStream. But, what happens if an exception is also thrown from the input.close() method? Which of the two exceptions should be propagated up the call stack?

Luckily, there is a way around this problem. The solutions is called “Exception Handling Templates”. Create an exception handling template that properly closes your stream after use. This template is written once, and reused throughout your code. Nice and simple. You learn more, go to Exception Handling Templates in Java.

Java IO Exception Handling From Java 7

From Java 7 on and forward Java contains a new exception handling mechanism called “try with resources”. This exception handling mechanism is especially targeted at handling exception handling when you are using resources that need to be closed properly after use, like InputStream, OutputStreametc. You can read more about it in my tutorial about Try With Resources in Java 7.

Java IO: Concurrent IO

by ⋅ Link

Java IO: Concurrent IO

original source : http://tutorials.jenkov.com/java-io/concurrent-io.html

Sometimes you may need to process input and output concurrently. In other words, you may need to have more than one thread processing input and producing output. For instance, you may have an application that needs to process a large number of files on the disk. This can be done in parallel with performance gain. Or you may have a server, like a web server or chat server, that receives many individual connections and requests. These may also be processed in parallel with some performance gain as result.

If you need concurrent IO, here are a few general issues you should be aware of:

You should not have more than one thread read from an InputStream or Reader at the same time. Nor should you have more than one thread write to an OutputStream or Writer at the same time. If you, you have no way to guarantee how much of the input each thread will read, or in what sequence the threads write data to the output stream.

You may be able to have more than one thread use a stream, reader or writer if they use it sequentially. For instance, you may have one thread determine from the input what type of request it is, then hand it over to the appropriate thread for further processing. This is possible since the access to the stream / reader / writer is sequential. Note, that the code that hands over the stream between the threads should be properly synchronized.

Note: In Java NIO you are able to have a single thread read from / write to more than “channel”. For instance, if you have a lot of network connections open, but there is only data on each connection rarely, for instance in a chat server, you can have a single thread monitor all channels (connections). Java NIO is a different story though, and will be covered in a later tutorial.