Download source - 396.8 KB

Table of Contents

Introduction
Background
Using the Code
- Default Usage - Client-Side Processing Mode
- Fully AJAXified Table - Server-Side Processing Mode
  - Servlet Implementation
Conclusion
History

Introduction

The most common task in web development is adding tables in pages. One standard page with a table that you have added a lot of times is shown in the following figure:

However, this table is too simple. It has no sorting, there is no pagination, some filter might be useful. How much work would you need to add these features? If you are using jQuery, and if you have seen the jQuery DataTables plug-in, then you know that you need just one line of JavaScript code:

$('table#myTable').dataTable();

In this example, the HTML table with ID myTable is found in the DOM of the web page in the browser and the DataTables plug-in is applied in order to add the widgets described in the previous text. The DataTables plug-in adds a "Show XXX entries" dropdown above the table, enabling the user to choose whether he wants to see 10, 25, 50, or 100 records per page and a search text box that enables the user to filter by keyword records that should be shown in the table. This plug-in also adds sorting functionality that enables the user to sort results by clicking on the column header. Below the table, there is a pagination that enables the user to navigate through the pages, and text that automatically displays which records are currently displayed.

Everything is implemented using JavaScript functionalities so you do not need to do anything else. The only thing you need to do is generate a plain table as in the initial case. The new, enhanced table is shown in the following figure:

A lot of nice functionalities gained by just one line of code. In this article, you will find more details about the usage of the plug-in.

Background

The goal of this article is to show how you can implement fully functional, high performance tables using the jQuery DataTables plug-in. This is a JavaScript plug-in implemented using the jQuery library that handles all the necessary interaction with the user on the client-side.

The jQuery DataTables plug-in is an excellent client-side component that can be used to create rich-functional tables in a web browser. This plug-in adds a lot of functionalities to plain HTML tables, such as filtering, paging, sorting, changing page length, etc. Although, by default, it is pure client side, it might be configured to use data from the server via AJAX calls in order to improve performance. However, to integrate DataTables with server-side code, the developer must know the protocols and parameters that are sent by DataTables and how to use them on the server side.

This article shows how the jQuery DataTables plug-in can be integrated into Java web applications. It contains step by step examples that show how the DataTables plug-in interacts with server-side components. There are a lot of server-side frameworks in Java such as standard servlets, JSP, JSF, Spring, Struts, etc., and this article will not cover them all. In this article, I will focus on plain servlets to demonstrate how you can create high performance AJAX-based data tables with standard Java servlets.

Using the Code

This sample shows how you can generate a table of companies and add the jQuery DataTables plug-in to the HTML table. The code is logically organized in the MVC structure:

Model represents classes that contain data and that will be shown in the browser.
Controller is the logic of the application and represents servlets that handle web requests and utility functions.
View are pages that are used to show data to the client - in this example, a JSP and a plain HTML page are used as views.

There is also one utility package containing classes transforming Java objects into JSON (this is required because the jQuery DataTables plug-in communicates with server-side code via JSON objects).

The Model is a Company class that contains the following properties:

Name of the company
Address of the company
Town of the company

In this example, a database or any other data source is not used, so I have used a class called DataRepository that contains a hardcoded list of companies. This class returns the companies that will be shown, using the following call:

DataRepository.GetCompanies();

In the following sections are presented two major cases of usage of DataTables in Java web applications.

Default Usage - Client Side Processing Mode

In default mode, a minimum amount of code is required - the web server can generate a plain HTML table in standard format. The client-side JavaScript component will use whatever gets generated and add client-side functionalities. In this client-side mode, DataTables takes all the table rows from the <tbody></tbody> section and performs filtering, paging, and sorting directly on these elements as with in-memory objects. This is the fastest way to use DataTables, but it requires that the server returns all data in a single call, loads all these rows as in-memory JavaScript objects, and renders them dynamically in DOM. This might cause performance issues with the server call, and memory usage on the client. However, this minimizes the number of requests sent to the server because once the table is loaded, the server is not used at all.

As mentioned above, the jQuery DataTables plug-in can be applied on a static HTML structure in the browser. In that case, you will need to generate HTML code for the table on the server-side. In this example, I have generated a table structure using a JSP page shown in the listing below:

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"
    import="jquery.datatables.model.*"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
    "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>Applying jQuery DataTables plugin in the Java Server application</title>
        <link href="media/dataTables/demo_page.css" rel="stylesheet" type="text/css" />
        <link href="media/dataTables/demo_table.css" rel="stylesheet" type="text/css" />
        <link href="media/dataTables/demo_table_jui.css" rel="stylesheet" type="text/css" />
        <link href="media/themes/base/jquery-ui.css" rel="stylesheet" 
           type="text/css" media="all" />
        <link href="media/themes/smoothness/jquery-ui-1.7.2.custom.css" 
           rel="stylesheet" type="text/css" media="all" />
        <script src="scripts/jquery-1.4.4.min.js"
           type="text/javascript"></script>
        <script src="scripts/jquery.dataTables.min.js" 
           type="text/javascript"></script>
        <script type="text/javascript">
        $(document).ready(function () {
            $("#companies").dataTable({
                "sPaginationType": "full_numbers",
                "bJQueryUI": true
            });
        });
        </script>
    </head>
    <body id="dt_example">
        <div id="container">
            <div id="demo_jui">
                <table id="companies" class="display">
                    <thead>
                        <tr>
                            <th>Company name</th>
                            <th>Address</th>
                            <th>Town</th>
                        </tr>
                    </thead>
                    <tbody>
                      <% for(Company c: DataRepository.GetCompanies()){ %>
                    <tr>
                             <td><%=c.getName()%></td>
                         <td><%=c.getAddress()%></td>
                         <td><%=c.getTown()%></td>
                    </tr>
                <% } %>
                    </tbody>
                </table>
         </div>
        </div> 
    </body>
</html>

In this JSP page is included all the necessary JavaScript libraries, and HTML code for the company table is generated. For demonstration purposes, a simple loop generates a TR for each company that is returned by the repository class. However, in your applications, you can use any server-side processing you want (JavaBeans, JSTL components, etc.) because the jQuery DataTables plug-in is independent of the applied server-side technology.

In the document-ready JavaScript event handler, the plain generated table is enhanced with the jQuery DataTables plug-in. There are two parameters that are passed to the plug-in initialization function (these are two parameters I always use):

sPagination - instructing the plug-in to generate pagination with numbers instead of two previous-next buttons, as is generated by default
bJQueryUI - applying standard jQueryUI styles

Instead of the plain HTML table, the following component is shown on the client side:

All actions you see in the component are implemented on the client-side (e.g., when you enter text in the text box, TR elements are filtered). This is the fastest way for the user, under the assumption that the time required to load the table is not too big. If you have a huge amount of data, you might consider using DataTables in AJAX mode where only partial results are returned to the plug-in.

These are just basic functionalities provided by the DataTables plug-in and you can see more details in the Enhancing HTML tables using the jQuery DataTables plug-in article. Also, you can use a lot of other enhancements such as:

You can see a complete list of additional DataTable plugins on the DataTables site. All these plug-ins are additional add-ons for DataTables, but you can also use the powerful DataTables API to customize behavior. An example of the plain table enhanced with a few mentioned plugins is shown in the following figure:

In this example are added a grouping plugin that partitions rows by the first letter of the company name, and columns filter widget that adds filtering dropdowns above the table. In the figure above, companies are filtered by the town London. Adding these plugins is easy - you will just need to modify the initialization call and if needed, add some parameters as shown in the following example:

$(document).ready(function () {
    $("#companies").dataTable({
        "sPaginationType": "full_numbers",
        "bJQueryUI": true,
        "sDom": 'W<"clear">lfrtip'
    })
    .rowGrouping({sGroupBy: "letter", bHideGroupingColumn: false})
});

If you have a reasonable number of records in the table, you do not need to worry about these functionalities. Just render a plain table and apply some combination of plug-ins that you need.

However, if you have a lot of records that are shown in the table and you want to avoid complex JavaScript processing in the browser, you can implement the processing logic on the server-side (e.g., in some servlet), and setup DataTables to query the server via AJAX calls in order to take information that should be displayed. This mode is described in the following section.

Fully AJAXified Table - Server Side Processing Mode

With the jQuery DataTables plugin, it is possible to implement client-server interaction by configuring DataTables to query the server via AJAX calls in order to fetch the required data. In this case, the plug-in will maintain UI state on the client-side, handle all events, but it will not process data at all. Instead of this, it will call the server side page, post information about the current state and required data, take the response from the server, and refresh the table content.

On the DataTables site, there is an example of server-side configuration where the jQuery DataTables plug-in sends requests to a PHP page and gets data that should be shown in the current view. The server response is formatted as a JSON object, parsed on the client side, and displayed in the table body.

In this case, each event (changing the number of items that should be displayed per page, entering keyword in search filter, sorting, pressing pagination button, etc.) triggers the DataTables plug-in to send information about the current page, the search filter, and the sort column to the server page. As shown in the request, the server page returns JSON as a result and DataTables uses that data array when displaying the current table page. In this mode, instead of taking the complete page at once, several smaller requests are sent whenever new information is required, and minimal amount of data is returned from the server. DataTables, in this example, calls the /CompanyAjaxDataSource URL and sends information about the user action. A full example of the server-side configuration of the jQuery DataTables plug-in can be found here. A major problem with the server-side mode is the implementation of server-side logic that accepts parameters from the client-side component, performs action, and returns data as expected.

In AJAX mode, only a minimal amount of data is provided to the plug-in using JSON. The plug-in sends AJAX requests to the server containing information of the current state of the view (current page, filter criterion, page number, etc.). The server accepts the AJAX call and determines what information should be shown on the client side and returns a JSON response back to the plug-in. Note that in this case, processing must be implemented on the server side.

In AJAX mode, no relevant information is generated in the view page, therefore it can be even a static HTML page. An example of the HTML page used in this example is shown in the following listing:

<!DOCTYPE html>
<html>
    <head>
        <title>Using jQuery DataTables plugin with AJAX 
           source implemented in Java web application</title>
        <link href="media/dataTables/demo_page.css" 
           rel="stylesheet" type="text/css" />
        <link href="media/dataTables/demo_table.css" 
           rel="stylesheet" type="text/css" />
        <link href="media/dataTables/demo_table_jui.css" 
           rel="stylesheet" type="text/css" />
        <link href="media/themes/base/jquery-ui.css" 
          rel="stylesheet" type="text/css" media="all" />
        <link href="media/themes/smoothness/jquery-ui-1.7.2.custom.css" 
          rel="stylesheet" type="text/css" media="all" />
        <script src="scripts/jquery-1.4.4.min.js" 
          type="text/javascript"></script>
        <script src="scripts/jquery.dataTables.min.js" 
          type="text/javascript"></script>
        <script type="text/javascript">
        $(document).ready(function () {
            $("#companies").dataTable({
                "bServerSide": true,
                "sAjaxSource": "/JQueryDataTables/CompanyAjaxDataSource",
                "bProcessing": true,
                "sPaginationType": "full_numbers",
                "bJQueryUI": true
            });
        });
        </script>
    </head>
    <body id="dt_example">
        <div id="container">
            <div id="demo_jui">
        <table id="companies" class="display">
              <thead>
                  <tr>
                       <th>Company name</th>
                       <th>Address</th>
                       <th>Town</th>
                  </tr>
              </thead>
              <tbody>
              </tbody>
        </table>
        </div>
        </div>
    </body>
</html>

As you can see, the table body is completely empty because the jQuery DataTables plug-in will be populated using the AJAX call. In the document ready event, DataTables is initialized with three additional parameters:

bServerSide that instructs the DataTables plug-in to take information from the server-side
sAjaxSource that defines that URL that should be called by the plug-in to take data
bProcessing (optional) used to show the "Processing" message while the AJAX call is executing

The key part of the server-side code is the component that will provide data to the jQuery DataTables plugin - in this case, this is the component on the server-side that reacts when the sAjaxSource page is called. This can be anything: servlet, JSP page, or any server-side code that returns a JSON response based on the parameters sent from the plug-in. The jQuery DataTables plug-in sends a lot of parameters to the server-side; you can find a detailed documentation on the DataTables site, but here are the most important ones:

sEcho - Integer value that is used by DataTables for synchronization purposes. Response from the server-side code should return the same value to the plug-in.
sKeyword - Text entered in the filter text box and it should be used for filtering records.
iDisplayStart - First record that should be shown (used for pagination).
iDisplayLength - The number of records that should be returned (this value is equal to the value selected in the 'Show XXX items per page' dropdown). This value is also used for pagination.
iColumns - The number of columns in the table.
iSortingCols - The number of columns used for ordering. Usually this value is 1, but if the user orders results by more than one column (holding the SHIFT key while clicking on the header cells), the DataTables plug-in will send information about the number of columns you should use for ordering results.
iSortCol_0, iSortCol_1, iSortCol_2, etc. - The IDs of the columns used for ordering results. If results are ordered by one column, you should order results by the iSortCol_0 column.
sSortDir_0, sSortDir_1, sSortDir_2, etc. - The sort direction for each of the columns used for ordering. If results are ordered by one column, an "asc" or "desc" value will be returned in the sSortDir_0 parameter. In the case of multi-column ordering, each parameter in this array will have a direction that matches the column in the iSortCol_ parameter.

The server-side component should have the GET method handler that will be called when the plug-in sends an AJAX request. This method should take the parameters described above, process data, and prepare values that will be sent to the plug-in. An example of the response that is returned back from the servlet is shown in the example below:

{   "sEcho":"1",
    "iTotalRecords":97,
    "iTotalDisplayRecords":9,
    "aaData":[    
            ["Zander Exports", "34 Sapcote Trading Centre", "London"],
            ["Windsong International", "Heather Court", "Kent"],
            ["Wilkinson Turner King", "10A London Road", "Cheshire"],
            ["Web User", "IPC Media", "London "],
            ["Way to Blue", "First Floor", "London"],
            ["Warner Home DVD", "Warner House", "London"],
            ["Vivante Music Ltd", "32 The Netherlands", "Surrey"],
            ["Vinyl Music", "1 Minerva Works", "West Yorkshire"],
            ["Villa Audio Ltd", "Baileys Yard", "Essex"]
        ]
}

Values that the server returns to the DataTables plug-in are:

sEcho - An integer value that is used by DataTables for synchronization purposes. On each call sent to the server-side page, the DataTables plug-in sends the sequence number in the sEcho parameter. The same value has to be returned in the response because DataTables uses this for synchronization and matching requests and responses.
iTotalRecords - The integer value that represents the total unfiltered number of records that exist on the server-side and that might be displayed if no filter is applied. This value is used only for display purposes; when the user types in a keyword in the search text box, DataTables shows a "Showing 1 to 10 of 23 entries (filtered from 51 total entries)" message. In this case, the iTotalRecords value returned in the response equals 51.
iTotalDisplayedRecords - The integer value that represents the number of records that match the current filter. If the user does not enter any value in the search text box, this value should be the same as the iTotalRecords value. The DataTables plug-in uses this value to determine how many pages will be required to generate pagination - if this value is less or equal than the current page size, the pagination buttons will be disabled. When the user types in a keyword in the search text box, DataTables shows a "Showing 1 to 10 of 23 entries (filtered from 51 total entries)" message. In this case, the iTotalDisplayedRecords value returned in the response equals 23.
aaData - A two-dimensional array that represents the cell values that will be shown in the table. When DataTables receives data, it will populate the table cells with values from the aaData array. The number of columns in the two dimensional array must match the number of columns in the HTML table (even the hidden ones), and the number of rows should be equal to the number of items that can be shown on the current page (e.g., 10, 25, 50, or 100 - this value is selected in the "Show XXX entries" drop-down).

In this case, a matrix of cells that will be displayed is returned. However, this is not the only format you can use. You can also return an array of JSON objects in the following format:

{
    "sEcho":"1",
    "iTotalRecords":73,
    "iTotalDisplayRecords":51,
    "aaData":[   
            {"name":"Zane Music","address":"162 Castle Hill","town":"Berkshire"},
            {"name":"Zander Exports","address":"34 Sapcote Trading Centre","town":"London"},
            {"name":"Windsong International","address":"Heather Court","town":"Kent"},
            {"name":"Wilkinson Turner King","address":"10A London Road","town":"Cheshire"},
            {"name":"Web User","address":"IPC Media","town":"London "},
            {"name":"Way to Blue","address":"First Floor","town":"London"},
            {"name":"Warner Home DVD","address":"Warner House","town":"London"},
            {"name":"Vivante Music Ltd","address":"32 The Netherlands","town":"Surrey"},
            {"name":"Vinyl Music","address":"1 Minerva Works","town":"West Yorkshire"},
            {"name":"Villa Audio Ltd","address":"Baileys Yard","town":"Essex"}
        ]
}

In this case, named properties in the array are returned, instead of the array of arrays like in the previous case. The DataTable initialization call should be slightly changed because we would need to map properties in the objects to the table columns. The initialization call is shown in the following code:

$(document).ready(function () {
    $("#companies").dataTable({
        "bServerSide": true,
        "sAjaxSource": "/JQueryDataTablesAll/CompanyGsonObjects",
        "bProcessing": true,
        "sPaginationType": "full_numbers",
        "bJQueryUI": true,
        "aoColumns": [
                      { "mDataProp": "name" },
                      { "mDataProp": "address" },
                      { "mDataProp": "town" }
                  ]
    });
});

In this example, mapping of properties to columns in the aoColumns parameter of the DataTable initialization call is added.

Servlet Implementation

Any Java server-side component that accepts the parameters described above and returns the expected JSON result can be used. In this example, a plain servlet is used for demonstration purposes, but you can use any other component. The servlet used in this example has a doGet method that accepts parameters and returns a JSON object. The following listing shows an example of the get method:

protected void doGet(HttpServletRequest request, HttpServletResponse response) 
               throws ServletException, IOException {
    JQueryDataTableParamModel param = DataTablesParamUtility.getParam(request);    
    String sEcho = param.sEcho;
    int iTotalRecords;       // total number of records (unfiltered)
    int iTotalDisplayRecords;//value will be set when code filters companies by keyword

    //Filtering companies
    //Ordering companies
    //Pagination
    //Generate JSON response
}

The servlet is mapped on the /CompanyAjaxDataSource URL and the get method takes parameters sent by the plug-in. For this purpose, we have added two utility classes: JQueryDataTableParamModel containing the properties that are sent by the plug-in, and DataTablesParamUtility that loads the values of the JQueryDataTableParamModel from the request. Also, in this part of code, values that will be sent to the plug-in are prepared. The actual code that populates properties from the request is omitted, but you can find the code in the code example. Note that properties in this class have the same names as the parameters sent by the plug-in so you can easily follow the code.

The first action that needs to be done on the server-side is filtering of companies by the keyword provided by the plug-in. This code is shown in the listing below:

iTotalRecords = DataRepository.GetCompanies().size();
List<Company> companies = new LinkedList<Company>();
for(Company c : DataRepository.GetCompanies()){
    if(    c.getName().toLowerCase().contains(param.sSearch.toLowerCase())
                ||
        c.getAddress().toLowerCase().contains(param.sSearch.toLowerCase())
                ||
        c.getTown().toLowerCase().contains(param.sSearch.toLowerCase()))
    {
        companies.add(c); // Add a company that matches search criterion
    }
}
iTotalDisplayRecords = companies.size();
//Number of companies that matches search criterion should be returned

The keyword entered in the filter text box is placed in the param.sSearch string. In this example, iTotalRecords is set to the total number of companies that are in the list, a search is performed by the company properties, and a new list of filtered companies that contains the keyword are added in the list. The number of filtered companies is placed in the iTotalDisplayRecords variable. In the second part of the code, companies are ordered by column. The following code shows ordering done using the index of the column that should be sorted and the direction. On the server-side code, you will need to know what column indexes match properties in the Company class.

final int sortColumnIndex = param.iSortColumnIndex;
final int sortDirection = param.sSortDirection.equals("asc") ? -1 : 1;

Collections.sort(companies, new Comparator<Company>(){
    @Override
    public int compare(Company c1, Company c2) {    
        switch(sortColumnIndex){
        case 0:
            return c1.getName().compareTo(c2.getName()) * sortDirection;
        case 1:
            return c1.getAddress().compareTo(c2.getAddress()) * sortDirection;
        case 2:
            return c1.getTown().compareTo(c2.getTown()) * sortDirection;
        }
        return 0;
    }
});

This is a simplified case where it is assumed that ordering is done by one single column and that the index of the column that will be used for sorting and the direction are placed in the param.iSortColumIndex and param.sSortDirection properties.

The last functionality that should be implemented is pagination. The current page and the length are placed in the iDisplayStart and iDisplayLength properties, and these properties are used to get the sub list that should be returned to the plug-in. An example is shown in the following listing:

if(companies.size()< param.iDisplayStart + param.iDisplayLength)
    companies = companies.subList(param.iDisplayStart, companies.size());
else
    companies = companies.subList(param.iDisplayStart, 
                   param.iDisplayStart + param.iDisplayLength);

When the list is prepared, a JSON object that represents the response should be created. The code for creating the JSON response is:

try {
    JsonObject jsonResponse = new JsonObject();
    
    jsonResponse.addProperty("sEcho", sEcho);
    jsonResponse.addProperty("iTotalRecords", iTotalRecords);
    jsonResponse.addProperty("iTotalDisplayRecords", iTotalDisplayRecords);
    
    Gson gson = new Gson();
    
    for(Company c : companies){
        JsonArray row = new JsonArray();
        row.add(new JsonPrimitive(c.getName()));
        row.add(new JsonPrimitive(c.getAddress()));
        row.add(new JsonPrimitive(c.getTown()));
        data.add(row);
    }
    jsonResponse.add("aaData", data);
    
    response.setContentType("application/Json");
    response.getWriter().print(jsonResponse.toString());
} catch (JsonIOException e) {
    e.printStackTrace();
    response.setContentType("text/html");
    response.getWriter().print(e.getMessage());
}

This example has the echo, total records, and total filtered records properties. Also, the data properties have the matrix containing the name, address, and town information. When this object is returned to the plug-in, filtered information is shown in the table on the client side.

As you saw earlier, you can output either a matrix or an array of objects back to the DataTable. If you want to output an array of objects, the code is slightly different:

Gson gson = new Gson();
try {

    JsonObject jsonResponse = new JsonObject();
    
    jsonResponse.addProperty("sEcho", sEcho);
    jsonResponse.addProperty("iTotalRecords", iTotalRecords);
    jsonResponse.addProperty("iTotalDisplayRecords", iTotalDisplayRecords);
    jsonResponse.add("aaData", gson.toJsonTree(companies));
    
    response.setContentType("application/Json");
    response.getWriter().print(jsonResponse.toString());
} catch (JsonIOException e) {
    e.printStackTrace();
    response.setContentType("text/html");
    response.getWriter().print(e.getMessage());
}

In this example, the GSON library is used for serializing Java objects to JSON, but you can use any other JSON serialization library instead.

In this example, processing is done in plain source code; however, in your application, you can use other methods such as SQL, Stored Procedures, HQL, etc. You can find an example that generates JSON response from the database on the DataTables site. The only important thing is that you return a JSON response with objects that match the current state on the table.

Conclusion

This example shows how you can create effective, fully functional tables in a Java web application using the jQuery DataTables plug-in. Using the code examples in the article, you can significantly enhance the look and functionalities of your web application. I recommend that you try it - when you integrate jQuery DataTables in a few tables in your application, you will see that the implementation is straightforward and that you will be, with some practice, able to implement a lot of functionalities with very little effort.

You can download the code example in the attached project that was created in the Eclipse Java EE IDE for Web Developers, that runs on a Tomcat 6.0 web server. If you have the same configuration, you can run and try this project, and if you have any other development environment, I suggest you create a new project, configure it, and add classes that you can find in the project. I hope that this example will help you to create better table interfaces.

If you are interested in adding full Web 2.0 CRUD functionalities to jQuery DataTables, I recommend another article, Adding data management (CRUD) functionalities to web tables, where I have explained how you can configure plugin to automatically add inline editing, deleting, and adding new records functionalities to the jQuery DataTables plugin.

History

7^th April, 2012: Initial version

jQuery DataTables in Java Web Applications