Developing with Grizzly / Building a Example Client Server Application

Prerequisites

This tutorial assumes that you have some basic knowledge of, or programming experience with, the following technologies.

• Java NIO libraries
• How to get and build the Grizzly project with NetBeans IDE 6.0
• How to check-out a version of Grizzly and get it working in Eclipse

Software Needed for This Tutorial

Before you begin, you need to install the following software on your computer:

• Grizzly NIO Framework (download)
• Grizzly Framework Samples (download)

Protocol Layout

Some Details on Custom Protocol Messages

The example custom protocol currently defines 6 different kinds of Messages.
Note: The message names are similar to the Messages defined in GIOP Standard (but of course GIOP is much more than this simple example protocol)

A client sending a RequestMessage normally expects a reply. Because a client may be multithreaded a Request Id is associated with each request and its reply. This allows a server to reply to a client request in different orders. The protocol also supports fragmented messages. So RequestMessage and ReplyMessage can be split into several fragments. The first fragment is the normal message with a set more-fragments-flag. Each following FragmentMessage has the more-fragments-flag also set to true. The last MessageFragment has the flag set to false.

top

Setting up Grizzly Framework on Client and Server

Setting up the Client

Controller controller = new Controller(); //  see 1)

TCPSelectorHandler selectorHandler = new TCPSelectorHandler(true); // true for Client side
selectorHandler.setSelectionKeyHandler(new BaseSelectionKeyHandler());//  see 2)
controller.addSelectorHandler(selectorHandler);

DefaultProtocolChain protocolChain = new DefaultProtocolChain();// see 3)
protocolChain.addFilter(CustomProtocolParser.createParserProtocolFilter( null); //  see 4)
protocolChain.addFilter(new SampleDispatcher()); //  see 5)


TCPConnectorHandler connectorHandler=(TCPConnectorHandler) controller.acquireConnectorHandler(Controller.Protocol.TCP);
.
.
callbackHandler =new CallbackHandler {...}; //see 6)
connectorHandler.connect(address, callbackHandler,selectorHandler); // see 7)

Code Comments

1. Controller administers all Grizzly components which need to collaborate together to provide the Grizzly enhanced NIO Service
2. The default Grizzly behavior is to close a client server socket after 30 secs. Since a connection should be permanent,
   Controller will be given a new SelectorHandler with an adjusted Keyhandler
3. The BaseSelectionKeyHandler has no default Timeout. So now connections will be long lasting
4. The ProtocolChain will be invoked every time chunks of bytes arrive on the connection
5. The example CustomProtocolClient filter will parse these chunks back into messages
6. The example SampleDispatcher filter will invoke the businesslogic layer
7. Since the connection will be non blocking a CallbackHandler is defined
8. After the Controller has been setup and started a ConnectorHandler uses a CallbackHandler to build a connection.
   This ConnectorHandler will also be used to write messages to the server

top

When setting up a client to be non blocking a CallbackHandler needs to be provided to Grizzly. Broadly Grizzly does not change the events native java NIO exposes. So when a connection is ready to be processed
NIO produces Connect, Read, Write Events and Grizzly invokes the equivalent CallbackHandler On-Methods.

 public void onRead(IOEvent ioEvent) {   
    Context ctx = ioEvent.attachment();
    .
    .	
    ctx.getProtocolChain().execute(ioEvent.attachment()); // see 1)
	
}
public void onWrite(IOEvent ioEvent) {
   // see 2)
}

Code Comments

1. On the client side Grizzly default behavior is to not use a ProtocolChain at all. For this reason we need to invoke ProtocolChain from onRead
2. Client will handle writes with an ConnectorHandler. So this method stays empty

Setting up the Server

Setting up a server is even simpler. Using a ProtocolChain is the default so no need for a CallbackHandler. The server will reuse the client example CustomProtocolParser. Of course it needs to also add a server filter which invokes buisnesslogic.

   Controller controller = new Controller();
   TCPSelectorHandler tcpSelectorHandler = new TCPSelectorHandler(); // server side

   BaseSelectionKeyHandler keyHandler = new BaseSelectionKeyHandler();
   tcpSelectorHandler.setSelectionKeyHandler(keyHandler);
   tcpSelectorHandler.setPort(SERVER_LISTEN_PORT);
   controller.addSelectorHandler(tcpSelectorHandler);
   final DefaultProtocolChain protocolChain = new DefaultProtocolChain();
   protocolChain.addFilter(CustomProtocolParser.createParserProtocolFilter(null));
   protocolChain.addFilter(new ServerDispatcher()); // Filter with Server Businesslogic
   protocolChain.setContinuousExecution(true);

top

Getting work done with Protocol Filters

WorkerThread

Now because of the above configuration when NIO signals "bytes are ready to be received" Grizzly will start a ProtocolChain. The chain will not be run on Grizzly's main Thread.
Instead the chained Protocol Filters will be run by a WorkerThread.
One special Property of WorkerThread is its ByteBuffer in which a Filter called ReadFilter stores bytes it reads of the connection.

public abstract class WorkerThread extends Thread {
  protected ByteBuffer byteBuffer;
   public void setByteBuffer(ByteBuffer byteBuffer){ // see 1)
        this.byteBuffer = byteBuffer;
    }
    public ByteBuffer getByteBuffer(){ // see 2)
        return byteBuffer;
    }
	 public void run(){        
        // calls Filters in ProtocolChain
	}
...
}

Code Comments

1. The to be discussed CustomProtocolParser uses setByteBuffer(..) to hand Grizzly a new clean ByteBuffer
2. A Filter can always get hold of the current ByteBuffer

Parsing bytes to Messages

Note: Please see Scott Oaks's Blog on Grizzly Protocol Parsers for an detailed explanation on ProtocolParser and ParserProtocolFilter basics

1. just a few bytes of the header
2. a chunk of a packet
3. a whole packet
4. several packets

 protected MessageBase msg;
 
 protected ByteBuffer byteBuffer;
 
  public void startBuffer(ByteBuffer byteBuffer) {

  }
  public boolean hasNextMessage() {

  }
  public boolean isExpectingMoreData() {

  }
  public MessageBase getNextMessage() {

  }
  public boolean releaseBuffer() {
  }

Let's discuss two scenarios which might happen when parsing bytes:

1. Connection has bytes ready to be read and these bytes would makes up several packets
2. Connection has bytes ready to be read but not enough bytes for a full packet

Client sending a Request

 RemoteCall call= customProtocolClient.callRemote();
 OutputStream out=call.getOutputStream();
 // write something to out
 InputStream in =call.getInputStream();
 // read something in
}

Server receiving a Request

 abstract public void onRequestMessage(RequestMessage msg, Context ctx); // see (1) 

 abstract public void onMessageError(MessageError msg, Context ctx); // see (2)

 private void dispatch(final Message msg, final Context ctx) { 
       ctx.incrementRefCount(); // see (3)
	   
        executorService.execute(new Runnable() {
            public void run() {
                switch (msg.getMessageType()) {
                    case Message.Message_Request:
                        onRequestMessage((RequestMessage) msg, ctx);
                        break;
                    case Message.Message_Error:
                        onMessageError((MessageError) msg, ctx);
                        break;  
                }
                workerCtx.getController().returnContext(ctx); // see (4)
            }
        });
    }

WorkerThread invokes MessageDispatcher on the ProtocolChain. It will then call MessageDispatcher.dispatch(..) with the ProtocolChain's Context Object. Briefly a Context has all kinds of abilities Filters might need to communicate with the Grizzly Framework.

Here are just a couple of Context's features:

• getters for many Controller Components
• can write bytes back to the current Connection
• store Attributes in different Scopes ProtocolChain, Connection,...

In the above code the server's businesslogic (1) and (2) will be executed on a new Thread. But Context is a Grizzly pooled resource. To prevent the WorkerThread from releasing Context.incrementRefCount (3) must be called. This ensures that Context won't be recycled. In (4) businesslogic Thread then marks Context to be released.

Note: Since example client also registers a MessageDispatcher on the ProtocolChain it also acts as a server that can handle RequestMessages.

top

Summary

By touching some of the main points the reader should now have a kickstart into understanding the Grizzly framework filter example. Readers interested in the example should just check out from subversion the latest Grizzly version and execute com.sun.grizzly.standalone.framework.Main. Hopefully this tutorial helps to understand the following points a little better:

• How-to set a Grizzly ProtocolChain on client and server
• The roles that WorkerThread, ByteBuffer and Context play
• How-to write a ProtocolParser to parse a custom protocol
• How-to start a new Thread from the ProtocolChain

top

See Also

Here are some further links.

• Writing a TCP/UDP stack supporting the SIP protocol using the Grizzly Framework
• Why SelectionKey.attach() is evil