Running XmlTransform
To run XmlTransform, you need to load a few components:
- Load Java (version 1.5 or later). You need only the Java run-time engine, which you probably already have. If not, download it from Sun.
- Load the Xerces library for XML parsing.
- Load the Xalan library for XSLT transformations.
- Load the cleancode-java open source library.
- Add the following JAR files to your Java classpath: the CleanCode library (cleancode.jar), the Xerces library (xml-apis.jar and xercesImpl.jar), and the Xalan library (serializer.jar and xalan.jar).
To test the installation, invoke the usage message option:
> java com.cleancode.xml.XmlTransform --help
That command displays the complete list of command-line options available, with a one-line description of each.
Because there are a large number of options, XmlTransform allows you to put all your options in a
parameter file and reference that file from the command line by preceding the file name with an "at sign" (@) prefix, as in:
> java com.cleancode.xml.XmlTransform @myParams.dat
XmlTransform treats options in a parameter file just as if you had typed them on the command line, except that they are not exposed to shell interpolation. This can avoid conflicts with special characters that your shell may want to process first (quotes, redirection, etc.) if they are provided directly on the command line. A second benefit to a parameter file is that you may use it to create a default set of options and then override or augment that set on the command line with either direct options or with another parameter file.
As an example, suppose you have a parameter file called
inline.conf containing these three parameters (for simplicity the example options below are not real option names):
--x1=2
--x2=4.3
--x3=true
You could then specify options on the command line as:
> java class_name --x1=4 @inline.conf --x4=0.5
The parameter file is interpolated just as if you had written:
> java class_name --x1=4 --x1=2 --x2=4.3 --x3=true --x4=0.5
You can see the
x1 option is effectively given twice; the
last one encountered is the one that gets used, so the value of
x1 will be two rather than four. An important point to note, then, is that if you wish to use a default set of options from a file and override them on the command line as needed, the parameter file specification must
precede all the direct options on the line (unlike in the contrived example above where it is in the middle).
Yet another variation of this is simply to create a default set of options in one parameter file and a few customized options in another.
> java class_name @default.dat @variation-one.dat
Option Summary
Below is the list of all the available options for XmlTransform. The following steps describe the details of these XmlTransform options in logical groupings. Also see the
XmlTransform API for further details.
contentsBaseName -- base name for contents file (e.g. 'index')
contentsToParent -- boolean indicating to place contents
in parent or same dir
debug -- enable all diags if true (including
libraries)
diagList -- string of single-character diags to activate
dirList -- comma-separated list of dirs to process
enable -- do processing if true; just report if false
generateContents -- boolean switch to generate contents
generatorNode -- tag name of node to replace with
generator info
groupIdXpath -- simple Xpath pointing to group id
node in each file
groupPlaceHolder -- tag name in contents file to put file list
help -- show this list
inExtension -- extensions of files to process
inputSchemaSource -- global Schema file for input validation
outExtension -- extensions for translated files
outputSchemaSource -- global Schema file for output validation
processAll -- process without checking date stamps if true
sourcePath -- root of source XML tree
startDepth -- number of directories from the top of
your tree back to your own relative root
targetPath -- root of target XML tree
validateInputToSchema -- boolean switch to validate input
validateOutputToSchema -- boolean switch to validate output
validateXslBySchema -- boolean switch to validate needed XSL files
xslName -- primary XSL file in each directory
xslParmList -- comma-separated list of XSL parameters
xslSchema -- name of Schema file for XSL files
xslTransform -- boolean switch to do XSL translation
These remaining options are available in XmlTransform but are not specific to this application. Any application that uses the CleanCode diagnostic system would have these same options. Complete details of the Diagnostic API are available
here.
.*_DIAG -- diagnostic level for any class
CREATE_DIAG -- diagnostic level for object creations
DIAG_LEVEL -- diagnostic mask
ENV_DIAG -- diagnostic level for system environment
FORMATTER -- class name for web channel formatting
LOG_DIAG_NAME -- base file name for regular messages
LOG_DIR -- directory in which to create log files
LOG_ERR_NAME -- base file name for warning/error messages
OUTPUT_DIAG -- output channels for regular messages
OUTPUT_ERR -- output channels for warning/error messages
SHOW_THREAD -- show/hide switch for thread information
TRACE_DIAG -- diagnostic level for method enter/exit
TRACE_INDENT -- indentation string for nested output
VERSION_DIAG -- diagnostic level for module versioning
WARNINGS_ON -- show/hide switch for warning messages
Listing 2 illustrates a complete parameter file from a sample project. The steps on the next page explain in further detail how to determine the appropriate values.