Ajax Patterns And Best Practices (2006)

Implementing an Asynchronous Parent Interface Instance

The big challenge with implementing an asynchronous Parent interface instance is managing the results. With the asynchronous Parent instance, multiple threads will be representing multiple local clients, and each local client will be generating results that need to be handed off to the controller. Synchronization is required when multiple Command instances hand off their results to the Parent instance that is running on a different thread to the local clients. Following is the implementation of the asynchronous class, which inherits from the previously defined

ParentBase class:

public class AsynchronousParent extends ParentBase { private LinkedList _results = new LinkedList();

public void addResult(Result result) { synchronized( _results) {

_results.addLast( result); _results.notify();

}

}

public Object getResult() { synchronized( _results) {

if( _results.size() > 0) {

return _results.removeFirst();

}

else { try {

_results.wait(15000);

}

catch (InterruptedException e) { return null;

}

if( _results.size() > 0) {

return _results.removeFirst();

}

else {

return null;

}

}

}

}

public AsynchronousParent() { }

}

The data member _results represents the list used to manage the results handed to the controller from the executing local clients. The method addResult is used to add a result to the list, and getResult is used to retrieve a result. Both the adding and removing from the list is embedded in a synchronized keyword, where the synchronization object is the list itself. Using the synchronized function in this way ensures that only one thread is adding or removing a result from the list.

An additional item to note is that the wait function with the value 15000 is used. Using the wait function is like using a Monitor in .NET. The wait function will wait to get pulsed, with the maximum wait being 15 seconds. A pulse is sent in the function addResult by using the notify method. The idea is that if there are no results to retrieve, the thread should wait a maximum of 15 seconds to retrieve a result. The strategy of waiting is part of the Persistent Communications pattern, in which the server will wait for a result to become available.

Implementing a Synchronous Parent

Implementing a synchronous Parent interface instance subclasses ParentBase and uses synchronization techniques, but in a different manner from the asynchronous Parent interface instance. The Parent interface instance instantiates the local clients and waits for all the Command interface instances to finish execution. During the execution, the Parent interface instance waits and does not accept further requests. In the synchronous implementation, the place where synchronization is needed is when the individual Command interface instances hand off results to the waiting Command interface instance. When the Command interface instance processes the results, all the Command interface instances have finished executing, and thus there is no concurrency. Following is the synchronous implementation:

public class SynchronousParent extends ParentBase { private List _results = new LinkedList();

public synchronized void addResult(Result result) { _results.add( result);

}

public Iterator getResultsIterator() { return _results.iterator();

}

public SynchronousParent() {

}

public void processRequest(Request request) { super.processRequest( request);

Iterator iter = _runningThreads.iterator(); while( iter.hasNext()) {

Thread thrd = (Thread)iter.next(); try {

thrd.join();

}

catch (InterruptedException e) {}

}

}

}

The SynchronousParent class has only one data member, _results, which is used to store the results generated by the Command interface instances. The method addResult is synchronized, allowing only a single thread to access the method and allowing only a single thread to add a result to the results list.

Look at the implementation of the method processRequest. The first call is to call the method super.processRequest, which translates to calling the ParentBase.processRequest method. The base class method implementation will start all the threads. Then, when the base class returns, SynchronousParent retrieves the Iterator instance to the currently executing threads. The method processRequest will use the iterator to iterate each thread ID and call the method thrd.join. Calling thrd.join will call the calling thread to wait until the thread referenced by the variable thrd has finished executing. The idea is to call the join method on each of the executing threads, and if all have been called, then no thread will be executing.

Relating this back to the addResult method, what happens is that a caller of SynchronousParent will expect to execute all the Command interface instances. Let’s call that the main thread. SynchronousParent then spawns a number of child threads. The main thread then waits until all child threads have executed. During the execution of the child threads, results will be added by using the method addResult. However, no results will be retrieved because the main thread is waiting for all the child threads to finish. After all the child threads have finished executing, the main thread returns control to the caller of SynchronousParent, who then proceeds to iterate the results. When the results are iterated, there will be only one thread accessing the data.

This finishes the basic architecture of the REST-Based Model View Controller pattern. The last remaining piece is to implement the Java servlet. The implementation of the Java servlet will be broken into two pieces; one is used to handle asynchronous requests, and the other to handle synchronous requests. The implementation is broken into two pieces because of the complexity associated with the implementation. Remember from the architecture that the REST-Based Model View Controller pattern needs to implement the Permutations pattern. Combining the Permutations pattern with the asynchronous and synchronous implementations would be too much complexity in one explanation.

Handling an Asynchronous Search

The asynchronous Java servlet search will be discussed first because it will not implement the Permutations pattern. The focus of the asynchronous Java servlet is to configure the REST-Based Model View Controller pattern implementation, illustrate how to make a call, and then process the results.

Posting a Query

Consider the following source code that defines the Java Servlet class AsynchronousServlet and configures the SearchBuilder class:

public class AsynchronousServlet extends HttpServlet { public void init(javax.servlet.ServletConfig config)

throws javax.servlet.ServletException { SearchBuilder.assignConfiguration(

config.getInitParameter( "amazon-endpoint"), config.getInitParameter( "amazon-access-key"), config.getInitParameter( "amazon-secret-key"), config.getInitParameter( "google-endpoint"), config.getInitParameter( "google-access-key"));

}

The configuration of the SearchBuilder class is relatively simple. The init method is overridden, and the configuration values are retrieved from the configuration file associated with the web application.

In the “Architecture” section of this chapter, the asynchronous interface implements the Persistent Communications pattern, and implements the HTTP GET and HTTP POST, which in Java Servletspeak means to implement the doPost and doGet methods. Following is the implementation of the doPost method:

protected void doPost(HttpServletRequest request, HttpServletResponse response)

throws javax.servlet.ServletException, java.io.IOException { HttpSession session = request.getSession( true); AsynchronousParent parent = null;

if( session.isNew()) {

parent = new AsynchronousParent(); session.setAttribute( "parent", parent);

}

else {

parent = (AsynchronousParent)session.getAttribute( "parent");

}

String value = request.getParameter( "query");

String queryIdentifier = request.getHeader( "X-query-identifier"); if( value != null && value.length() > 0) {

synchronized( parent) { SearchBuilder.buildCommands( parent);

parent.processRequest( new SearchRequest(queryIdentifier, value));

}

response.setContentType( "text/xml"); PrintWriter out = response.getWriter(); out.println( "<result>success</result>");

}

}

At the beginning of doPost, the session is retrieved by using the method getSession and is assigned to the variable session. The session is associated with an HTTP cookie. Using Java servlets, it is possible to query whether a new session has been created by using the method isNew. If isNew returns true, an instance of AsynchronousParent (which is the asynchronous controller) is instantiated and assigned to the session by using the method setAttribute. If isNew does not indicate a new session, the already-existing AsynchronousParent instance is returned by using the method getAttribute.

From that point on, there is a valid AsynchronousParent instance that is responsible for instantiating the Command interface instances and collecting the results. To execute a search, the value for the query string variable query is retrieved by using the method getParameter. The method getParameter can be called even though an HTTP POST is made. The query identifier that is stored as an HTTP header is retrieved by using the method getHeader and is assigned to queryIdentifier.

If the query value is not null and has some value, a synchronized block is entered. The synchronized block is important because no two requests should be executing queries at the same time. Think of it this way: a client creates an application in which a user could very quickly generate search requests. Those two very quickly executed requests could run concurrently but should not.

Do not make the mistaken assumption that the synchronized block cannot run multiple queries at the same time. It can have multiple queries going at the same time. What is not possible is to start multiple queries at the same time. The problem of starting multiple queries at the same time is that the AsynchronousParent is a session variable that could be associated with multiple web browsers. Remember from previous examples, an HTTP cookie is associated with a URL, and if multiple windows of a web browser reference the same URL, so will the same HTTP cookie.

Some readers may argue that my code is not efficient enough. True, but my objective was to illustrate that when executing requests asynchronously, there is one AsynchronousParent instance associated with one session, which is one cookie that collects all results and multiple queries running at the same time. When running in an asynchronous manner, there are concurrency issues to consider that must not be taken lightly.

Let’s get back to the synchronization block. After the method processRequest is called, the generated output is a simple success. Anything more than a successful result is not required as the Persistent Communications pattern expects results when using the HTTP GET.

Before I continue the discussion, a side step is necessary regarding the query identifier. In the Persistent Communications pattern, the query identifier was called a version number.

In the Persistent Communications pattern, the version number was used by the server to know when to return data to the client. The query identifier in the example is used to identify the version number of the query.

Retrieving a Result

To retrieve a result, an HTTP GET is executed, and that means the doGet method needs to be implemented. The implementation of doGet will test the AsynchronousParent instance for available results and is implemented as follows:

protected void doGet(HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException { HttpSession session = request.getSession( true); Object obj = session.getAttribute( "parent"); if( obj != null) {

AsynchronousParent parent = (AsynchronousParent)obj; SearchResult result = (SearchResult)parent.getResult(); if( result != null) {

response.setHeader( "X-transaction-identifier", result.getTransactionIdentifier());

PrintWriter out = response.getWriter(); out.println( "<results>");

out.println( "<result>");

out.println( "<URL>" + result.getURL() + "</URL>"); out.println( "<Title>" + result.getTitle() + "</Title>"); out.println( "<Snippet><![CDATA[" +

result.getSnippet() + "]]></Snippet>"); out.println( "</result></results>");

}

}

return;

}

In the implementation of doGet, the first step is to retrieve the session by using getSession, which is then used to retrieve the AsynchronousParent instance by using getAttribute. The return value of getAttribute is assigned to an Object type because if the value of obj is null and a typecast is attempted, an exception will arise. If the value of obj is not null, it is possible to perform a typecast to AsynchronousParent. The cast value is assigned to parent, which retrieves a value by using the method getResult. If there is a result, the retrieved value will be non-null, allowing the appropriate XML content to be generated.

Notice how the query identifier is assigned to an HTTP header, which the client will need to process. Based on the query identifier, the client would know whether the result is stale or to which query the result belongs. If the result is valid, it can be manipulated by the client and transformed to HTML or parsed to fill some HTML.

Handling a Synchronous Search

The other way of calling the REST-Based Model View Controller pattern implementation is to use the synchronous interface. A web browser, HTTP client, or even another REST-Based Model View Controller pattern implementation can call the synchronous interface. As the synchronous interface is a standard HTTP GET, the Permutations pattern is applicable.

Implementing the Servlet-Based Permutations Pattern

In the Permutations pattern, the example illustrated how to implement the pattern by using an HTTP filter or module. The Permutations pattern is implemented in the Java servlet or ASP.NET handler to reduce the number of redirections. However, when a Java servlet or ASP.NET handler implements the Permutations pattern, an object redirection (instead of a URL redirection or rewriting) occurs. The object redirection is illustrated in Figure 11-9.

In Figure 11-9, the Handler class receives an HTTP request. In the implementation of the method doGet, the Permutations pattern is implemented. The URL along with the HTTP headers would be read in the doGet method. Like the original Permutations pattern, the acceptable types would be iterated for which a new URL could be rewritten or redirected to. In this implementation of the Permutations pattern, the acceptable types would be iterated and matched to an object instance that could process the acceptable type. The object instances implement the Representation interface. For Handler, there are two appropriate Representations: XML and HTML. The cross-referencing of the acceptable type and object instance is based on the getType method that returns the MIME type that it can process. The idea of the outlined architecture is to mimic a redirection infrastructure of Java Servlet or ASP.NET handlers.

Figure 11-9. Object redirection architecture

Implementing the architecture requires a servlet that manages the various representation implementations and reacts appropriately to an HTTP request. Following is the implementation of the class PermutationsServlet, with some parts missing for clarity:

public abstract class PermutationsServlet extends HttpServlet { List _representations = new LinkedList();

public PermutationsServlet() {

}

protected Representation getRepresentationInternal( String mimetype, HttpServletRequest request) { Iterator repIter = _representations.iterator(); while( repIter.hasNext()) {

Representation representation = (Representation)repIter.next(); if( representation.canProcess( mimetype, request)) {

return representation;

}

}

return null;

}

366 C H A P T E R 1 1 ■ R E S T - B A S E D M O D E L V I E W C O N T R O L L E R P A T T E R N

protected Representation getRepresentation(HttpServletRequest request) { ArrayList elements = parseHeaders( request.getHeader( "Accept")); Iterator iter = elements.iterator();

while( iter.hasNext()) {

StringTokenizer tokenizer = new StringTokenizer( (String)iter.next(), ";");

Representation representation =

getRepresentationInternal( tokenizer.nextToken(), request); if( representation != null) {

return representation;

}

}

return getRepresentationInternal( "*/*", request);

}

protected void doGet(HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException {

Representation representation = getRepresentation( request); if( representation != null) {

representation.doGet( request, response);

}

return;

}

}

The data member _representations represents a list that contains all of the representations. PermutationsServlet implements the method doGet, which will be called whenever an HTTP GET request is received. In the doGet method implementation, getRepresentation is called, and that is the implementation of the Permutations pattern. The method getRepresentation is responsible for cross-referencing the acceptable types sent by the client, with a representation from the list of representations.

In the implementation of getRepresentation, the Accept HTTP header is parsed for the individual MIME types that are acceptable by using the method parseHeaders. For better clarity, the method parseHeaders is not illustrated. To see an actual implementation, please see the Permutations pattern chapter. After the MIME types have been ordered, each value is iterated and attempted to be matched with a representation by using the method getRepresentationInternal. In the implementation of getRepresentationInternal, the method representation.canProcess is called. The canProcess method requires two parameters: the

MIME type and HTTP request. It is important to realize that not only the MIME type determines whether a representation can process the request, but also the request parameters. If a match is made, getRepresentation will return immediately and stop iterating. If a match cannot be made, the catch-all MIME type (*/*) is queried for a representation. Getting back to the doGet implementation, if a representation is found, the method representation.doGet is called with the HTTP request and response types.

Processing a Request

The class PermutationsServlet is implemented as an abstract class that requires another class to subclass PermutationsServlet. The goal is to require a class to subclass PermutationsServlet and associate with PermutationsServlet the representations that can process requests. Following is the example implementation for the SynchronousServlet class:

public class SynchronousServlet extends PermutationsServlet { public void init(javax.servlet.ServletConfig config) throws javax.servlet.ServletException {

SearchBuilder.assignConfiguration( config.getInitParameter( "amazon-endpoint"), config.getInitParameter( "amazon-access-key"), config.getInitParameter( "amazon-secret-key"), config.getInitParameter( "google-endpoint"), config.getInitParameter( "google-access-key"));

addRepresentation( new XMLContent()); addRepresentation( new OtherContent());

}

}

The implementation of the SynchronousServlet class requires the implementation of only the method init. The method init would like AsynchronousServlet to retrieve the configuration information from a web application configuration file. The methods addRepresentation instantiate two types, XMLContent and OtherContent, that are used to generate content as either XML or the default HTML content.

What is interesting is that the implementations of the classes XMLContent and OtherContent are very similar to the AsynchronousServlet implementation. The major difference is that

SynchronousParent is used instead of AsynchronousParent.

Because the similarities are so great, an argument could made that the synchronous and asynchronous functionality should have been combined into a single implementation. The fact is that it probably could have been done, but was not done so that I could illustrate the thinking required to implement either a synchronous or asynchronous interface.

Pattern Highlights

In conclusion, the REST-Based Model View Controller pattern is an example pattern for which it is more important to understand the details of the architecture than the example implementation. As much as I would like to say that the example implementation should always be used, it is not possible. The reason why I say that every REST-Based Model View Controller is a custom implementation is due to the nature of remote servers defining the model. Maybe it is necessary to call only a single remote server. Or maybe you first call one remote server and then call another remote server. Those details will change how the local client is implemented, and potentially how the controller interacts with the local client.

The following points are the important highlights of the REST-Based Model View Controller pattern:

•Each and every implementation of the pattern should have a controller, local client, and model. The controller and local client are managed as a package, but are two separate pieces of software. The controller executes the local clients, manages the request information, manages the results, and is responsible for interacting with the client. The local clients manage the models exposed by the remote servers.

•A pattern implementation will expose either an asynchronous or synchronous interface, or potentially both. If a synchronous interface is exposed, it fulfills the Chunked Content pattern. If an asynchronous interface is exposed, it fulfills the Persistent Communications pattern.

•The view interacts with the controller, using well-defined URLs specific to the domain of the problem.

•The data that is exchanged between the client and the server is the least amount required to uniquely describe the information.