Related Links
Documentation Logo

What is the FormattedDataSet?

The FormattedDataSet Java class is the easiest way to generate dynamic text (HTML, XML, WML, CSV, and more). The dynamic text is generated by using tabular data as input (SQL, ResultSets, 2 dimensional arrays and more). The API is free, open-source, thread safe, and high performance. The primary benefit of using the FormattedDataSet is that both data and formatting can be reused independently.

Out-of-the-box the FormattedDataSet will generate HTML (tables, list boxes, drop down listboxes, multi-select listboxes, and radio buttons), XML and delimited output. The FormattedDataSet stores formatting in templates. FormattedDataSet templates are simply Java Strings, typically stored as files. In addition to using the Out-of-the-box templates mentioned above, developers and GUI designers can create their own templates and so can have total control over presentation formatting.

Templates are usually very simple. For example the out-of-the-box XML template was created in minutes, and is only about 10 lines long. Despite this simplicity the template has the power to render ANY tabular data as XML.

The FormattedDataSet was developed primarily for generating dynamic HTML in JSPs and Servlets, however it can be used in any JDK 1.2 or higher environment to generate ANY dynamic text.

What else is in the FormattedDataSet API?

The FormattedDataSet API also comes with a number of classes that can be used as standalone utility classes or used to enhance the power of the FormattedDataSet class itself. Arrays have become my "tabular data" of choice, as it is easy to get data from ANY source into an array. For example an array can be a mixture of data from programmatic state, ResultSets, and other sources. Many of the FormattedDataSet APIs most powerful utility classes are used to help developers more easily manipulate arrays. The most important of these classes follow:

  • ResultSetConverter - This class converts a ResultSet and its associated ResultSetMetaData into 2 dimensional (Object[][]), and 1 dimensional (String[]) arrays respectively. This abstraction allows developers to entirely bypass JDBC objects and method calls (i.e. no calls to Connection, Statement, and ResultSet etc.). The ResultSetConverter also keeps statistics on JDBC performance.
  • DataAccess - The ResultSetConverter uses the DataAccess class to make all JDBC calls. This class abstracts whether your database connections are made in a J2EE container or a standalone client.
  • ArraySQL - This class allows a developer to query arrays in a SQL-like style. The ArraySQL syntax supports a display list of columns, as well as the "where" and "order by" clauses (Example: select rowNum(),* from array where fname in ('steve','joel') order by lname, fname). The ArraySQL query is run by calling the 'execute(...)' method. In addition by calling the ArraySQL 'convert(...)' method, developers can easily format arrays for display (examples include: replacing nulls with the empty string, formatting dates, and comma delimitting numbers). Using ArraySQL and ResultSetConverter together allows a developer to easily combine programmatic and database data.

Ease of Use

The FormattedDataSet API is easy to use. No installation is required; a developer only has to place a few small jars in the class path and within a few minutes can start displaying dynamic text, and using the utility classes. Also, the learning curve for creating FormattedDataSet templates is not steep, unlike competing products that involve knowing any number of the following technologies: JDBC, tag libraries, proprietary GUI tools, and complex proprietary runtime Object creation code.

The required JARs are:

  • fdsapi.jar - The FormattedDataSet API
  • JAMon.jar - Performance statistics are automatically gathered for many of the FormattedDataSet API's method calls using JAMon (Java Application Monitor).
  • jakarta-oro-2.0.6.jar (or higher) - Regular Expression engine used to parse FormattedDataSet templates

In a Web application you could put these three jars in the "web-inf\lib" directory.

Simple JSP Code Example

The following example is a fully functioning JSP that uses the FormattedDataSet to display ANY query as an HTML table. The query will execute against the specified J2EE DataSource (your server must have access to this DataSource). If you can write a query you can use the FormattedDataSet.

<%@ page language="java" buffer="8kb" autoFlush="true" isThreadSafe="true" %>
<%@ page import="com.fdsapi.*" %>

// Construct the FormattedDataSet
FormattedDataSet fds = FormattedDataSet.createInstance();
String html = fds.getFormattedDataSet("MyDataSource", "SELECT * FROM table", "htmlTable");
<%= html %>


Representative output follows:

First Name Last Name
Keith Richards
Mick Jagger
Bill Wyman
Ron Wood
Charlie Watts
Mick Taylor
Brian Jones

Note that the details of JDBC are abstracted away (the developer doesn't have to make the JDBC calls). Although this example uses a J2EE DataSource straight JDBC connections are also supported.

The FormattedDataSet methods are overloaded to take ANY type of tabular data, so although this example takes a query it could just as easily taken a ResultSet, a two dimensional array (Object[][]) and others.

A sample call that takes a ResultSetMetaData object (header information), and a ResultSet object (the data) follows:

String html = fds.getFormattedDataSet(resultSetMetaData, resultSet, "htmlTable");

Tables with clickable column header sorting can also easily be created. Click on the columns below to see the demo.

First Name
Last Name
Bill Wyman
Ron Wood
Charlie Watts
Mick Taylor
Keith Richards
Brian Jones
Mick Jagger

Separation of Data and Formatting

The FormattedDataSet cleanly separates data from presentation formatting. In JSPs, often developers use tag libraries to display data. To do this you must put data, iteration code and HTML formatting in a JSP.

In the JSP/Tag solution, the formatting cannot be reused independently from the data. If a similar report is created in another JSP the HTML tags must be repeated. In addition the data can't be reused either as the iteration logic is embedded within the tags of each JSP. The FormattedDataSet can reuse both the data, and the formatting in any number of JSPs/Servlets or even straight Java code. For example one HTML table template could be created for the whole enterprise and if this template were changed, all pages using it would automatically be updated to the new look and feel.

In a recently developed application, the backend developer was often able to return new columns to the front end and because the GUI and Java developers used the FormattedDataSet, often they did not have to change their code. In other cases, the GUI developer was able to make GUI changes without the backend and Java developers needing to make changes to their work. This capability allows GUI, backend, and Java developers to work independently.

The following graphic demonstrates how the same template may be used to format ANY type of TabularData (in this case two stored procs returning ResultSets, and a SQL select statement). (Note the "tab controls" below are not rendered by the call to getFormattedDataSet(...). Only "htmlTable" is rendered.)

The following example demonstrates how varying the template (i.e. the formatting) allows you to vary the presentation while keeping the data constant. The example shows the "emails" table being formatted as an "htmlTable", "formLetter" and "xml" respectively.

How Do I Learn More?

This web page has only touched on the power of the FormattedDataSet API, to get a full understanding of all it can do read the documentation. All documentation is available in the links section at the top of the page or by download from SourceForge. Documentation includes the FormattedDataSet API Users Manual, Java Docs, presentations and sample code. The Java Docs contain lots of sample code. In addition the java docs of all classes have a 'View Code' link that allows a developer to quickly look at the classes code. The 'main' method of many classes are interesting as they have test and sample code. Some of the method signatures in the presentations are out of date (particularly the FDS details presentation). When in doubt about a method signature refer to the Java Docs.

The FormattedDataSet API Users Manual also has all the information you need to create your own templates as well as information on all the other other useful API utilities.

Live Demo

An online demo is available. The demo allows you to enter SQL and have it displayed as HTML tables. The demo also generates dynamic XML, CSV, listboxes, drop down listboxes, multi-select listboxes, and demonstrates clickable column header sorting. An explanation of the demo application follows:

  • demo.jsp - Index to access the other demo pages in the application. Click here to access all pages in the demo application.
  • basicdemo.jsp - Simple JSP demonstrating how to create dynamic HTML (tables, list boxes, drop down list boxes and multi-select list boxes), XML and CSV files. No database access is used for this page. The dynamic content is built from arrays. All pages in the demo have a view code button that allows you to view how the page was generated.
  • querydemo.jsp - A JSP that allows you to enter and execute a SQL select statement. The ResultSet is displayed as an HTML table. All JSPs that access a database have a button that displays an ER diagram (musicians and groups). This helps you see what valid queries you may enter.
  • sortdemo.jsp - Just like querydemo.jsp except the ResultSet is sortable by clicking the HTML table’s column headers.
  • JAMonAdmin.jsp - Administration page for JAMon (an open source performance tuning API), that displays various performance statistics for the demo application. The FormattedDataSet API code is monitored as well as all site page and file hits (via a Servlet filter).

This application (fdsapi.war) is also available for you to run in your application server and is part of the FormattedDataSet download. An in memory database is included in the WAR, so you may simply install the WAR and start making queries! If you wish to point the demo to one of your own databases you will have to go into querydemo.jsp and sortdemo.jsp and make minor changes. The WAR has been tested with Sybase’s EAServer connecting to Sybase ASE, and Apache Tomcat connecting to MySQL, and hsqldb.

Download the FormattedDataSet API

You may download the FormattedDataSet API from SourceForge. The download file has the following format:, where MMDDYY is the date of the build. This file contains the jars that are required to run the FormattedDataSet (fdsapi.jar, JAMon.jar, and Jakarta's ORO jar). In addition it has the same demo Web Application (WAR) that is available via this website.