Vert.x

Verticles running in Vert.x often need to process blocks of data. For instance, data from an incoming HTTP request, data loaded from disk, or data generated as response to an HTTP request etc. Vert.x provides a Buffer interface (io.vertx.core.buffer.Buffer) to help you handle such data blocks.

A Buffer in Vert.x can hold binary data. As such a Buffer is similar to a byte array, except the Buffer can expand its capacity dynamically as you write data to it.

Creating a Buffer

Creating a Buffer is done using the static buffer() method in the Buffer interface. Here is how creating a Vert.x Buffer looks:

Buffer buffer = Buffer.buffer();

You can also create a Buffer with some data inside from the start. Here is how you create a Buffer initialized with bytes from a byte array:

byte[] initialData = new byte[]{1, 2, 3};

Buffer buffer2     = Buffer.buffer(initialData);

You can also initialize a Buffer with the contents of a String. Here is an example of creating a Buffer initialized to the value of a String:

Buffer buffer3 = Buffer.buffer("initial data");

If you want the bytes stored in the Buffer to be encoded using a special encoding (e.g. UTF-8, UTF-16 etc.) you can specify the encoding as the second parameter to the buffer() method, like this:

Buffer buffer4 = Buffer.buffer("initial data", "UTF-8");
Buffer buffer5 = Buffer.buffer("initial data", "UTF-16");

This is equivalent to this:

Buffer buffer6 = Buffer.buffer("initial data".getBytes("UTF-8"));
Buffer buffer7 = Buffer.buffer("initial data".getBytes("UTF-16"));

Buffer Length

You can read the length of a Buffer using its length() method. Here is an example:

Buffer buffer = Buffer.buffer();

System.out.println("buffer.length() = " + buffer.length());

Writing to a Buffer

You can write to a specific position inside a buffer using one of the set...() methods. Here are some examples:

Buffer buffer = Buffer.buffer();

System.out.println("buffer.length() = " + buffer.length());

buffer.setByte  ( 0, (byte)  127);
buffer.setShort ( 2, (short) 127);
buffer.setInt   ( 4,         127);
buffer.setLong  ( 8,         127);
buffer.setFloat (16,      127.0F);
buffer.setDouble(20,      127.0D);

System.out.println("buffer.length() = " + buffer.length());

Notice that the length of the buffer starts as 0. Then, as data is written into it, the buffer expands to fit the required size. After executing the code above, the length of the buffer is 28.

You can also write data to a Buffer using one of the append...() methods. Here are some examples:

Buffer buffer = Buffer.buffer();

System.out.println("buffer.length() = " + buffer.length());

buffer.appendByte  ((byte)  127);
buffer.appendShort ((short) 127);
buffer.appendInt   (        127);
buffer.appendLong  (        127);
buffer.appendFloat (     127.0F);
buffer.appendDouble(     127.0D);

System.out.println("buffer.length() = " + buffer.length());

The append...() methods do not need an index as parameter. They always append the data to the end of the Buffer. The length of the Buffer will be 27 after executing this code (because all data following the first byte is inserted from index 1, and not index 2 as in the previous example).

Reading From a Buffer

You can read the data stored in a Buffer using the many get...() methods. Here are some examples:

byte   aByte   = buffer.getByte  ( 0);
short  aShort  = buffer.getShort ( 2);
int    anInt   = buffer.getInt   ( 4);
long   aLong   = buffer.getLong  ( 8);
float  aFloat  = buffer.getFloat (16);
double aDouble = buffer.getDouble(20);