juglr.net
Class HTTPServer

java.lang.Object
  extended by juglr.net.HTTPServer

public class HTTPServer
extends java.lang.Object

A generic light weight HTTP server handling requests by forwarding them to a set of actors and sending the reponse from the actor back to the client.

The "backend" actors functions much as bottom halves in system level interrupt programming. The HTTPServer manages an actor per active HTTP connection which is considered the upper half. The upper half dispatches incoming request to the right bottom half. When the bottom half responds the upper half sends back the reply to the HTTP client.

Since:
Feb 15, 2010
Author:
Mikkel Kamstrup Erlandsen

Constructor Summary
HTTPServer(int port)
          Create a new HTTP server listening on port port.
HTTPServer(int port, MessageBus messageBus)
          Create a new HTTP server listening on port port.
 
Method Summary
 void registerHandler(java.lang.String urlRegex, Address handler, HTTP.Method... methods)
          Configure all requests with URLs matching pathRegex to be handled by the actor living at the handler address.
 void start()
          Start listening on the configured port.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HTTPServer

public HTTPServer(int port)
           throws java.io.IOException
Create a new HTTP server listening on port port. To start listening you must invoke the server's start() method. Before doing so you must install a set of handlers with the registerHandler(java.lang.String, juglr.Address, juglr.net.HTTP.Method...) method.

The HTTP server will be configured to spawn, and talk to, actors on the default message bus.

Parameters:
port - the port to listen on
Throws:
java.io.IOException - if there is an error setting up the server socket
See Also:
MessageBus.getDefault()

HTTPServer

public HTTPServer(int port,
                  MessageBus messageBus)
           throws java.io.IOException
Create a new HTTP server listening on port port. To start listening you must invoke the server's start() method. Before doing so you must install a set of handlers with the registerHandler(java.lang.String, juglr.Address, juglr.net.HTTP.Method...) method.

The HTTP server will be configured to spawn, and talk to, actors on the message bus messageBus.

Parameters:
port - the port to listen on
messageBus - the MessageBus to use
Throws:
java.io.IOException - if there is an error setting up the server socket
Method Detail

registerHandler

public void registerHandler(java.lang.String urlRegex,
                            Address handler,
                            HTTP.Method... methods)
Configure all requests with URLs matching pathRegex to be handled by the actor living at the handler address.

Messages sent from the HTTPServer to the handler are guaranteed to be instances of HTTPRequests.

The handler must reply with a HTTPResponse or Box to any incoming message, sending the reply to msg.getReplyTo(). Sending a Box as response will automatically result in a HTTP status code 200 OK. To alter the response code you must wrap the response box in a HTTPResponse.

It is strongly recommended that the handler replies in a finally clause. Failing to reply will result in dangling connections, and empty replies or timeouts for clients.

When looking up a matching handler the first one with a matching path will be used. The handlers are checked in the order they are registered.

Parameters:
urlRegex - A regular expression the request URL must match for the request to be forwarded to handler
handler - the address of the actor that handles the request
methods - the HTTP methods the handler can accept
Throws:
java.lang.IllegalStateException - if the server has had its start() method invoked

start

public void start()
Start listening on the configured port. After invoking start() the registerHandler(java.lang.String, juglr.Address, juglr.net.HTTP.Method...) method should not be called again

Throws:
java.lang.IllegalStateException - if the server has already been started