>> Complete Source Code for the Tutorial

Using Grizzly Connection Caching. 

This document provides a complete tutorial for understanding and using the Grizzly Connection Caching framework. The example code also demonstrates the general use of Grizzly and its underlying NIO technologies. 

For more information about Grizzly, see the Grizzly Home page on the java.net web site.

Expected duration: 45 minutes

Contents

Tutorial Requirements

Before you proceed, make sure you review the requirements in this section.

Introduction

This tutorial will show step by step how to build a very simple "messaging ORB" using the Grizzly framework on the server side and the general NIO on the client side. The underlying design is briefly discussed here first: 

Server side

1. The server object invocation is purely asynchronous, in that requests are sent to servers asynchronously.   
2. Responses are sent back to clients asynchronously too via a client listener end point, whose address comes with the original request.  
3. We call this "messaging" ORB (morb) to emphasize the asynchronous nature of the resulting programming model, as opposed to the underlying wire protocol, which one way or the other uses the same Grizzly, e.g. 
   
4. This is not a real ORB of couse. To minimize the distraction (as a Grizzly tutorial), remote object invocation semantics have been largely ignored.  

Client side

1. Clients send requests asynchronously and registers with its local runtime a callback handler for "future" responses.
   
2. Typical ORB plays dual role of server and client. In this tutorial, however, we assume that the client runtime only generates requests (hence a pure client).
   
3. Raw NIO is used to build the simple client runtime to interact with the server ORB instance. NIO tricks/guidelines (ref. Grizzly document) are followed. In some way, the client implementation tries to show the "troubles" for not using a NIO framework or what may be under the hood of an NIO framework.

Server-side Implementation

In the following, we will describe how the server side function (morb) is implemented. The server uses Grizzly framework for both receiving request messages (as server) and sending response messages (as client). As a result, both Grizzly server api and client api are used, as well as their respective connection caching mechanisms. 

1. First, we have the following interface defined to represent a server object instance that a client can invoked. As pointed out earlier, the API is made "type-less" for simplification.  
   

String handle(String request) throws Exception;

2. The actual server implementation is provided by the following class.  Exception handling is much simplfied, unless it's needed for resource reclaim or error recovery. 
   

public ServerRequestController(String serverId) { ... }      // serverId is an app. defined identifier for tracing purpose only

public String getServerId() { ... }

public InetSocketAddress getLocalAddr() { ... }              // the local address that the controller (i.e. morb instance) binds to

public void register(String objectId, RequestHandler handler) { ... }    // an server object instance: objectId essentially provides "naming"

public void unregister(String objectId) { ... }    

public void open(String addr) throws Exception { ... }    

public void close() { ... }

Now we will describe the initialization open() and shutdown close() routines.  The code is annotated as following:

3. As you can see from the above code, it is mostly transparent to enable connection caching on Grizzly.  The above code refers to MessageDecoder, which defines the protocol filter that does the actual processing of the incoming request messages (TCP). This filter class is defined as an inner class as the following:
   

The message format is quite dummy, but it has the essential parts of client-server invocation semantics. The receiver thread (as provided from Grizzly) will be also responsible for sending out the response to the wire (asynchronously). ARP could also be used here, to make it fancier. 

Overall, processing the receiving message is straightforward (with the use of Grizzly) . 

The following code shows the detail of sendResponse. The more obvious use of Grizzly connection caching actually happens here. As you can see from the code, under the predefined cache pool limits, an outbound connection (to a remote client) will be acquired from the connection cache pool directly (if available). This saves the cost of generating a new connection, which involves expensive native socket operation.

The actual handling of sending the response is again asynchronous, via the callback API (Grizzly).

Client-side Implementation

Due to the space limitation, we will not show the client code here. In the following, the client-side design is briefly described. It is of course possible to implement the client runtime (interacting with a remote MORB) with Grizzly too, or any other implementation as long as it aligns with the server morb protocol. 

The provided client implementation uses the basic NIO and adopts the following guidelines as recommended in the Grizzly document:

• the use of a temporary write selector 
• the use of a temporary read selector
  

Putting things together

In this section, we will go through the server and client setup, and describe what's expected from the example testing program, and how to observe the connection caching behavior.

1. On the server side, an MORB is instantiated as the following:  
   

2. On the client side, a standalone client app. is created for the demo purpose. It uses the client runtime support we introduced earlier. The client code sequentially invokes a list of server objects, asynchronously. A single dispatch thread manages the inbound connections (responses). The main application routine, under the user control, loops through the list of server ids (input parameter) and sends each one a request containing an auto-generated sequence id.  In dealing with the server-side inbound connection cache, a failed outbound connection (request) will be retried once if the cached one fails the first time. Upon successful sending a request, the outbound connection will be cached via a simple per-server-id hashmap.
   

With the above example test application, both the inbound connection cache and outbound connection cache of the Grizzly framework are demonstrated. Interested readers may try to adjust the # of client instances and server instances, and use tools like "netstat -nt" to monitor the open connections between clients and servers, and their variations.

Conclusion

I hope you find this tutorial useful in understanding the Grizzly and its connection cache framework. Comments to make the overall tutorial simpler (i.e. shorter) or more complicated (i.e. revealing more Grizzly) are more than welcome!

top

>> Complete Source Code for the Tutorial