Introduction to NioFlex

nioflex-intro.md

Introduction to NioFlex 0.20-rc1

Brief Overview

NioFlex is a powerful tool that you need to fully understand to be able to take advantage of all of its features. It is recommended that you have a grasp of Java NIO, since NioFlex is built on top of it.

The current 'dev' release of NioFlex is 0.20-rc1 and it contains many important improvements over the stable 0.10.

It is recommended that you learn from this 'dev' build and not the stable 0.10 because of the numerous differences between the two.

The Core Class - NIOServer

NIOServer is the most important class in NioFlex and is the one that you will be using as the base of your server. So, how exactly do you create a server with NioFlex?

Well, it is quite simple:

import com.revtekk.nioflex.NIOServer;
import com.revtekk.nioflex.utils.SocketUtil;

import java.nio.channels.SelectionKey;
import java.nio.channels.SocketChannel;

public class MyServer extends NIOServer
{
    public MyServer(int port)
    {
        super(port);
    }
    
    @Override
    public void handleRead(SocketChannel client, SelectionKey key, SocketUtil util)
    {
        //TODO
    }
}

That is the bare minimum required for NioFlex. So exactly what does all this mean or do?

The Constructor

public MyServer(int port)
{
    super(port);
}

All the constructor does here is called the super-class' constructor. You don't need to do anything else here.

The handleRead() Method

@Override
public void handleRead(SocketChannel client, SelectionKey key, SocketUtil util)
{
    //TODO
}

The handleRead() method is called everytime data can be read by a client. The method provided you with a SocketChannel, a SelectionKey, and a SocketUtil.

The SocketUtil class is part of NioFlex and makes it easy to perform basic Java NIO operations (read/write).

The handleAccept() Method

Another method that is part of NIOServer is handleAccept(), though it isn't necessary to implement it. This is how handleAccept() looks like:

@Override
public void handleAccept(SocketChannel client, SelectionKey key)
{
    //TODO
}

The handleAccept() method is called everytime a new client is accepted by the server.

Launching the Server

The example class is complete (it implements all abstract methods of NIOServer); however, it cannot run yet. You still need to launch the server.

Simple Server Launcher

public class MyServerLauncher
{
    public static void main(String[] args)
    {
        MyServer server = new MyServer(6767);
        server.launch();
    }
}

The class MyServerLauncher, when run, will bind the server on port 6767 and launch the server on the same thread.

If you want to run the server on another thread, use the launchThread() method:

Thread serverThread = server.launchThread();

The launchThread() method returns the Thread that the server was launched on.

Note: It is perfectly acceptable to just add a main() method to the actual server class, instead of creating another class.

We now have the most-basic working NioFlex server!

The next GitHub Gist will explain how to use the SocketUtil class to simplify NIO operations (e.g. reading from and writing to SocketChannels).

Next tutorial: Using the SocketUtil Helper Class