#LyX 1.6.7 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass scrbook
\begin_preamble
\input{preamble.tex}
\end_preamble
\use_default_options false
\language english
\inputencoding utf8
\font_roman lmodern
\font_sans helvet
\font_typewriter courier
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\float_placement H
\paperfontsize default
\spacing single
\use_hyperref false
\papersize letterpaper
\use_geometry false
\use_amsmath 2
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\bullet 0 5 11 -1
\bullet 1 5 24 -1
\bullet 2 0 0 -1
\tracking_changes false
\output_changes false
\author ""
\author ""
\end_header
\begin_body
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
input{chapter.tex}
\end_layout
\end_inset
\end_layout
\begin_layout Chapter
\family typewriter
\begin_inset CommandInset label
LatexCommand label
name "cha:Resource-Bundles"
\end_inset
\family default
Resource Bundles
\end_layout
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
epigraph{Always code as if the guy who ends up maintaining your code will
be a violent psychopath who knows where you live.}{John F.
Woods}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Resource bundles provide a way to organize and maintain text literals (that
is, descriptive text that appears on a report but is not part of the results
from a database query).
Placing all report text literals in a single location is forward thinking,
even if you have no plans to provide internationalization.
A resource bundle is a plain text file with key-value pairs assigned as
follows:
\end_layout
\begin_layout LyX-Code
\family typewriter
key=value
\end_layout
\begin_layout Standard
Developers implement the reports using the key, and then
\begin_inset ERT
status open
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
automatically substitutes its corresponding value when the report is generated.
Resource bundles allow many possibilities:
\end_layout
\begin_layout Itemize
Commenting for text field use and size.
\end_layout
\begin_layout Itemize
Consistent text used across all reports.
\end_layout
\begin_layout Itemize
Complex strings that rely on database values.
\end_layout
\begin_layout Itemize
Change a single word and have it propagate across all reports without recompilin
g.
\end_layout
\begin_layout Itemize
Prepare system for future development with internationalization.
\end_layout
\begin_layout Itemize
Parallel development of reports and text translation.
\end_layout
\begin_layout Standard
Resource bundles have a few drawbacks, including:
\end_layout
\begin_layout Itemize
Increased testing time due to dependency coupling.
\end_layout
\begin_layout Itemize
Complex configuration.
\end_layout
\begin_layout Itemize
Time consuming to create (initially).
\end_layout
\begin_layout Standard
The advantages outweigh the drawbacks.
This chapter addresses the drawbacks to using resource bundles on reporting
projects.
When you understand how to use resource bundles, the next question is:
how do you create automated resource bundles using a database?
\end_layout
\begin_layout Standard
In this chapter:
\end_layout
\begin_layout Itemize
\series bold
Dependencies.
\series default
Edit property file comments to document field width restrictions.
\end_layout
\begin_layout Itemize
\series bold
Configuration.
\series default
How to configure resource bundles in
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
and
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
.
\end_layout
\begin_layout Section
Dependencies
\end_layout
\begin_layout Standard
Changing the value of a property will affect reports that rely on that property.
This is the point of resource bundles and is highly desirable.
A consequence of changing the property's value is, if the new value is
longer than the old value, any report that uses that property must be previewed
to validate that the longer word fits.
Comments are a simple solution to this problem.
\end_layout
\begin_layout Standard
Comments describe any line in the a resource bundle file that begins with
a hash mark (#).
There are a couple of ways to add comments to a properties file:
\end_layout
\begin_layout Itemize
Use a regular text editor.
\end_layout
\begin_layout Itemize
Use
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
's properties file editor.
\end_layout
\begin_layout Subsection
Properties File -- Manual Editing
\end_layout
\begin_layout Standard
Group related keys together and use comments to indicate field widths (in
pixels).
For example, the field width could display the minimum and maximum allowed
widths for that field.
(All widths in between may be permitted as well, if you so choose.
Perhaps only the minimum width is required, based on the corporate standard
font style and size.)
\end_layout
\begin_layout Standard
The comments shown in
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Properties-File"
\end_inset
are displayed in their respective
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
Comment field.
This allows developers to produce a consistent layout across reports.
Comments are also shown as tool-tips when hovering over
\series bold
Favorites
\series default
panel items (
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Properties-File-in-Favourites"
\end_inset
shows the
\series bold
Favorites
\series default
panel).
\end_layout
\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename source/text/city.properties.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:Properties-File"
\end_inset
Properties File
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Properties File --
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
Editing
\end_layout
\begin_layout Standard
The properties file can be edited directly in
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
, as follows:
\end_layout
\begin_layout Enumerate
Open
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
filejrxmlcity}
\end_layout
\end_inset
.
\end_layout
\begin_layout Enumerate
Delete
\series bold
city_name
\series default
,
\series bold
region_id
\series default
,
\series bold
latitude
\series default
, and
\series bold
longitude
\series default
from the report.
\end_layout
\begin_layout Enumerate
Open
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileproptext}
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
The
\series bold
Properties Editor Window
\series default
appears (
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:iReport-Properties-Editor-Window"
\end_inset
).
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-edit-properties.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:iReport-Properties-Editor-Window"
\end_inset
Properties Editor Window
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
To make the resource bundle properties readily available, add the file to
the
\series bold
Favorites
\series default
panel:
\end_layout
\begin_layout Enumerate
Click
\series bold
Window
\begin_inset Quotes ald
\end_inset
Favorites
\series default
.
\end_layout
\begin_layout Enumerate
Right-click inside the
\series bold
Favorites
\series default
panel.
\end_layout
\begin_layout Enumerate
Click
\series bold
Add to Favorites
\series default
.
\end_layout
\begin_layout Enumerate
Browse to and select
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileproptext}
\end_layout
\end_inset
.
\end_layout
\begin_layout Enumerate
Click
\series bold
Add
\series default
.
\end_layout
\begin_layout Standard
The
\series bold
Favorites
\series default
panel appears (
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Properties-File-in-Favourites"
\end_inset
).
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-favourites.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Properties-File-in-Favourites"
\end_inset
Properties File in Favorites
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Complete the following steps to make reference to the resource bundle names:
\end_layout
\begin_layout Enumerate
Replace
\series bold
city_name
\series default
with a
\series bold
Text field
\series default
with the following value:
\end_layout
\begin_deeper
\begin_layout LyX-Code
\family typewriter
str( "city.name" )
\end_layout
\end_deeper
\begin_layout Enumerate
Replace
\series bold
region_id
\series default
,
\series bold
latitude
\series default
, and
\series bold
longitude
\series default
with their respective expressions:
\end_layout
\begin_deeper
\begin_layout LyX-Code
\family typewriter
str( "region.id" )
\end_layout
\begin_layout LyX-Code
\family typewriter
str( "latitude" )
\end_layout
\begin_layout LyX-Code
\family typewriter
str( "longitude" )
\end_layout
\end_deeper
\begin_layout Standard
The result resembles
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Resource-Bundle-Name-References"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-resource-bundle-str.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Resource-Bundle-Name-References"
\end_inset
Resource Bundle Name References
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The report is nearly ready to run.
Clicking
\series bold
Preview
\series default
at this point will result in a number of
\family typewriter
null
\family default
values displayed.
The
\family typewriter
null
\family default
values are due to
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
not being configured with the directory that contains the resource bundle
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileproptext}
\end_layout
\end_inset
.
Even though the content is visible in the
\series bold
Favorites
\series default
panel in
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
, the resource bundle cannot be loaded by
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
The following section describes how to configure both
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
and
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
.
\end_layout
\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Resource-Bundles-Configuration"
\end_inset
Configuration
\end_layout
\begin_layout Standard
The location of the resource bundle must be set explicitly for
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
and
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
.
\end_layout
\begin_layout Subsection
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
After adding and editing a resource bundle, perform the following steps:
\end_layout
\begin_layout Enumerate
Open
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
filejrxmlcity}
\end_layout
\end_inset
(if it is not already visible).
\end_layout
\begin_layout Enumerate
Click
\series bold
city
\series default
at the top of the
\series bold
Report Inspector
\series default
to expose the
\series bold
Properties
\series default
panel.
\end_layout
\begin_layout Enumerate
Click the button beside
\series bold
Resource bundle
\series default
in the
\series bold
Properties
\series default
panel.
\end_layout
\begin_layout Enumerate
Type the literal value:
\end_layout
\begin_deeper
\begin_layout LyX-Code
\family typewriter
text
\end_layout
\end_deeper
\begin_layout Enumerate
Click
\series bold
Tools
\begin_inset Quotes ald
\end_inset
Options
\series default
.
\end_layout
\begin_layout Enumerate
Click the
\series bold
Classpath
\series default
tab.
\end_layout
\begin_layout Enumerate
Click
\series bold
Add Folder
\series default
.
\end_layout
\begin_layout Enumerate
Browse to and select the
\series bold
texts
\series default
directory (see
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Example-Directory-Organization"
\end_inset
).
\end_layout
\begin_layout Enumerate
Click
\series bold
Open
\series default
to add the
\series bold
texts
\series default
directory to the Classpath.
\end_layout
\begin_layout Enumerate
Click
\series bold
OK
\series default
to close the
\series bold
Options
\series default
dialog.
\end_layout
\begin_layout Enumerate
Click
\series bold
Preview
\series default
.
\end_layout
\begin_layout Standard
The values from the resource bundle (that is,
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileproptext}
\end_layout
\end_inset
) now appear on the report in a user-friendly form.
\end_layout
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
uses a look-up method that tries various locale-based suffixes (where
\family typewriter
base
\family default
represents the resource bundle name---
\family typewriter
text
\family default
) for finding the translated report content (
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Internationalization-Look-up-Method"
\end_inset
).
\end_layout
\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename source/java/i18n.java.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:Internationalization-Look-up-Method"
\end_inset
Internationalization Look-up Method
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This allows you to create the following files (that contain the same keys
but different property values) to translate properties into various languages
and dialects:
\end_layout
\begin_layout Itemize
English
\end_layout
\begin_deeper
\begin_layout Itemize
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_en.properties}
\end_layout
\end_inset
(Default)
\end_layout
\begin_layout Itemize
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_en_CA.properties}
\end_layout
\end_inset
(Canada)
\end_layout
\begin_layout Itemize
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_en_US.properties}
\end_layout
\end_inset
(United States)
\end_layout
\begin_layout Itemize
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_en_UK.properties}
\end_layout
\end_inset
(United Kingdom)
\end_layout
\end_deeper
\begin_layout Itemize
French
\end_layout
\begin_deeper
\begin_layout Itemize
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_fr_CA}
\end_layout
\end_inset
(Canada)
\end_layout
\begin_layout Itemize
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_fr_FR}
\end_layout
\end_inset
(France)
\end_layout
\end_deeper
\begin_layout Standard
As the Australian English file (
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_en_AU.properties}
\end_layout
\end_inset
) is not available, the contents of
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileproptext}
\end_layout
\end_inset
would be used instead.
\end_layout
\begin_layout Subsection
\begin_inset CommandInset label
LatexCommand label
name "sub:JasperReports"
\end_inset
JasperReports
\end_layout
\begin_layout Standard
Depending on Java's executing environment, the technical details for configuring
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
to find the resource bundles can vary.
Rather than providing the instructions for every possible situation, a
single specific example (configuring the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appphpjavabridge{}
\end_layout
\end_inset
) is noted below.
\end_layout
\begin_layout Standard
Complete the following steps to configure the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appphpjavabridge{}
\end_layout
\end_inset
so
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
can load the resource bundles:
\end_layout
\begin_layout Enumerate
Create a Java archive containing all the texts.
\end_layout
\begin_deeper
\begin_layout Enumerate
Change to the directory containing the various texts.
\end_layout
\begin_layout Enumerate
Execute the following command to create a Java archive file containing all
the text files:
\end_layout
\begin_deeper
\begin_layout LyX-Code
\family typewriter
jar -cvf
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
filejarlanguage}
\end_layout
\end_inset
*
\end_layout
\end_deeper
\end_deeper
\begin_layout Enumerate
Copy
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
filejarlanguage}
\end_layout
\end_inset
into
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
windirprogbridgelib
\end_layout
\end_inset
.
\end_layout
\begin_layout Enumerate
Restart the Java application (for example, the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appphpjavabridge{}
\end_layout
\end_inset
b).
\end_layout
\begin_layout Enumerate
Browse to
\begin_inset CommandInset href
LatexCommand href
name "http://localhost/filter.html"
target "http://localhost/filter.html"
\end_inset
.
\end_layout
\begin_layout Enumerate
Click
\series bold
Report
\series default
.
\end_layout
\begin_layout Standard
If the PDF report fails to appear, check all the error logs shown in
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Windows-Applications-Logs"
\end_inset
(Windows) or
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Unix-Applications-Logs"
\end_inset
(Linux).
Resolve any errors and try again.
\end_layout
\begin_layout Section
Summary
\end_layout
\begin_layout Standard
Maintaining software is a chore few developers enjoy.
Far too often, the decisions that were made while developing the software
have left it inflexible, rigid, and brittle (that is, hard to change without
breaking other parts of the system).
For reports, inflexibility appears in three ways: first, by using the
\emph on
copy and paste
\emph default
technique instead of the
\emph on
master calls subreport
\emph default
technique to create new reports; second, by recreating variations on the
same SQL statement instead of implementing the query once, as a database
function, and calling it with different parameters; and third, by hard-coding
the same text strings over and over again.
All of these decisions would upset a violent, psychotic programmer.
Use resource bundles, avoid duplicating SQL code, and set up a master template.
Future developers will appreciate such thoughtfulness.
\end_layout
\end_body
\end_document