Package org.web_send

Inter-model messaging.

See:
Description

Class Summary

Entity

A MIME entity.

Exception Summary

Failure

Indicates a failed HTTP request.

Package org.web_send Description

Inter-model messaging.

When using the Waterken Server, each reference created by an application can be exported to HTTP clients as a URL. These clients, including other Waterken Server instances, can then interact with the referenced object by sending HTTP requests using the exported URL. The API in this package provides additional access to the HTTP messaging layer.

Accessing HTTP error status codes

Using an eventual reference, code written to the ref_send API can send HTTP requests. For example, the following code:

 final Drum drum_ = …
 final Promise<Integer> hits = drum_.getHits();
 

results in an HTTP request like:

 GET /-/bang/?p=hits&s=mvrgdn3rvq7qmy HTTP/1.1
 Host: vsci.hpl.hp.com
 
 

If the request is processed successfully, the hits promise will eventually resolve to an Integer indicating the number of times the drum has been banged. On the other hand, should there be an application level problem with the request, such as attempting to access a drum which no longer exists, the hits promise will eventually transition to the rejected state with a reason Exception providing details about the problem. For example:

 final int expected = …   // the expected number of hits
 class Was extends Do<Integer,Boolean> implements Serializable {
     static public final int serialVersionUID = 1L;
 
     public Boolean
     fulfill(final Integer reported) {
         …    // compare reported value to expected value
     }
 
     public Boolean
     reject(final Exception reason) {
         if (reason instanceof Failure) {
             // HTTP request failed
             final Failure e = (Failure)reason;
             if ("410".equals(e.status)) {
                 // the target drum no longer exists!
                 …
             }
             …
         }
         …
     }
 }
 … = _.when(hits, new Was());
 

Using a custom Content-Type

By default, all invocation arguments and return values are represented as JSON in HTTP requests and responses. Sometimes, an application may need to use another Content-Type to interact with a specific client, or to transfer raw bytes. This can be accomplished using an Entity. For example, the following code:

 public Entity
 getGreeting() {
     return new Entity(
         "text/plain; charset=US-ASCII",
         ByteArray.array(ASCII.encode("Hello World!\n"))
     );
 }
 

returns the following HTTP response to a GET request:

 HTTP/1.1 200 OK
 Content-Type: text/plain; charset=US-ASCII
 Content-Length: 13
 
 Hello World!