Ejen Logo
 
 Project
                         
News
Download
Developer site
Browse CVS
License (GPL)
 
 Documentation
                         
Introduction
Requirements
Installation
Ejen doc
Ejen API
EJB 1.1 demo
EJB 1.1 doc
 
 Links
                         
Xerces-j
Xalan-j
Ant
JavaCC
JBoss
 
 Contact
                         
Author
 
   
 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):

  1. source: this node allows the loading of an XML file, replacing any current (in memory) DOM tree used in the generation process.

  2. 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.

  3. save: this node allows the saving of the current (in memory) DOM tree used in the generation process.

  4. filter: this node allows the transformation (enrichment) of the current (in memory) DOM tree used in the generation process (via an XSL stylesheet).

  5. 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:

  1. 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).

  2. 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).

  3. 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:
  1. Standard extensions: you may use them, for example, for text formatting, Java compiled classes exploration, XML files includes or extended XSL variables management purposes.

  2. Java parser extension: you may use this extension in order to get a DOM tree representation of a Java source file.

  3. 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)


 

SourceForge.net Logo