<?xml version="1.0" encoding="UTF-8"?>
<!-- 
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
 -->
 <chapter id="AJAX_Client">
    <title>AJAX Client</title>
    <para>RESTEasy resources can be accessed in JavaScript using AJAX using a 
      proxy API generated by RESTEasy.</para>
    <section>
    	<title>Generated JavaScript API</title>
    	<para>
    		RESTEasy can generate a JavaScript API that uses AJAX calls to invoke JAX-RS operations.
    	</para>
   		<example>
   			<title>First JAX-RS JavaScript API example</title>
    		<para>
    			Let's take a simple JAX-RS API:
	    	</para>
	    	<programlisting><![CDATA[@Path("orders")
public interface Orders {
 @Path("{id}")
 @GET
 public String getOrder(@PathParam("id") String id){
  return "Hello "+id;
 }
}]]></programlisting>
	    	<para>
				The preceding API would be accessible using the following JavaScript code:
	    	</para>
	    	<programlisting language="javascript"><![CDATA[var order = Orders.getOrder({id: 23});]]></programlisting>
   		</example>
    	<section>
    		<title>JavaScript API servlet</title>
    		<para>
    			In order to enable the JavaScript API servlet you must configure it in your
    			web.xml file as such:
    		</para>
    		<programlisting language="xml"><![CDATA[<servlet>
 <servlet-name>RESTEasy JSAPI</servlet-name>
 <servlet-class>org.jboss.resteasy.jsapi.JSAPIServlet</servlet-class>
</servlet>

<servlet-mapping>
 <servlet-name>RESTEasy JSAPI</servlet-name>
 <url-pattern>/rest-js</url-pattern>
</servlet-mapping>]]></programlisting>
    	</section>
    	<section>
    		<title>JavaScript API usage</title>
    		<para>
    			Each JAX-RS resource class will generate a JavaScript object of the same name
    			as the declaring class (or interface), which will contain every JAX-RS method
    			as properties.
    		</para>
    		<example>
    			<title>Structure of JAX-RS generated JavaScript</title>
    			<para>For example, if the JAX-RS resource X defines methods Y and Z:
    			</para>
	    		<programlisting language="java"><![CDATA[@Path("/")
public interface X{
 @GET
 public String Y();
 @PUT
 public void Z(String entity);
}]]></programlisting>
    			<para>
	    			Then the JavaScript API will define the following functions:
    			</para>
	    		<programlisting language="javascript"><![CDATA[var X = {
 Y : function(params){…},
 Z : function(params){…}
};]]></programlisting>
    		</example>
    		<para>
				Each JavaScript API method takes an optional object as single
				parameter where each property is a cookie, header, path, query or form parameter as identified
				by their name, or the following special parameters:
    		</para>
    		<warning><para>The following special parameter names are subject to change.</para></warning>
    		<table>
				<caption>API parameter properties</caption>
				<thead>
					<tr>
						<th>Property name</th>
						<th>Default</th>
						<th>Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td>$entity</td>
						<td></td>
						<td>The entity to send as a PUT, POST request.</td>
					</tr>
					<tr>
						<td>$contentType</td>
						<td>As determined by @Consumes.</td>
						<td>The MIME type of the body entity sent as the Content-Type header.</td>
					</tr>
					<tr>
						<td>$accepts</td>
						<td>Determined by @Provides, defaults to */*.</td>
						<td>The accepted MIME types sent as the Accept header.</td>
					</tr>
					<tr>
						<td>$callback</td>
						<td></td>
						<td>
							Set to a function(httpCode, xmlHttpRequest, value) for an asynchronous call. If 
							not present, the call will be synchronous and return the value.
						</td>
					</tr>
					<tr>
						<td>$apiURL</td>
						<td>Determined by container</td>
						<td>Set to the base URI of your JAX-RS endpoint, not including the last slash.</td>
					</tr>
					<tr>
						<td>$username</td>
						<td></td>
						<td>If username and password are set, they will be used for credentials for the request.</td>
					</tr>
					<tr>
						<td>$password</td>
						<td></td>
						<td>If username and password are set, they will be used for credentials for the request.</td>
					</tr>
				</tbody>
    		</table>
    		<example>
    			<title>Using the API</title>
    			<para>Here is an example of JAX-RS API:</para>
	    		<programlisting language="java"><![CDATA[@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){
 }
}]]></programlisting>
				<para>We can use the previous JAX-RS API in JavaScript using the following code:</para>
	    		<programlisting language="javascript"><![CDATA[
var text = Foo.get({order: 'desc', 'X-Foo': 'hello',
                    colour: 'blue', 'Foo-Cookie': 123987235444});
Foo.put({$entity: text});]]></programlisting>
    		</example>
    	</section>
    	<section>
    		<title>Work with @Form</title>
    		<para>
    			@Form is a RESTEasy specific annotation that allows you to re-use any @*Param annotation within an injected class. 
    			The generated JavaScript API will expand the parameters for use automatically. Support we have the following form:
    		</para>
    		<programlisting language="java"><![CDATA[public class MyForm {
    @FormParam("stuff")
    private String stuff;

    @FormParam("number")
    private int number;

    @HeaderParam("myHeader")
    private String header;
}]]></programlisting>
			<para>And the resource is like:</para>
			<programlisting language="java"><![CDATA[@Path("/")
public class MyResource {

    @POST
    public String postForm(@Form MyForm myForm) {...}

}]]></programlisting>
			<para>Then we could call the method from JavaScript API like following:</para>
			<programlisting language="java"><![CDATA[MyResource.postForm({stuff:"A", myHeader:"B", number:1});]]></programlisting>
			<para>Also, @Form supports prefix mappings for lists and maps:</para>
			<programlisting language="java"><![CDATA[public static class Person {
    @Form(prefix="telephoneNumbers") List<TelephoneNumber> telephoneNumbers;
    @Form(prefix="address") Map<String, Address> addresses;
}

public static class TelephoneNumber {
    @FormParam("countryCode") private String countryCode;
    @FormParam("number") private String number;
}

public static class Address {
    @FormParam("street") private String street;
    @FormParam("houseNumber") private String houseNumber;
}

@Path("person")
public static class MyResource {
	@POST
	public void postForm(@Form Person p) {...} 
}]]></programlisting>
		<para>From JavaScript we could call the API like this:</para>
		<programlisting><![CDATA[MyResource.postForm({
	telephoneNumbers:[
		{"telephoneNumbers[0].countryCode":31},
		{"telephoneNumbers[0].number":12345678},
		{"telephoneNumbers[1].countryCode":91},
		{"telephoneNumbers[1].number":9717738723}
	],
	address:[
		{"address[INVOICE].street":"Main Street"},
		{"address[INVOICE].houseNumber":2},
		{"address[SHIPPING].street":"Square One"},
		{"address[SHIPPING].houseNumber":13}
	]
});]]></programlisting>
    	</section>
    	<section>
    		<title>MIME types and unmarshalling.</title>
    		<para>
    			The Accept header sent by any client JavaScript function is controlled by the $accepts parameter, which overrides
    			the @Produces annotation on the JAX-RS endpoint. The returned value however is controlled by the Content-Type header
    			sent in the response as follows:
    		</para>
    		<table>
				<caption>Return values by MIME type</caption>
				<thead>
					<tr>
						<th>MIME</th>
						<th>Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td>text/xml,application/xml,application/*+xml</td>
						<td>
							The response entity is parsed as XML before being returned. The return value is thus a DOM Document.
						</td>
					</tr>
					<tr>
						<td>application/json</td>
						<td>
							The response entity is parsed as JSON before being returned. The return value is thus a JavaScript Object.
						</td>
					</tr>
					<tr>
						<td>Anything else</td>
						<td>The response entity is returned raw.</td>
					</tr>
				</tbody>
			</table>
	   		<example>
   				<title>Unmarshalling example</title>
    			<para>
	    			The RESTEasy JavaScript client API can automatically unmarshall JSON and XML:
	    		</para>
	    		<programlisting><![CDATA[@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);
 }
}]]></programlisting>
	    		<para>
					Let us look at what the preceding JAX-RS API would give us on the client side:
	    		</para>
	    		<programlisting language="javascript"><![CDATA[// 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";]]></programlisting>
   			</example>
    	</section>
    	<section>
    		<title>MIME types and marshalling.</title>
    		<para>
    			The Content-Type header sent in the request is controlled by the $contentType parameter which overrides the
    			@Consumes annotation on the JAX-RS endpoint. The value passed as entity body using the $entity parameter is marshalled
    			according to both its type and content type:
    		</para>
    		<table>
				<caption>Controlling sent entities</caption>
				<thead>
					<tr>
						<th>Type</th>
						<th>MIME</th>
						<th>Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td>DOM Element</td>
						<td>Empty or text/xml,application/xml,application/*+xml</td>
						<td>The DOM Element is marshalled to XML before being sent.</td>
					</tr>
					<tr>
						<td>JavaScript Object (JSON)</td>
						<td>Empty or application/json</td>
						<td>The JSON object is marshalled to a JSON string before being sent.</td>
					</tr>
					<tr>
						<td>Anything else</td>
						<td>Anything else</td>
						<td>
							The entity is sent as is.
						</td>
					</tr>
				</tbody>
			</table>
	   		<example>
   				<title>Marshalling example</title>
    			<para>
	    			The RESTEasy JavaScript client API can automatically marshall JSON and XML:
	    		</para>
	    		<programlisting><![CDATA[@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
 }
}]]></programlisting>
	    		<para>
					Let us look at what the preceding JAX-RS API would give us on the client side:
	    		</para>
	    		<programlisting language="javascript"><![CDATA[// 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});]]></programlisting>
   			</example>
    	</section>
   	</section>
   	<section>
   		<title>Using the JavaScript API to build AJAX queries</title>
   		<para>
   			The RESTEasy JavaScript API can also be used to manually construct your requests.
   		</para>
   		<section>
   			<title>The REST object</title>
   			<para>
   				The REST object contains the following read-write properties:
   			</para>
    		<table>
				<caption>The REST object</caption>
				<thead>
					<tr>
						<th>Property</th>
						<th>Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td>apiURL</td>
						<td>
							Set by default to the JAX-RS root URL, used by every JavaScript client API functions when constructing
							the requests.
						</td>
					</tr>
					<tr>
						<td>log</td>
						<td>
							Set to a function(string) in order to receive RESTEasy client API logs. This is useful if you want to
							debug your client API and place the logs where you can see them.
						</td>
					</tr>
				</tbody>
			</table>
	   		<example>
   				<title>Using the REST object</title>
    			<para>
	    			The REST object can be used to override RESTEasy JavaScript API client behaviour:
	    		</para>
	    		<programlisting language="javascript"><![CDATA[// 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);
};]]></programlisting>
   			</example>
   		</section>
   		<section>
   			<title>The REST.Request class</title>
   			<para>
   				The REST.Request class is used to build custom requests. It has the following members: 
   			</para>
    		<table>
				<caption>The REST.Request class</caption>
				<thead>
					<tr>
						<th>Member</th>
						<th>Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td>execute(callback)</td>
						<td>
							Executes the request with all the information set in the current object. The value is never returned
							but passed to the optional argument callback.
						</td>
					</tr>
					<tr>
						<td>setAccepts(acceptHeader)</td>
						<td>
							Sets the Accept request header. Defaults to */*.
						</td>
					</tr>
					<tr>
						<td>setCredentials(username, password)</td>
						<td>
							Sets the request credentials.
						</td>
					</tr>
					<tr>
						<td>setEntity(entity)</td>
						<td>
							Sets the request entity.
						</td>
					</tr>
					<tr>
						<td>setContentType(contentTypeHeader)</td>
						<td>
							Sets the Content-Type request header.
						</td>
					</tr>
					<tr>
						<td>setURI(uri)</td>
						<td>
							Sets the request URI. This should be an absolute URI.
						</td>
					</tr>
					<tr>
						<td>setMethod(method)</td>
						<td>
							Sets the request method. Defaults to GET.
						</td>
					</tr>
					<tr>
						<td>setAsync(async)</td>
						<td>
							Controls whether the request should be asynchronous. Defaults to true.
						</td>
					</tr>
					<tr>
						<td>addCookie(name, value)</td>
						<td>
							Sets the given cookie in the current document when executing the request.
							Beware that this will be persistent in your browser.
						</td>
					</tr>
					<tr>
						<td>addQueryParameter(name, value)</td>
						<td>
							Adds a query parameter to the URI query part.
						</td>
					</tr>
					<tr>
						<td>addMatrixParameter(name, value)</td>
						<td>
							Adds a matrix parameter (path parameter) to the last path segment of the request URI.
						</td>
					</tr>
					<tr>
						<td>addHeader(name, value)</td>
						<td>
							Adds a request header.
						</td>
					</tr>
				</tbody>
			</table>
	   		<example>
   				<title>Using the REST.Request class</title>
    			<para>
	    			The REST.Request class can be used to build custom requests:
	    		</para>
	    		<programlisting language="javascript"><![CDATA[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);
});]]></programlisting>
   			</example>
   		</section>
   	</section>
   	<section>
   		<title>Caching Features</title>
   		<para>
   			RESTEasy AJAX Client works well with server side caching features. But the buggy browsers cache will 
   			always prevent the function to work properly. If you'd like to use RESTEasy's caching feature with its
   			AJAX client, you can enable 'antiBrowserCache' option:
   		</para>
	    <programlisting language="javascript"><![CDATA[REST.antiBrowserCache = true;]]></programlisting>
		<para>
			The above setting should be set once before you call any APIs.
		</para>
   	</section>
</chapter>