hirondelle.web4j.database
Class Report

Object
  hirondelle.web4j.database.Report

public final class Report
extends Object

Utility for producing reports quickly from a ResultSet.

Most web applications need to produce reports of summary or transaction information. If a Model Object already exists for the given data, then it may be used to fetch and render the data, likely with Db.

If a Model Object does not already exist for the given report data, then this class may be used to quickly implement the report, without the need to create a full Model Object.

This class translates each ResultSet row into a Map of some form. This Map is meant not as a robust Model Object, but rather as a rather dumb data carrier, built only for the purpose of reporting. The Map key is always the column name, and the Map value takes various forms, according to how the ResultSet is processed :

• formatted - column values are parsed using ConvertColumn into Integer, Date, and so on, and then standard formatting is applied using Formats.objectToText(Object). (This is the recommended style.)
• unformatted - column values are parsed using ConvertColumn into Integer, Date, and so on, but formatting is deferred to the JSP.
• raw - column values are all treated as simple text. To allow for various escaping styles in the view, the text is actually returned as SafeText. By default, the text will be properly escaped for presentation in HTML. If desired, some formatting can be applied directly in the underlying SQL statement itself, using database formatting functions.

Example of using the Map in a JSP. Here, column values are assumed to be already formatted, using either raw or formatted:

<c:forEach var="row" items="${reportMap}" >
 <tr>
  <td>${row['Name']}</td>  
  <td>${row['Visits']}</td>  
 </tr>
</c:forEach>
  

If unformatted is used to build the Map, then formatting of the resulting objects must be applied in the JSP.

Recommended Style

The recommended style is to use formatted.

If raw or unformatted is used, then the question usually arises of where to apply formatting:

• format with database formatting functions - then there will often be much repetition of formatting function calls across different SELECTs.
• format in the JSP (usually with JSTL) - be aware that there is often significant work involved. Not one but three operations can be necessary: a parse operation, a format operation, and possibly a check-for-null.

Empty Values

When the Map returned by this class has values as text, then any Strings which do not satisfy Util.textHasContent(String) are replaced with the return value of Formats.getEmptyOrNullText() (which is in turn configured in web.xml). This is a workaround for the fact that most browsers do not render empty TD tags very well when the cell has a border. An alternate (and likely superior) workaround is to set the empty-cells property of Cascading Style Sheets to 'show'.

Method Summary

static List<Map<String,SafeText>>	formatted(Class<?>[] aTargetClasses, Locale aLocale, TimeZone aTimeZone, SqlId aSqlId, DynamicSql aCriteria, Object... aParams) Return column values after processing into formatted building block objects.
static List<Map<String,SafeText>>	raw(SqlId aSqlId, DynamicSql aCriteria, Object... aParams) Return column values without any processing.
static List<Map<String,Object>>	unformatted(Class<?>[] aTargetClasses, SqlId aSqlId, DynamicSql aCriteria, Object... aParams) Return column values as unformatted building block objects.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

raw

public static List<Map<String,SafeText>> raw(SqlId aSqlId,
                                             DynamicSql aCriteria,
                                             Object... aParams)
                                      throws DAOException

Return column values without any processing.

For the returned Map<String, SafeText> objects,

• key is the column name
• value is the unprocessed column value, passed to a SafeText. SafeText is used instead of String to allow easy escaping of special characters in the view.

Parameters:

aSqlId - identifies the underlying SELECT statement

aCriteria - possible dynamic WHERE or ORDER BY clause. If no dynamic criteria, then just pass DynamicSql.NONE.

aParams - parameters for the SELECT statement, in the same order as in the underlying SELECT statement

Throws:

DAOException

formatted

public static List<Map<String,SafeText>> formatted(Class<?>[] aTargetClasses,
                                                   Locale aLocale,
                                                   TimeZone aTimeZone,
                                                   SqlId aSqlId,
                                                   DynamicSql aCriteria,
                                                   Object... aParams)
                                            throws DAOException

Return column values after processing into formatted building block objects.

For the returned Map<String, SafeText> objects,

• key is the column name
• value is the processed column value, as SafeText. Column values are first parsed into building block objects using ConvertColumn. Then the objects are formatted in a 'standard' way using the configured Formats.

Parameters:

aTargetClasses - defines the target class for each column. The order of the classes in the array corresponds one-to-one with the column order of the underlying ResultSet. The size of the array matches the number of columns. Each class in the array must be supported by the configured ConvertColumn.

aLocale - Locale returned by LocaleSource

aTimeZone - TimeZone returned by TimeZoneSource

aSqlId - identifies the underlying SELECT statement

aCriteria - possible dynamic WHERE or ORDER BY clause. If no dynamic criteria, then just pass DynamicSql.NONE.

aParams - parameters for the SELECT statement, in the same order as in the underlying SELECT statement

Throws:

DAOException

unformatted

public static List<Map<String,Object>> unformatted(Class<?>[] aTargetClasses,
                                                   SqlId aSqlId,
                                                   DynamicSql aCriteria,
                                                   Object... aParams)
                                            throws DAOException

Return column values as unformatted building block objects.

For the returned Map<String, Object> objects,

• key is the column name
• value is the processed column value, parsed into a building block Object using ConvertColumn.

Parameters:

aTargetClasses - defines the target class for each column. The order of the classes in the array corresponds one-to-one with the column order of the underlying ResultSet. The size of the array matches the number of columns. Each class in the array must be supported by the configured ConvertColumn.

aSqlId - identifies the underlying SELECT statement

aCriteria - possible dynamic WHERE or ORDER BY clause. If no dynamic criteria, then just pass DynamicSql.NONE.

aParams - parameters for the SELECT statement, in the same order as in the underlying SELECT statement

Throws:

DAOException