Chapter 1: Introduction to New InputOutput API | Java InstantCode. Developing Applications Using Java NIO

Java2 Platform, Standard Edition (J2SE) provides a New Input/Output (NIO) API that provides features for polling, buffer management, scalable network and advanced I/O file system, character conversion, and regular-expression matching. Development of NIO API was proposed in Java Specification Request (JSR) 51. JSR contains description of the proposal to develop new specifications for the for the Java platform. Using NIO API, you can create applications that can search for regular expressions in a file, read and write data in a file, transfer data over a network, and encode and decode characters . In addition, NIO API provides support for scalable I/O operations for sockets and files, such as file locking and memory mapping.

NIO API consists of the java.nio, java.nio.channels, java.nio.channels.spi, java.nio.charset, and java.nio.charset.spi packages.

This chapter explains the packages provided by NIO API, along with the classes included in each package. This chapter also explains the commonly used methods provided by each class.

The java.nio Package

The java.nio package contains various classes and methods for buffer management. You can use the java.nio classes to store the content of a file in a buffer in the form of bytes and characters. Buffer is a container to store fixed amount of specific primitive type data, such as byte, character, integer, and float.

Note	To learn more about java.nio package, see: http://java.sun.com/j2se/1.4.2/docs/api/java/nio/package-summary.html.

The various attributes of a buffer are:

capacity : Represents the number of elements stored in a buffer.
limit : Represents the index of the first element stored in the buffer. You cannot perform read and write operation on the limit. The limit of a buffer is always positive and greater than the capacity.
position : Represents the valid index position in the buffer for performing read and write operation. The position is always positive and greater than the limit.

Figure 1-1 shows the class diagram for the java.nio package:

click to expand: this figure shows the classes associated with the java.nio package.

Figure 1-1: The java.nio Package

Buffer

The Buffer class is an abstract class that provides common methods to all its subclasses, such as ByteBuffer, ByteOrder, and CharBuffer. The various methods declared in the Buffer class are:

capacity() : Returns an integer that specifies the storage capacity of the buffer.
clear() : Clears the buffer. This method makes the buffer ready for a new sequence of channel read or put operation. The clear() method also returns a reference to buffer objects.
flip() : Sets the buffer to empty state from a fill state and makes a buffer ready for channel-write or get operation.
hasRemaining() : Returns a Boolean value to indicate whether or not any element exists between the current position and the limit. The method returns true if any element exists in the buffer.
isReadOnly() : Returns a Boolean value that indicates whether or not the buffer is read-only. The method returns true if the buffer is read-only.
limit() : Returns an integer value that indicates the buffer limit. This method throws the IllegalArgumentException exception that occurs when an illegal argument is passed within the limit() method.
mark() : Sets the mark of a buffer at its position. A mark is the index to which the position of a buffer is reset.
position() : Returns an integer that indicates the current position of the buffer.
remaining() : Returns an integer that indicates the number of elements between the current position and limit of the buffer.
reset() : Resets the current position of a buffer to the previously- marked position. This method throws the InvalidMarkException exception that occurs when the mark is not defined in the buffer.
rewind() : Reverses the order of the data in the buffer. The position is set to zero and discards the mark of the buffer.

ByteBuffer

The ByteBuffer class represents a byte buffer. This is a subclass of the Buffer class. The most commonly used methods in the ByteBuffer class are:

allocate() : Returns the ByteBuffer class object. The allocate() method allocates a new byte buffer. You need to specify the size of the new byte buffer.
array() : Returns a byte array. The returned array backs up the buffer. If you change the content of the buffer, the content in the returned array is also changed. This method throws two exceptions, ReadOnlyBufferException and UnsupportedOperationException. The ReadOnlyBufferException exception occurs when the put() or compact() method is invoked on a read-only buffer. The UnsupportedOperationException exception occurs when the requested operation is not supported by the Java Virtual Machine (JVM).
arrayOffset() : Returns an integer value that specifies the offset within the backup array of the buffer. This method also throws two exceptions, ReadOnlyBufferException and UnsupportedOperationException.
asCharBuffer() : Returns an object of the CharBuffer class. The asCharBuffer() method creates a view of the byte buffer as a char buffer.
asDoubleBuffer() : Returns an object of the DoubleBuffer class. This method creates a view of the byte buffer as a double buffer.
asFloatBuffer() : Returns an object of the FloatBuffer class. This method creates a view of the byte buffer as a float buffer.
asIntBuffer() : Returns an object of the IntBuffer class. The asIntBuffer() method creates a view of the byte buffer as int buffer.
asLongBuffer() : Returns an object of the LongBuffer class. This method creates a view of the byte buffer as a long buffer.
asReadOnlyBuffer() : Returns an object of the ByteBuffer class. This method creates a new read-only byte buffer that shares the content of the byte buffer with another byte buffer.
asShortBuffer() : Returns an object of the ShortBuffer class. This method creates a view of the byte buffer as a short buffer.
compact() : Returns a ByteBuffer object. The compact() method compacts the buffer by copying the bytes between the current position and limits to the beginning of the buffer. This method throws a ReadOnlyBufferException, if the buffer is read-only.
compareTo() : Compares the object of the ByteBuffer class to another object of another buffer and returns an integer value: positive, negative, or zero. A positive integer indicates that the buffer is greater than the specified buffer. A negative integer indicates that the buffer is less than the specified buffer whereas zero indicates that the buffer and the specified buffer are equal. The compareTo() method throws a ClassCastException if the object passed is not a byte buffer.
duplicate() : Returns an object ByteBuffer class. The duplicate() method creates a new byte buffer and shares the content of the buffer with the newly created byte buffer.
getChar() : Returns a char type value at the current position of the buffer. The getChar() method reads the next two bytes from the current position of the buffer, converts the bytes into a char value according to the current byte order, and then increments the position by two. The getChar() method throws the BufferUnderflowException exception if there are less than two bytes in the buffer.
getDouble() : Returns a double value at the current position of the buffer. The getDouble() method reads the next eight bytes from the current position of the buffer, converts the bytes into a char value according to the current byte order, and then increments the position by eight. The getDouble() method throws the BufferUnderflowException exception if there are less than eight bytes in the buffer.
getFloat() : Returns a float type value at the current position of the buffer. The getFloat() method reads the next four bytes from the current position of the buffer, converts the bytes into a char value according to the current byte order, and then increments the position by four. The getFloat() method throws the BufferUnderflowException exception if there are less than four bytes in the buffer.
getInt() : Returns an int type value at the current position of the buffer. The getInt() method reads the next four bytes from the current position of the buffer, converts the bytes into a char value according to the current byte order, and then increments the position by four. The getInt() method throws the BufferUnderflowException exception if there are less than four bytes in the buffer.
getLong() : Returns a long type value at the current position of the buffer. The getLong() method reads the next eight bytes from the current position of the buffer, converts the bytes into a char value according to the current byte order, and then increments the position by eight. The getLong() method throws the BufferUnderflowException exception if there are less than 8 bytes in the buffer.
getShort() : Returns a short type value at the current position of the buffer. The getShort() method reads the next two bytes from the current position of the buffer, converts the bytes into a char value according to the current byte order, and then increments the position by two. The getShort() method throws the BufferUnderflowException exception if there are less than two bytes in the buffer.
putChar() : Returns an object of the ByteBuffer class. The putChar() method writes two bytes at the current position into the buffer and then increments the position by two. The putChar() method throws the BufferOverflowException exception if there are less than two bytes left in the byte buffer. In addition, the putChar() method throws the ReadOnlyBufferException exception if the buffer is read-only.
putDouble() : Returns an object of the ByteBuffer class. The putDouble() method writes eight bytes that contain the specified char value into the buffer at the current position, and then increments the position by eight. The putDouble() method throws the BufferOverflowException exception if there are less than 8 bytes left in the byte buffer. In addition, the putDouble() method throws the ReadOnlyBufferException exception if the buffer is read-only.
putFloat() : Returns an object of the ByteBuffer class. The putFloat() method writes four bytes that contain the specified char value into the buffer at the current position, and then increments the position by four. The putFloat() method throws the BufferOverflowException exception if there are less than four bytes left in the byte buffer. In addition, the putFloat() method throws a ReadOnlyBufferException, if the buffer is read-only.
putInt() : Returns an object of the ByteBuffer class. The putInt() method writes four bytes that contain the specified char value into the buffer at the current position, and then increments the position by four. The putInt() method throws the BufferOverflowException exception if there are less than four bytes left in the byte buffer. In addition, the putInt() method throws a ReadOnlyBufferException, if the buffer is read-only.

ByteOrder

The ByteOrder class defines the constants that determine the type of byte order to use when storing or retrieving byte values from a buffer. This class acts as a type-safe enumeration classes. Enumerations help create named values. The ByteOrder class defines two static values that denote byte order:

BIG_ENDIAN : Denotes the BIG_ENDIAN byte order. The bytes of a multibyte value are ordered from the most significant to least significant.
LITTLE_ENDIAN : Denotes the LITTLE_ENDIAN byte order. The bytes of a multibyte value are ordered from the least significant to most significant.

The most commonly used method in the ByteOrder class is the nativeOrder() method. This method returns the native byte order of the hardware on which JVM is running. Using the nativeOrder() method, the performance-sensitive Java code can allocate direct buffers with the same byte order as the hardware. The nativeOrder() method is a static method.

CharBuffer

The CharBuffer class represents a character buffer. The CharBuffer class provides methods to copy the String type variables into CharBuffer. All these methods return the CharBuffer object. The most commonly used methods in the CharBuffer class are:

allocate() : Creates a buffer object and allocates space to hold data elements. You also need to specify the size of the buffer to hold data elements when you invokes the allocate() method. This method throws two exceptions, ReadOnlyBufferException and UnsupportedOperationException.
wrap() : Wraps a character array into a buffer.
slice() : Creates a new character buffer. The content of the new buffer starts from the current position of the buffer.
duplicate() : Creates a new buffer. The new buffer shares the content of the buffer.
asReadOnlyBuffer() : Creates a new read-only character buffer. The new character buffer shares the content of the buffer.
get() : Reads the specified character from the current position of the buffer, and then increments the position by one. The method throws the BufferUnderFlowException exception if the current position of the buffer is smaller than the limit of the buffer.
put() : Writes the specified character into the current position of the buffer, and then increments the position by one. This method throws two exceptions, BufferOverflowException and ReadOnlyBufferException.
hasArray() : Returns a Boolean value. The hasArray() method indicates whether or not the given buffer is copied by the character array.