#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 true
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle true
\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
Report Assets
\end_layout
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
epigraph{Science is organized knowledge.
Wisdom is organized life.}{Immanuel Kant}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Report assets constitute all the external files required to execute a report.
Images, style sheets, resource bundles, fonts,
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjava{}
\end_layout
\end_inset
classes,
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjava{}
\end_layout
\end_inset
archive files, and subreports are all assets a given master report may
need to run successfully.
This chapter describes a way to organize report assets so that information
can be isolated to a single location, effectively eliminating many forms
of duplication.
It is helpful to create and use a source code repository
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
Use
\begin_inset CommandInset href
LatexCommand href
name "Git"
target "http://git-scm.com/"
\end_inset
or
\begin_inset CommandInset href
LatexCommand href
name "Subversion"
target "http://subversion.tigris.org/"
\end_inset
; avoid CVS and proprietary systems.
\end_layout
\end_inset
that mirrors the report development (or deployment) directory structure.
\end_layout
\begin_layout Standard
In this chapter:
\end_layout
\begin_layout Itemize
\series bold
Hierarchies.
\series default
How to arrange reports and their dependent, ancillary files.
\end_layout
\begin_layout Itemize
\series bold
Parameters.
\series default
Directory parameters and their relationships.
\end_layout
\begin_layout Itemize
\series bold
Organization.
\series default
How to organize the files and directories for subreports.
\end_layout
\begin_layout Itemize
\series bold
Styles.
\series default
Style template location.
\end_layout
\begin_layout Itemize
\series bold
Images.
\series default
Image location and a description on why names are so important.
\end_layout
\begin_layout Itemize
\series bold
Text.
\series default
Resource bundle location.
\end_layout
\begin_layout Section
Hierarchies
\end_layout
\begin_layout Standard
In
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Example-Directory-Organization"
\end_inset
is a directory hierarchy that provides a starting point for reusable reports.
The layout is a convenient convention enforced by neither
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appjasperreports{}
\end_layout
\end_inset
nor
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename drawings/directory-hierarchy.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:Example-Directory-Organization"
\end_inset
Recommended Directory Organization
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Master reports are placed in the
\family typewriter
ROOT_DIR
\family default
folder, because reports depend on files (either directly or indirectly)
in the directories below (fonts, images, styles, texts, and subreports).
\end_layout
\begin_layout Section
Parameters
\end_layout
\begin_layout Standard
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Report-Parameter-Values"
\end_inset
shows the parameter values that can mirror the directory structure in
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Example-Directory-Organization"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Report-Parameter-Values"
\end_inset
Report Parameter Values
\end_layout
\end_inset
\begin_inset Tabular
<lyxtabular version="3" rows="6" columns="2">
<features>
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
rowcolor{tableheader}
\backslash
toprule{}
\end_layout
\end_inset
\series bold
Parameter
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Exact Value
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
midrule{}
\end_layout
\end_inset
ROOT_DIR
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
"/reports/"
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
IMAGE_DIR
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
$P{ROOT_DIR} + "images/"
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
STYLE_DIR
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
$P{ROOT_DIR} + "styles/"
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
SUBREPORT_DIR
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
$P{ROOT_DIR} + "subreports/"
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
COMMON_DIR
\end_layout
\end_inset
</cell>
<cell alignment="center" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
$P{SUBREPORT_DIR} + "common/"
\family default
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
tabularnewline
\backslash
bottomrule%
\end_layout
\end_inset
\end_layout
\end_inset
</cell>
</row>
</lyxtabular>
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The order of parameters (and variables) is important: add them to the
\series bold
Report Inspector
\series default
according to their dependencies.
For example, since
\family typewriter
ROOT_DIR
\family default
does not depend on other values, it gets declared first.
In contrast,
\family typewriter
COMMON_DIR
\family default
is assigned a value using the
\family typewriter
SUBREPORT_DIR
\family default
, and
\family typewriter
SUBREPORT_DIR
\family default
is
\family typewriter
ROOT_DIR
\family default
concatenated with the directory name for subreports.
Therefore, the
\series bold
Report Inspector
\series default
must list the
\family typewriter
COMMON_DIR
\family default
variable last.
\end_layout
\begin_layout Standard
Note that the exact value for
\family typewriter
ROOT_DIR
\family default
contains the full path to the location of the other directories.
Avoid including operating-specific references.
For example, a value of
\family typewriter
"C:
\backslash
\backslash
reports
\backslash
\backslash
"
\family default
is not as portable as
\family typewriter
"/reports/"
\family default
; whereas, the latter works on both Linux- and Windows-based operating systems,
in fewer keystrokes, too.
\end_layout
\begin_layout Standard
An application of this hierarchical organization is explored in
\begin_inset CommandInset ref
LatexCommand vref
reference "cha:Subreports"
\end_inset
.
\end_layout
\begin_layout Section
Organization
\end_layout
\begin_layout Standard
The subreports directory must contain a directory for every report that
uses subreports.
Any common templates, that are meant to be re-used (such as a shared page
or report header), must exist in a suitably named subdirectory.
\end_layout
\begin_layout Standard
For example, imagine
\family typewriter
city.jasper
\family default
includes the following subreports:
\end_layout
\begin_layout Itemize
\family typewriter
demographics.jasper
\end_layout
\begin_layout Itemize
\family typewriter
climate.jasper
\end_layout
\begin_layout Itemize
\family typewriter
header.jasper
\end_layout
\begin_layout Standard
Additionally, suppose that
\family typewriter
header.jasper
\family default
was also a subreport used by other reports.
The relationship between these files could be made explicit by organizing
them as:
\end_layout
\begin_layout LyX-Code
\family typewriter
/reports/city.jasper
\end_layout
\begin_layout LyX-Code
\family typewriter
/reports/subreports/city/demographics.jasper
\end_layout
\begin_layout LyX-Code
\family typewriter
/reports/subreports/city/climate.jasper
\end_layout
\begin_layout LyX-Code
\family typewriter
/reports/subreports/common/header.jasper
\end_layout
\begin_layout Standard
As long as the sub-components for a report are clearly organized, there
will be little duplicated effort.
\end_layout
\begin_layout Standard
What you name the directory for common templates is unimportant.
Use your judgement as to what your coworkers would most readily recognize
as being the shared location.
Typical names include
\emph on
common
\emph default
,
\emph on
shared
\emph default
, and
\emph on
core
\emph default
.
\end_layout
\begin_layout Section
Styles
\end_layout
\begin_layout Standard
The styles directory contains style template files, which can be identified
by their
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
fileextjrtx}
\end_layout
\end_inset
extension.
\end_layout
\begin_layout Standard
Only put style template files that are actually used by reports in the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
path{styles}
\end_layout
\end_inset
directory.
For information on creating and using style templates, see
\begin_inset CommandInset ref
LatexCommand ref
reference "cha:Style"
\end_inset
.
\end_layout
\begin_layout Section
Images
\end_layout
\begin_layout Standard
Not all reports need or even warrant images.
In the cases where images are embedded into reports, keep the images in
their own directory.
Also, use a consistent naming scheme for the image files that relates,
in some way, to the data.
\end_layout
\begin_layout Standard
Consider the situation where a city's representative photograph must be
included on each report.
The image file names might be derived from the name of the city with the
appropriate file name extension appended (such as
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{abord-a-plouffe.png}
\end_layout
\end_inset
) and spaces replaced with hyphens (or underscores).
In this case, the hierarchy can be refined by adding directories for countries
and regions (state or province) to avoid duplication in file names.
\end_layout
\begin_layout Standard
Another way to name the images is by using a primary key.
The disadvantage of using a primary key is that the file's name becomes
obfuscated, you must either run a database query to find a particular image,
or open the image, and even then you would probably need to know how each
city appears to identify it (presuming the images do not have a city label).
An advantage to using a numeric primary key is that it avoids including
internationalized text in file names, which, without due care, can lead
to problems.
\end_layout
\begin_layout Section
Text
\end_layout
\begin_layout Standard
The text directory contains resource bundles filled with text that is shared
between reports.
At the start of the project, this directory might contain a single file:
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{
\backslash
filepropcommon}
\end_layout
\end_inset
.
The file would then contain English text used by different reports.
\end_layout
\begin_layout Standard
How resource bundles (also known as properties files) are configured varies
from system to system.
Configuring
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
is less involved than configuring the
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appphpjavabridge{}
\end_layout
\end_inset
, which may be more or less complicated than configuring the resource bundles
in conjunction with
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appapachetomcat{}
\end_layout
\end_inset
and JavaServer Pages.
\end_layout
\begin_layout Standard
For more configuration information, see
\begin_inset CommandInset ref
LatexCommand vref
reference "sec:Resource-Bundles-Configuration"
\end_inset
.
\end_layout
\begin_layout Section
Summary
\end_layout
\begin_layout Standard
Returning to Ray Ozzie's quote (from the previous chapter) on complexity,
defining a directory hierarchy migrates the system toward simplicity.
As the number of reports developed for a company increases, so too will
the need to find and maintain the reports.
Leaving all reports, subreports, and report assets in a single directory
will result in wasting time merely trying to open the correct report to
update.
It would be wise, therefore, to organize the information sooner rather
than later, as per Immanuel Kant's advice.
\end_layout
\end_body
\end_document