Locumi Documentation
The following is preliminary documentation that informally describes the protocol and architecture of Locumi.
Introduction
Locumi is a mechanism whereby peers in the following
networking environments can become HTTP servers:
- peers behind firewalls
- peers behind network address translating (NAT) gateways
- peers who cannot accept incoming socket connections due to device or API limitations (such as J2ME-CLDC-MIDP devices)
This is done by proxying these peers with an 'HTTP server proxy' such that
the peer regains, by proxy, the characteristics of being IP addressable and
being able to accept incoming connections.
The original motivation behind Locumi is to be able to turn a Java 2 Micro
Edition (J2ME) Mobile Information Device (MID) into a web server so that it
can serve up interesting data. Beyond that, Locumi is useful for generic P2P applications such as gaming, remote data collection, mobile webcams, etc. However, it is not intended to provide a generic asynchronous messaging layer that may be desired in P2P applications.
Design
Essentially what Locumi does is this:
- A peer connects to a Locumi server with
an HTTP POST request of '/getrequest'.
- When a client connects to the Locumi server, the server looks up the the peer that the client is trying to communicate with and inserts the client's connection into a connection queue for that peer.
- The proxy then dequeues that connection, and relays data back to the peer. A Request ID is attached to the HTTP headers, identifying the interaction.
- The peer will then response with an HTTP POST of '/postresponse', and included in the headers will be the Request ID.
- The proxy looks up the client connection for that request ID, and then transfers the HTTP response from the peer back to the client.
Implementation Architecture
Locumi is based on the Java Servlet API 2.2. It has been tested with Tomcat
3.2.1. Obtain Tomcat from http://jakarta.apache.org.
Building Locumi
If you have a source distribution of Locumi, you will need to build the
sources. Jakarta-Apache's Ant build tool is used to build Locumi. Obtain Ant
from http://jakarta.apache.org. After you have installed Ant, modify the
build.properties file to reflect your systems setup. Then just type 'ant'.
The locumi.war file will be built and copied to your servlet container's
webapps directory.
Installing Locumi
If you have obtained a binary distribution of Locumi, you simply need to
copy the locumi.war file to your webapps directory of your servlet
container.
Running Locumi
If your built Locumi from the sources or installed the binary distribution,
you will have a locumi.war file in your servlet container's webapps directory.
The next time you start your servlet container, Locumi will start
automatically, if that's how you have your container configured. On a
default deployment of Tomcat, you're URLs for interacting with the servlet
container are as follows:
- peers connect to: 'http://localhost:8080/locumi/httpsvrproxy'
- clients connect to: 'http://localhost:8080/locumi/client'
Using Locumi
To use Locumi, you'll need a compatible "proxied HTTP server" that speaks
the Locumi protocol. kHTTP, which is J2ME-MIDP compliant, is such a server. It
can be obtained at khttp.enhydra.org.