Java NIO AsynchronousFileChannel

In Java 7 the

AsynchronousFileChannel

was added to Java NIO. The

AsynchronousFileChannel

makes it possible to read data from, and write data to files asynchronously. This tutorial will explain how to use the

AsynchronousFileChannel

.

Creating an

AsynchronousFileChannel

You create an

AsynchronousFileChannel

via its static method

open()

. Here is an example of creating an

AsynchronousFileChannel

:

Path path = Paths.get("data/test.xml");

AsynchronousFileChannel fileChannel =
AsynchronousFileChannel.open(path, StandardOpenOption.READ);

The first parameter to the

open()

method is a

Path

instance pointing to the file the

AsynchronousFileChannel

is to be associated with.

The second parameter is one or more open options which tell the

AsynchronousFileChannel

what operations is to be performed on the underlying file. In this example we used the

StandardOpenOption.READ

which means that the file will be opened for reading.

Reading Data

You can read data from an

AsynchronousFileChannel

in two ways. Each way to read data call one of the

read()

methods of the

AsynchronousFileChannel

. Both methods of reading data will be covered in the following sections.

Reading Data Via a

Future

The first way to read data from an

AsynchronousFileChannel

is to call the

read()

method that returns a

Future

. Here is how calling that

read()

method looks:

Future<Integer> operation = fileChannel.read(buffer, 0);

This version of the

read()

method takes

ByteBuffer

as first parameter. The data read from the

AsynchronousFileChannel

is read into this

ByteBuffer

. The second parameter is the byte position in the file to start reading from.

The

read()

method return immediately, even if the read operation has not finished. You can check the when the read operation is finished by calling the

isDone()

method of the

Future

instance returned by the

read()

method.

Here is a longer example showing how to use this version of the

read()

method:

AsynchronousFileChannel fileChannel =
AsynchronousFileChannel.open(path, StandardOpenOption.READ);

ByteBuffer buffer = ByteBuffer.allocate(1024);
long position = 0;

Future<Integer> operation = fileChannel.read(buffer, position);

while(!operation.isDone());

buffer.flip();
byte[] data = new byte[buffer.limit()];
buffer.get(data);
System.out.println(new String(data));
buffer.clear();

This example creates an

AsynchronousFileChannel

and then creates a

ByteBuffer

which is passed to the

read()

method as parameter, along with a position of 0. After calling

read()

the example loops until the

isDone()

method of the returned

Future

returns

true

. Of course, this is not a very efficient use of the CPU - but somehow you need to wait until the read operation has completed.

Once the read operation has completed the data read into the

ByteBuffer

and then into a

String

and printed to

System.out

.

Reading Data Via a

CompletionHandler

The second method of reading data from an

AsynchronousFileChannel

is to call the

read()

method version that takes a

CompletionHandler

as a parameter. Here is how you call this

read()

method:

fileChannel.read(buffer, position, buffer, new CompletionHandler<Integer, ByteBuffer>() {
@Override
public void completed(Integer result, ByteBuffer attachment) {
System.out.println("result = " + result);

attachment.flip();
byte[] data = new byte[attachment.limit()];
attachment.get(data);
System.out.println(new String(data));
attachment.clear();
}

@Override
public void failed(Throwable exc, ByteBuffer attachment) {

}
});

Once the read operation finishes the

CompletionHandler

’s

completed()

method will be called. As parameters to the

completed()

method are passed an Integer telling how many bytes were read, and the “attachment” which was passed to the

read()

method. The “

attachment

” is the third parameter to the

read()

method. In this case it was the

ByteBuffer

into which the data is also read. You can choose freely what object to attach.

If the read operation fails, the

failed()

method of the

CompletionHandler

will get called instead.

Writing Data

Just like with reading, you can write data to an

AsynchronousFileChannel

in two ways. Each way to write data call one of the

write()

methods of the

AsynchronousFileChannel

. Both methods of writing data will be covered in the following sections.

Writing Data Via a Future

The

AsynchronousFileChannel

also enables you to write data asynchronously. Here is a full Java

AsynchronousFileChannel

write example:

Path path = Paths.get("data/test-write.txt");
AsynchronousFileChannel fileChannel =
AsynchronousFileChannel.open(path, StandardOpenOption.WRITE);

ByteBuffer buffer = ByteBuffer.allocate(1024);
long position = 0;

buffer.put("test data".getBytes());
buffer.flip();

Future<Integer> operation = fileChannel.write(buffer, position);
buffer.clear();

while(!operation.isDone());

System.out.println("Write done");

First an

AsynchronousFileChannel

is opened in write mode. Then a

ByteBuffer

is created and some data written into it. Then the data in the

ByteBuffer

is written to the file. Finally the example checks the returned

Future

to see when the write operation has completed.

Note, that the file must already exist before this code will work. If the file does not exist the

write()

method will throw a

java.nio.file.NoSuchFileException

.

You can make sure that the file the

Path

points to exists with the following code:

if(!Files.exists(path)){
Files.createFile(path);
}

Writing Data Via a

CompletionHandler

You can also write data to the

AsynchronousFileChannel

with a

CompletionHandler

to tell you when the write is complete instead of a

Future

. Here is an example of writing data to the

AsynchronousFileChannel

with a

CompletionHandler

:

Path path = Paths.get("data/test-write.txt");
if(!Files.exists(path)){
Files.createFile(path);
}
AsynchronousFileChannel fileChannel =
AsynchronousFileChannel.open(path, StandardOpenOption.WRITE);

ByteBuffer buffer = ByteBuffer.allocate(1024);
long position = 0;

buffer.put("test data".getBytes());
buffer.flip();

fileChannel.write(buffer, position, buffer, new CompletionHandler<Integer, ByteBuffer>() {

@Override
public void completed(Integer result, ByteBuffer attachment) {
System.out.println("bytes written: " + result);
}

@Override
public void failed(Throwable exc, ByteBuffer attachment) {
System.out.println("Write failed");
exc.printStackTrace();
}
});

The

CompletionHandler

’s

completed()

method will get called when the write operation completes. If the write fails for some reason, the

failed()

method will get called instead.

Notice how the

ByteBuffer

is used as attachment - the object which is passed on to the

CompletionHandler

’s methods.