| |
 |  |  |
 | How to use this documentation |  |
 |
Ejen documentation consists in this page and
Javadoc API pages that give detailled instructions about how to use the
Ejen Ant Task as well as
standard extensions,
Java parser extension and
database
extensions. You may also use, of course, the
Xalan Extensions
Library (but keep in mind that only extensions available in the
Xalan-j_2_2_D13 distribution are accessible).
|  |
 | Ejen task |  |
 |
Ejen is implemended for now as an Ant task. However, because it is not
integrated to built-in or optional tasks distributed with Ant, you must define
the task prior to use it:
build.xml |
---|
<?xml version="1.0" encoding="UTF-8"?>
<project name="build" default="build">
<taskdef name="ejen" classname="org.ejen.EjenTask"/>
<target name="build">
<ejen>
...
</ejen>
</target>
</project>
|
Here, "taskdef" node defines the org.ejen.EjenTask class as an ant
task that will be used between <ejen>...</ejen> nodes
in the build file. You may have a look at the
Ejen Ant Task API documentation.
|  |
 | Ejen task child nodes |  |
 |
There are five primitive actions (or "nodes") in the Ejen system (children
of an <ejen>...</ejen> section):
-
source: this node allows
the loading of an XML file, replacing any current (in memory) DOM tree
used in the generation process.
-
merge: this node allows
the loading of an XML file, that will be merged into the current (in
memory) DOM tree used in the generation process.
-
save: this node allows
the saving of the current (in memory) DOM tree used in the generation
process.
-
filter: this node allows
the transformation (enrichment) of the current (in memory) DOM tree used
in the generation process (via an XSL stylesheet).
-
template: this node allows
the creation of resulting text files, using the current (in memory) DOM tree
(via an XSL stylesheet).
In addition, three sub-actions (or "sub-nodes") are available:
-
include: this node allows
the loading of an XSL file as an include for a filter or template node (and,
optionally, for an import of even include node).
-
import: this node allows
the loading of an XSL file as an import for a filter or template node (and,
optionally, for an include of even import node).
-
param: this node allows
the setting of a XSL stylesheet parameter (filter, template, include or import).
Each of those nodes may be invoked (several times if necessary) in an Ejen generation
process, by the mean of the Ejen Ant Task.
Basically (but this is only a very simple and typical setup), if you use Ejen as a code
generation framework, you will have to define an initial XML source (that contains
minimal data required for the generation), possibly a filter XSL stylesheet to transform
(or enrich) the initial data and a template XSL stylesheet to produce the results of the
generation.
|  |
 | Extensions |  |
 |
Beside this Ant task system, Ejen comes with a bunch of extensions that may be
used in XSL stylesheets (filter/template/include/import). Those extensions
constitute a library of classes that makes easier code generation. There are for now
three kind of extensions:
-
Standard extensions:
you may use them, for example, for text formatting, Java compiled classes
exploration, XML files includes or extended XSL variables management
purposes.
-
Java parser extension: you may use this extension in order to get
a DOM tree representation of a Java source file.
-
Database extension: you may use this extension in order to get
a DOM tree representation of database (table) metadata.
Other extensions will be added in future, especially other text parser classes
(using the JavaCC compiler compiler). As a matter of fact, limitations of Ejen
does not come from output problems: you are absolutly free to generate any kind of
text files (letters, Java, C, C++ or even ADA source files...). The true problem comes
with the input question: Ejen only allows access to DOM tree data so, if you want to
use a source of data which is not natively XML based, you must convert it to a DOM
tree representation. This is already available for Java source files (via the
Java parser
extension). But you may need other text file parsers as well, and the Java parser
extension may serve as an example of the use of JavaCC based parsers, modified in order
to get a DOM tree representation usable in the Ejen process.
|  |
 | A very basic example |  |
 |
Suppose you want to generate several letters with the same content (except the name
of the person to whom the letter will be send). This example is available in
the
ejen-demos-***.zip archive.
First, we need obviously a source XML file with all person names:
persons.xml |
---|
<?xml version="1.0" encoding="iso-8859-1"?>
<persons>
<name>John Smith</name>
<name>Bonnie Parker</name>
<name>Clide Barrow</name>
...
</persons>
|
Then, because we don't need any filter in this very basic example, we simply
write the following template:
letter.xsl |
---|
<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:output method="text" encoding="iso-8859-1"/>
<xsl:template match="name">
Dear <xsl:value-of select="."/>,
Obviously, you are reading a meaningless letter.
Best regards.
</xsl:template>
</xsl:stylesheet>
|
Finally, we set up the Ant build file generation process:
generate.xml |
---|
<?xml version="1.0" encoding="UTF-8"?>
<project name="basic-project" default="basic-target">
<taskdef name="ejen" classname="org.ejen.EjenTask"/>
<target name="basic-target">
<ejen>
<source file="persons.xml"/>
<template file="letter.xsl"
foreach="persons/name"
filepattern="{.}.txt"/>
</ejen>
</target>
</project>
|
If we run this example, we will get text files named "John Smith.txt",
"Bonnie Parker.txt", "Clide Barrow.txt", ... For example, the
"John Smith.txt" file will look like:
John Smith.txt |
---|
Dear John Smith,
Obviously, you are reading a meaningless letter.
Best regards.
|
This example only shows one feature of Ejen: you can apply a template node not
only to the entire DOM tree in memory (loaded by the "source" node), but also,
by iteration, to a set of sub-nodes of this tree. The "foreach" attribute above
means: apply the template, by iteration, to the set of all "name" nodes (children
of the "persons" node). The "filepattern" attribute, which is relative to the
"foreach" attribute, means: for each "name" selected by the "foreach" attribute,
save the result of the transformation to a file named
"<value of the name node>.txt". Using the
Xalan SQL
extension you could as well get those names from a database (no "source"
node is required this way, only a "filter" that calls the extension in order
to build a DOM tree with the same structure).
|  |
 | Other examples |  |
 |
Other examples are available in the downloadable
ejen-demos-***.zip archive: the EJB 1.1 demonstration, an example
of automated implementation wizard (that creates a basic, but compilable, implementation
of a child class of any abstract class or interface), an example of Java source to
highlighted HTML conversion (see
Generated EJB 1.1 sources), as well as some tutorial
examples.
|  |
 | Ejen sources compilation |  |
 |
Requirements:
-
You must install the
ejen-bin-***.zip archive. It seems strange
to need the binaries in order to compile the sources... But you
must do it, because the sources compilation needs jar archives that only comes
with the binaries distribution.
-
You must also install the
JavaCC program (version 2.1
or newer) and you must edit the
build.xml file and set the
javacc-home property:
<project name="install" default="all">
<target name="init">
...
<property name="javacc-home" value="/usr/java/javacc2.1/bin/lib"/>
...
</target>
...
</project>
|
If you fill the above requirements, you may compile the Ejen sources by the
mean of the ./build (Unix) or build.bat (Windows)
command (in the ejen-*** directory)
|  |
 |  |  |
|