Package com.faunos.skwish.ext.http

An experimental read-only HTTP interface to skwish is provided here.

See:
Description

Class Summary

MappedSkwishResponseFactory	Packages a mapped skwish Provider with a skwish HTTP ResponseFactory.
MappedUriProvider	A filter on a skwish service provider that maps input URIs to output URIs.
QueryStringConsts	Defines some constants used by skwish in query strings.
SkwishHttpMountPoint	Represents a skwish "mount" point on the HTTP server.
SkwishHttpServer	An HTTP server with convenience methods for setting up skwish stores and serving entries from them.
SkwishResponseFactory	The skwish HTTP application.

Package com.faunos.skwish.ext.http Description

An experimental read-only HTTP interface to skwish is provided here.

Version 0.2.0 Note

The setup API has changed since the previous release. And it will change again in the next release. We'll keep the skwish mount-point idea below and ditch the specialized SkwishHttpServer class. Delaying that small refactoring right now in order to make a release.

Setup

Setting up the server (programmatically) is straightforward. To have the server begin listening on port 8880, for instance, code the following:

    
        SkwishHttpServer server = SkwishHttpServer.newInstance(8880);

Or, for a debug instance that echoes output to the std out:

    
        SkwishHttpServer server = SkwishHttpServer.newDebugInstance(8880);

Create a skwish mount point

    
        SkwishHttpMountPoint mountPoint = server.getSkwishMountPoint("/skwish-root/", true);

/skwish-root/ will be the root URI for serving up skwish entries. Now to serve entries from a segment store, you must create a URI mapping to that store. Here are 2 ways you can setup such a mapping once you have the mountPoint. The first, assumes you already held a reference to the store before you created the server:

        // suppose you already have a reference to the store
        SegmentStore store = ..
        mountPoint.mapRelativeUriToSkwish("MyStore", store);

Alternatively, you can use the uri (file path) used to load the store from the default provider (how you got the store in the snippet above, to begin with) to map an HTTP URI to the store:

        mountPoint.mapRelativeUriToSkwish("MyStore", <path-to-store>);

Start the server to begin serving HTTP requests

        server.start();

Multiple mappings may be defined this way. It's okay modify mappings while the server is running. (And it's okay to start the server before any mappings are defined: all requests will be greeted with 404s until a mapping is defined.)

Retrieving entries from a browser

Continuing with the example above, typing the URL below in your browser

        http://<server-name>/skwish-root/MyStore?id=0

retrieves the entity (entry, in skwish-speak) with id 0 from the store in plain text (text/plain).

Recall that skwish knows nothing about the content it stores. Rather, it's the application that does. So the server allows the client to set the Content-Type header through the ct parameter of the query string. To retrieve the previous entry in HTML, for example, type:

        http://<server-name>/skwish-root/MyStore?id=0&ct=text/html

(It helps if entry 0 is in fact HTML.) In the above query string, the text/html value is strictly illegal: it should be URL-encoded, but our parser picks it up still.

The server recognizes the following abbreviations for the ct value.

• T = text/plain
• H = text/html

Other abbreviations will be added in later releases.

Transaction ID support

An entry's id may be qualified by specifying a transaction id through the query string's tid parameter. For example,

        http://<server-name>/skwish-root/MyStore?id=0&tid=0

The server uses the tid parameter in order to increment the specified entry id by the transaction gap amount. See TxnSegment for details.

Implementation Notes

This is a newly rolled out HTTP implementation, and is thus unproven. And it is nothing near complete. The point of the exercise (besides scratching an itch) is to demonstrate the NIO capabilities of skwish in a non-blocking network I/O setting. And what better protocol candidate than HTTP?

Why roll out your own HTTP server?

In a nutshell, because a non-blocking java HTTP server implementation that supported non-blocking calls to FileChannel.transferTo(SocketChannel) could not be found. (If you know of a good implementation I should try instead, do drop me a line--BF.)