Implementation of a protocol at the level that is at normally requires a large amount of bug-prone code, such as code for handling tcp/ip connections, multi-threading, and request object reuse. Resin provides a simple way to handle protocols without requiring the implementation of that code.
Applications take advantage of Resin's highly tested and configurable server architecture and only need to implement some simple objects. Two classes are required, one which extends the abstract class and one which implements the interface.
A custom class derived from is a factory that produces custom Request objects.
The Protocol passes a
object to the Request object it creates. The Request object uses the
to obtain a read stream and a write stream.
The example in this tutorial is simple, it's main purpose is to override the
createRequest method to return an instance of the
request handling object.
It also stores and returns the protocol name.
is the interface used for implementing the class that handles a request. This is where the bulk of the work is done.
handleRequest() is called for each request.
Implementations should not assume that a new request object is created
for each new connection from a client. Resin may reuse a request object once
it has finished handling a request. It is guaranteed, however, that the
handleRequest() method of a given instance will only be handling a
single request at a time.
This means that any member variables must be initialized at the
beginning of the code in
The first step in handleRequest() is usually to obtain a and a from the Connection that was stored with the constructor. These streams are used to read raw data from the client and write raw data to the client.
This tutorial then goes on to initialize a parser and perform appropriate commands, depending on what is submitted by the client. The readStream is used to determine what to do, and the writeStream is used to send the response. The implementation here depends on the protocol that is being supported.
The protocol is handled at the server level in the Resin Environment
hierarchy. This means that the code has to be available to the appropriate
classloader. A jar with your code in it can be placed in
$RESIN_HOME/lib/, for example
The use of the Protocol class is configured with and .
This tutorial has to be deployed by hand in your installation of Resin.
The filesystem location of this tutorial is at the top of this page.
To run the demo, you can find the
build/magic8ball.jar file and
copy it to
ant build file is provided. Calling "ant deploy" will build the jar and deploy it in
Start Resin, or if it is already running wait for it to notice the new library and restart. The default Resin configuration will notice the new jar file (eventually) and restart itself. If you are impatient you can stop and start the server yourself.
The simplest way to test a protocol like the
is to use
The and classes are of course Resin specific. The and are as well.
If portability is a concern, implement a class that is similar in
functionality to .
Code that class to get passed a and a
. A bare-bones Resin-specific
ServerRequest can be used as a thin
wrapper to your custom class, and the Resin's ReadStream and
WriteStream can be passed as the
OutputStream. When porting to another application server (if they
provide this kind of functionality) you can code a thin-wrapper specific to
that app-server that uses your custom Request class.