Overview

This package provides a means for listening in one an HTTP connection and recieving commands after being authenticated. The primary use case is communication between Javascript running in a browser from the Lime Wire Store web site and the Lime Wire Client. In order to do this the core component, called the {@link Dispatcher}.will first authenticate who ever is talking on this connection, and then pass along the remaining commands. To create a {@link Dispatcher} one would call the following method:

{@link LWSDispatcherFactory.createInstance(SenderOfMessagesToServer, ReceivesCommandsFromDispatcher)}

In this instance, the {@link SenderOfMessagesToServer} would have to be able to encode a url and send it to a remote server; the {@link ReceivesCommandsFromDispatcher} would do some action when a command was receives on the HTTP connection.

{@link Dispatcher} is an instance of {@link org.limewire.http.AsyncHttpRequestHandler} so can listen on the local HTTP acceptor. So a typical use of this package would be the following

SenderOfMessagesToServer s = new SenderOfMessagesToServer() {
	public String sendMessageToServer(String msg, Map args) throws IOException {
		// send the message, msg, and arguments args to a remote server
		// ...
		// return the result
	}
	ReceivesCommandsFromDispatcher r = new ReceivesCommandsFromDispatcher() {
	
	  private final List connectionListeners = new ArrayList();
    private boolean isConnected;
	

 			public String receiveCommand(String cmd, Map args) {
 				// take some action
 			}
 					
    public final void setConnected(boolean isConnected) {
        this.isConnected = isConnected;
        connectionChanged(this.isConnected);
        if (!connectionListeners.isEmpty()) {
            for (ConnectionListener lis : connectionListeners) {
                lis.connectionChanged(isConnected);
            }
        }
    }

    public final boolean addConnectionListener(ConnectionListener lis) {
        return connectionListeners.contains(lis) ? false : connectionListeners.add(lis);
    }

    public final boolean removeConnectionListener(ConnectionListener lis) {
        return !connectionListeners.contains(lis) ? false : connectionListeners.remove(lis);
    }
};
Dispatcher d = LWSDispatcherFactory.createInstance(s,r);

// now attach d to the local HTTP connection using the 'registerHandler' command
		

The class {@link AbstractReceivesCommandsFromDispatcher} abstracts away the management of the {@link ConnectionListener}s. Next is the authentication scheme used in this package.

Authentication

In order to do this securely (i.e. make sure the javascript sending messages is actually from limewire.com and not the ever-evil pelzer.com), we need a scheme to authenticate the the javascript, and in English it is:

More formally (but just barely) this scheme consists of the following participants:

and there are three pieces of data:

and the scheme is:

Lifecycle of the local server

The life cycle of the local server can be represented using an FSA such as the following:

FSA of local server