Creating an AJAX-Enabled Application, a Toolkit Approach

Print-friendly Version

Articles Index

This is the second in a series of articles that describe ways to introduce Ajax functionality into an existing web application developed with the NetBeans IDE. Readers are encouraged to read the first article in the series, Creating an Ajax-Enabled Application, a Do-It-Yourself Approach, before reading this one. At a minimum, install the example project, the NetBeans 5.5 IDE, and the GlassFish server, as described in Downloading and Installing the Tools.

Your first approach to introducing Ajax functionality into the Duke's Bookstore application was do-it-yourself: you hand-coded JavaScript and CSS files on the client side and wrote a servlet to service the Ajax XMLHttpRequest on the server.

The do-it-yourself approach works well enough for simple projects, but as your project grows you want to find an approach that requires less client-side coding. For your second attempt to implement pop-up balloons in your application, you use one of the available JavaScript libraries to minimize the amount of JavaScript code you need to write.

In this article, you use the JavaScript libraries available with the Dojo Toolkit. The Dojo Toolkit provides a comprehensive set of JavaScript libraries and is receiving industry support from companies such as Sun Microsystems, AOL, and IBM. The Dojo Tookit is the logical choice for your project. Note that adopting Dojo libraries doesn't preclude other solutions. If at some point the Dojo libraries don't provide required functionality, they can be combined with libraries from other sources.

One advantage of using Dojo libraries is that they are designed to work with various browsers when desired functionality is missing. As a minimum, JavaScript must be enabled on the client browser in order for Ajax techniques to work. However, if JavaScript has been disabled entirely on the browser, the Dojo libraries do not prevent the page from loading. In the case of your bookstore application, there is no real penalty to the user if a missing browser technology prevents the pop-up balloons from appearing, so the degraded case is easy to handle. For more feature-packed Ajax pages, degradable code is more important.

To download and install the Dojo Toolkit library:

1. Download the compressed Dojo Toolkit file from the Dojo web site.
   
   
2. Expand the downloaded file and read the accompanying documentation, especially the README file.
   
   

You are now ready to see how to use the Dojo library in a web application.

To use the Dojo libraries with a web application, two sections of code are required:

1. Include the Dojo bootstrap file:

   <script type="text/javascript" src="pathname/dojo.js"/>

   
   
   where pathname is the location where the dojo.js file is stored. The dojo.js file includes a section that bootstraps the Dojo Toolkit. Depending on the release build of Dojo you are using, the file also includes code for some of the Dojo library modules.
   
   
2. Specify the packages you are using, such as dojo.io:

   <script type="text/javascript"> dojo.require("dojo.io.*"); </script>

   
   
   Note the similarity to the Java import statement.

The next section describes how to use these statements in your project.

To incorporate the Dojo libraries into the project you developed in Creating an Ajax-Enabled Application, a Do-It-Yourself Approach, you need to edit or replace the following two files:

• project/examples/web/bookstore2/web/popup.js
  
  
• project/examples/web/bookstore2/web/books/bookcatalog.jsp

where project is the root location of your project directory.

Pre-edited versions of the files have already been placed in the project for you, to be incorporated as described in the next section.

You also need to insert the dojo.js bootstrap file from the Dojo distribution into your project and include the supporting libraries.

The dojo.js file enables the entire Dojo library suite. The file includes some common functionality, such as dojo.io.bind. Depending on the Dojo edition, the file also provides a profile that makes certain Dojo features available. To make sure all Dojo features are available regardless of the Dojo edition, all editions provide access to the entire Dojo library in the dojo/src directory. Any features that aren't built into the dojo.js file can be dynamically loaded at runtime through the dojo.require() statement.

You can sometimes speed up your application's response time by customizing the dojo.js file to make it as small as possible (see the Dojo web site for more information). In your project you will use the default version of the file for the sake of simplicity.

The dojo.js file has already been placed in your NetBeans project, in the following location:

project/examples/web/bookstore2/web/dojo.js

where project is the root location of your project directory.

To use the Dojo library in your project, you need to edit the existing popup.jsp file or replace it with a different file. A pre-edited version of the file, called popup_dojo.js, has been provided to speed the process. You will include popup_dojo.js in the project build and exclude popup.jsp by changing a line in the bookcatalog.jsp file.

1. Start the NetBeans IDE if it is not already running.
   
   
2. From the NetBeans toolbar, choose File > Open. The Open Project window opens.
   
   
3. Navigate to project/examples/web/bookstore2. Select the bookstore2 project folder and click Open Project Folder. The IDE opens the project folder and selects bookstore2 as the main project. The bookstore project is also opened because bookstore2 depends on many of the files in bookstore.
   
   
4. If the IDE flags the bookstore project and alerts you that references need to be resolved:
   
   
   1. Right-click the project and choose Resolve Reference Problems from the pop-up menu.
      
      
   2. In the resulting window, click Resolve and navigate to the server/glassfish/lib directory, where server is the root of your GlassFish server installation.
      
      
   3. Select the javaee.jar file and open it. Click Close to resolve the reference and close the window.
      
      
5. If the bookstore2 project also produces an alert:
   
   
   1. Right-click on the project name and choose Resolve Missing Server Problem from the pop-up menu.
      
      
   2. In the resulting window, select the GlassFish server that you registered in Creating an Ajax-Enabled Application, a Do-It-Yourself Approach. Click OK to resolve the reference.

You need to edit the bookcatalog.jsp file to reference the dojo.js and popup_dojo.js files you are using. Instead of editing the bookcatalog.jsp file, replace it with the bookcatalog_popup_dojo.jsp file already in the project directory.

1. In the NetBeans IDE, click the Files tab to open the Files view of your project.
   
   
2. Expand the bookstore2 > web > books node and select the bookcatalog.jsp file.
   
   
3. Right-click and choose Rename from the pop-up menu. Rename the file to bookcatalog_popup.jsp to remove it from the build.
   
   

   Figure 1: Renaming the bookcatalog.jsp file

    
   
4. Similarly, rename the bookcatalog_popup_dojo.jsp file to bookcatalog.jsp, making the new file part of the project build.

You can now build and deploy the bookstore2 project.

In the NetBeans Projects window, the bookstore2 project should be shown in bold type to indicate that it is the main project. If it is not, set it as the main project by choosing Files > Set Main Project > bookstore2.

• Build and deploy the bookstore2 project by choosing Run > Run Main Project.
  
  

The status of the build is shown in the NetBeans Output window. When the build finishes successfully, your browser opens to show the Duke's Bookstore application. The application behaves just as it did when you implemented pop-up balloons in the do-it-yourself approach.

You now examine the files that make the pop-up balloons work with the Dojo library.

To examine the bookcatalog.jsp (formerly the bookcatalog_popup_dojo.jsp file):

1. In the NetBeans IDE, click the Files tab to show the Files view of the project.
   
   
2. Expand the bookstore > web > books node and double-click bookcatalog.jsp. The file opens in the NetBeans Editor, as shown in the following figure.

   Figure 2: The bookcatalog.jsp file in the NetBeans IDE Click here for a larger image.

The code of interest in bookcatalog.jsp lies between lines 28 and 58, bounded by the following comments:

<!-- BEGIN: popup -->

and

<!-- END: popup -->

Lines 29–30, shown below, import two scripts: dojo.js, the base Dojo script, and popup_dojo.js, a modification of the original popup.js script.

<script type="text/javascript" src="../dojo.js></script>
<script type="text/javascript" src="../popup_dojo.js"></script>

The remainder of the file is identical to the bookcatalog_popup.jsp file that you introduced in the do-it-yourself implementation described in Creating anAjax-Enabled Application, a Do-It-Yourself Approach.

The dojo.js file you are using in your project requires no coding on your part. However, you do need to code the popup_dojo.js file, just as you do for the do-it-yourself approach.

The first line in the file makes sure that the dojo.io library package is available:

dojo.require("dojo.io.*");

This package is, in fact, the only one used in the project.

One advantage in the Dojo version of the pop-up JSP file is that the Dojo libraries provide the necessary initilization request for the Ajax XMLHttpRequest object. In the popup_dojo.js file, this request is provided by the showPopupInternal() function (lines 35–50). The request results from the object literal format (lines 38–45) where the objects are set up. Line 48 dispatches the request.

As discussed in the Creating an Ajax-Enabled Application, a Do-It-Yourself Approach, this function can be easily changed to direct the request to either a servlet or a JSP page on the server side by changing the value of the url argument.

The following table compares the bpui.alone.showPopupInternal() function in each file, stripped of most comments for brevity. In terms of the amount of code you have to write for this function, there is very little difference between the Dojo and the do-it-yourself approaches.

bpui.alone.showPopupInternal=
function(popupx,  bookId) {
  // retrieve data through dojo call
  var bindArgs =  {
    url: "../PopupServlet?bookId=" 
      + escape (bookId),
    mimetype: "text/xml",
    handle:  bpui.alone.ajaxReturnFunction};
  bpui.alone.req=dojo.io.bind (bindArgs); 
}

bpui.alone.showPopupInternal=
function(popupx,  bookId) {
  // set up request 
   bpui.alone.req=bpui.alone.initRequest();
  url="../PopupServlet? bookId=" 
      + escape(bookId);
   bpui.alone.req.onreadystatechange = 
       bpui.alone.ajaxReturnFunction;
  bpui.alone.req.open("GET", url,  true);
  bpui.alone.req.send(null);
}

The code illustrates one advantage of the Dojo libraries: they handle most browser differences for you, in this case eliminating the need for an initRequest() call.

The Ajax callback function, bpui.alone.ajaxReturnFunction(), also differs between the two files. View the function in lines 52–70 of the popup_dojo.js file.

In line 53, the function signature defines the type, data, and event arguments:

bpui.alone.ajaxReturnFunction=function(type, data, evt)

whereas, in the popup.js file, the function signature does not define these arguments:

bpui.alone.ajaxReturnFunction=function()

The function in the popup_dojo.js file checks status of the returned XMLHttpRequest object using the evt (event) argument (lines 57–58):

if (evt.readyState == 4) {
    if (evt.status == 200) {
       ...

In contrast, in the popup.js file, the same function checks the status of the XMLHttpRequest object directly with the following lines:

if (bpui.alone.req.readyState == 4) {
    if (bpui.alone.req.status == 200) {
       ...

Overall, the popup_dojo.js and popup.js files represent about the same level of coding effort.

For the very simple Ajax functionality you are implementing in this example project, the benefits of a robust library aren't readily apparent, especially if the amount of hand coding required is the primary consideration.

As you expand your application's functionality, however, you can take advantage of additional library modules. In that case, there can be a clear advantage to using JavaScript libraries such as those provided by the Dojo Toolkit. For example, if you want to send form data through an Ajax call, the amount of hand coding can be very large in the do-it-yourself approach. In contrast, to introduce a form with Dojo, you need only create a form node in your bind argument. One line of code can provide the necessary functionality.

Even in the simplest of applications, a JavaScript library such as one provided by the Dojo Toolkit can provide some advantages. Notably,

• It handles events for you.
  
  
• It adjusts well to browser differences.
  
  
• It provides support for history and bookmark browser features that can be troublesome in Ajax.
  
  
• It handles cases in which JavaScript capability in the client browser is disabled or nonexistent.
  
  
• It provides a wide range of useful widgets such as date picker, rich text editor, time picker, and many more.

In your next implementation, you create a custom JSF component to generate the Javascript that executes the Ajax interactions on the client side. The JSF component is packaged with the application bundle and accessed directly. A Java Servlet on the server side responds to the Ajax request.

• Hands-On JavaEE — home page for this article series
  
• Ajax Design Strategies — article by Ed Ort and Mark Basler
  
• Dojo Toolkit — home page
  
• Ajax Developer Resource Center — the latest Java tools and technologies for Ajax developers
  
• JavaScript Recommendations for Ajax Component Writers — recommendations from Greg Murray
  
• Ajax in Action: Appendix B – JavaScript for Object-Oriented Programmers — hints for Java programmers new to JavaScript
  
• Java BluePrints Project — guidelines for designing enterprise applications and web services using Java technologies
  
• Programming Model for Ajax — an early access set of solutions for using Ajax on the Java EE platform
  
• NetBeans IDE — the tool for creating cross-platform Java web applications
  
• Java EE 5 Tutorial — lessons in developing Java EE applications on the Sun Java System Application Server Platform Edition 9 and GlassFish Community server
  
• Java EE 5 SDK — download page for Java EE SDK and NetBeans IDE
  
• Sun Developer Network (SDN) — the source for Sun developer solutions
  
• New Technologies for Ajax and Web Application Development: Project jMaki, Project Dynamic Faces, and Project Phobos — article by Jennifer Ball
  
• GlassFish Community — the GlassFish community, building a free, open source, Java EE 5 compatible application server
  
• Sun Java System Application Server Platform Edition 9 — the industry's first free, robust, commercial-grade Java EE 5 compatible application server
  

• Developing JavaServer Faces Components With Ajax (DTJ-3108) — training course
  
• Developing JavaServer Faces Web Applications With Ajax Using Sun Java Studio Creator (DTJ-2105) — training course
  
• Introduction to Developing Rich-Client Applications (WJO-1107) — training course
  
• Sun Java System Application Server Platform Edition 9: Overview (WMT-IAS-1499) — training course
  
• Java EE Learning Path — focused on Java Platform, Enterprise Edition (Java EE) training
  
• Developer Training and Certification — professional development to enhance your skills
  
• Developer Support — online incident-based programming advice, telephone product support, developer training courses, service plans