Chapter 52. AJAX Client

For example, if the Jakarta RESTful Web Services resource X defines methods Y and Z:

@Path("/")
public interface X{
 @GET
 public String Y();
 @PUT
 public void Z(String entity);
}

Then the JavaScript API will define the following functions:

var X = {
 Y : function(params){…},
 Z : function(params){…}
};

Here is an example of Jakarta RESTful Web Services API:

@Path("foo")
public class Foo{
 @Path("{id}")
 @GET
 public String get(@QueryParam("order") String order, @HeaderParam("X-Foo") String header,
                   @MatrixParam("colour") String colour, @CookieParam("Foo-Cookie") String cookie){
  …
 }
 @POST
 public void post(String text){
 }
}

We can use the previous Jakarta RESTful Web Services API in JavaScript using the following code:

var text = Foo.get({order: 'desc', 'X-Foo': 'hello',
                    colour: 'blue', 'Foo-Cookie': 123987235444});
Foo.put({$entity: text});

The RESTEasy JavaScript client API can automatically unmarshall JSON and XML:

@Path("orders")
public interface Orders {

 @XmlRootElement
 public static class Order {
  @XmlElement
  private String id;
  
  public Order(){}
  
  public Order(String id){
   this.id = id;
  }
 }

 @Path("{id}/xml")
 @GET
 @Produces("application/xml")
 public Order getOrderXML(@PathParam("id") String id){
  return new Order(id);
 }

 @Path("{id}/json")
 @GET
 @Produces("application/json")
 public Order getOrderJSON(@PathParam("id") String id){
  return new Order(id);
 }
}

Let us look at what the preceding Jakarta RESTful Web Services API would give us on the client side:

// this returns a JSON object
var orderJSON = Orders.getOrderJSON({id: "23"});
orderJSON.id == "23";

// this one returns a DOM Document whose root element is the order, with one child (id)
// whose child is the text node value
var orderXML = Orders.getOrderXML({id: "23"});
orderXML.documentElement.childNodes[0].childNodes[0].nodeValue == "23";

The RESTEasy JavaScript client API can automatically marshall JSON and XML:

@Path("orders")
public interface Orders {

 @XmlRootElement
 public static class Order {
  @XmlElement
  private String id;
  
  public Order(){}
  
  public Order(String id){
   this.id = id;
  }
 }

 @Path("{id}/xml")
 @PUT
 @Consumes("application/xml")
 public void putOrderXML(Order order){
  // store order
 }

 @Path("{id}/json")
 @PUT
 @Consumes("application/json")
 public void putOrderJSON(Order order){
  // store order
 }
}

Let us look at what the preceding Jakarta RESTful Web Services API would give us on the client side:

// this saves a JSON object
Orders.putOrderJSON({$entity: {id: "23"}});

// It is a bit more work with XML
var order = document.createElement("order");
var id = document.createElement("id");
order.appendChild(id);
id.appendChild(document.createTextNode("23"));
Orders.putOrderXML({$entity: order});

The REST object can be used to override RESTEasy JavaScript API client behaviour:

// Change the base URL used by the API:
REST.apiURL = "http://api.service.com";

// log everything in a div element
REST.log = function(text){
 jQuery("#log-div").append(text);
};

The REST.Request class can be used to build custom requests:

var r = new REST.Request();
r.setURI("http://api.service.com/orders/23/json");
r.setMethod("PUT");
r.setContentType("application/json");
r.setEntity({id: "23"});
r.addMatrixParameter("JSESSIONID", "12309812378123");
r.execute(function(status, request, entity){
 log("Response is "+status);
});