org.xrn.ant
Class XMLReleaseNotes

java.lang.Object
  |
  +--org.apache.tools.ant.ProjectComponent
        |
        +--org.apache.tools.ant.Task
              |
              +--org.xrn.ant.XMLReleaseNotes

public class XMLReleaseNotes

extends org.apache.tools.ant.Task

This task enables to use the XMLReleaseNotes framework via Ant.

If you need to use the XRN task, this is place of reference that exhaustively shows all features.

Version

This manual has been generated from the source code of XRN V@XRN_VERSION@. This documentation is extracted from the source code, hence it should be up-to-date.

This manual just explains the Ant XRN task, but is not a documentation on the XRN framework. You will find such a documentation on the official web site of the XRN framework at http://xmlreleasenotes.free.fr.

A wrapper above XRN

The XMLReleaseNotes framework can also be used from the Ant world, thanks to this tiny wrapper task.

Declare the task

In order to use the Ant plug-in task, declare it via the

 <taskdef
   classname="org.xrn.ant.XMLReleaseNotes"
   name="XMLReleaseNotes"
 />
 

snippet. Later on, you will use the XMLReleaseNotes task.

Runtime requirements

There is a place where you will find this information back: XRN release notes, so you'd better to refer to them, in order to have fresh information. The "requirements" section of the XRN version that you are currently using should be self explanatory.

However, here are roughly the components you need at runtime in order it to work properly (at least by version 0.17.2 of the framework).

• Ant V1.5.0+: older versions will not work because the XMLCatalog class is used.
• It is required that the Ant lib directory contains an XSLT implementation library (like Xalan or Saxon, for instance) of the javax.xml.transform.TransformerFactory Java interface.

The two-phases

This task processes two steps:

1. the enrichment operated on the XML XRN file via optional XSL transformations,
2. the rendering of the resulting XML into HTML.

The detailed description of this feature is beyond this manual. However, let's see to what elements these two phases correspond to.

Enrichment

This first step is optional, and is handled by the inner model XML elements. You can define as many transformers that you want to.

Rendering

Two different types of rendering

The HTML renders pages can be generated by using two distinct modes, either compact or expanded.

Compact rendering

In that mode, only one HTML file is rendered per component release notes. This is a compact mode.

Expanded rendering

This mode renders the release notes in a very likely Javadoc way. This involves that a HTML page is rendered for every release of each component.

This feature is activated as soon as more one XRN file is provided to the task, or when the singlePage is disabled.

HTML supported

Some attributes or elements of the task support textual information mixed with HTML tags. Every time this is the case, the end-user is directed here.

XSLT resource

Some inner XML elements of the XRN task enable to refer to a XSLT style sheet file. When this is the case, you have the choice to use:

• either xsl: this specifies the path of this stylesheet file,
• or plugin: this specifies the name of the XSLT plug-in to be used, present in the XRN jar, under XMLReleaseNotes/plugin hierarchy. When you use it, provide the name of the plug-in XSLT file, without the file extension. For example, if you intend to use the version and type filter that is performed through the XMLReleaseNotes/plugin/VersionAndTypeFilterModel.xsl, set this attribute to VersionAndTypeFilterModel.

The attribute defined first takes precedence over the second one, in case when you define both.

Important

Here are some miscellaneous important matters.

XMLCatalog feature

This is a rather advanced feature, so, unless you use XSLT plug-in feature, you do not need to care about it.

This feature is used via in the following locations within the task:

• model,
• layout,
• pluginLayout.

Said shortly, the XMLCatalog nested XML element acts like a URI resolver, which is very handy when it comes to the numerous XSLT that occur at runtime.

In the previous XML blocks, you can add a single XMLCatalog inner XML element, so as to tell the XSLT transformations where to find resources according to their public ID. In that case, insert the following block:

 <xmlcatalog>
     <entity
       publicId="SomePublicID"
       location="its_actual_URI"
     />
    ...
 </xmlcatalog>
 

Use as many entity as you need.

This XMLCatalog feature has been developed in the Ant framework. This feature is also used in the Xslt/Style: do not hesitate to take a look in the previous hyperlinks, in order to understand its purpose and how it works. Moreover, there are lots of examples of usage there.

Mail feature

This task is also the official Ant Mail task, so that you can send eventually the release notes by mail. If the mail parameter is set to yes, then the generated release notes will be sent as text/html: define the traditional Ant Mail parameters, except the message, messagefile, messagemimetype, files and includefilenames.

The mail sent will contain the abstract as subject, and the content of the mail will be the generated release notes.

Example

 <XMLReleaseNotes
   xml="ReleaseNotes.xml"
 />
 

will render the HTML for the XML release notes file ReleaseNotes.xml.

Since:

V0.3.2, 2004.04.01. Shift in the org.xrn.ant package from V0.18.0.

Version:

@XRN_VERSION@

Author:

Edouard Mercier

Inner Class Summary

class	XMLReleaseNotes.HTML A class that enables to express HTML code.
class	XMLReleaseNotes.XSLT A class that enables to express an XSL transformation.

Fields inherited from class org.apache.tools.ant.Task

description, location, target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

project

Constructor Summary

XMLReleaseNotes()

Method Summary

java.lang.Object	createFileSet() As many occurrences of this element are allowed. Enables to define multiple XRN release notes files at the same time.
java.lang.Object	createFooter() Only one occurrence of this element is allowed. This element is ignored if the expanded-rendering feature is not enabled.
java.lang.Object	createHeader() Only one occurrence of this element is allowed. This element is ignored if the expanded-rendering feature is not enabled.
java.lang.Object	createLayout() Only one occurrence of this element is allowed. Defines the XSL transformation that renders into HTML the XML release notes input.
java.lang.Object	createMail() Only one occurrence of this element is allowed. Enables to send an e-mail at the end of the XSL layout final transformation.
java.lang.Object	createModel() As many occurrences of this element are allowed. Defines a additional XSL transformations to be applied on the XML input.
java.lang.Object	createPluginLayout() Only one occurrence of this element is allowed. This element is ignored if the expanded-rendering feature is not enabled.
java.lang.Object	createTitle() Only one occurrence of this element is allowed. This element is ignored if the expanded-rendering feature is not enabled.
java.lang.Object	createURIResolverPath() This feature is only relevant when the XRN task jar file(s) lives outside from the Ant lib directory, and thus that you declared it via the typedef/taskdef task, with a properly defined classpath.
java.lang.Object	createXSLTPath() This feature is only relevant when the XSLT implementation lives outside from the Ant lib directory.
void	execute()
java.lang.String	getXRNVersion()
protected void	logRuntimeInformation() Logs the current runtime environment, so that it is possible to debug more easily the task, especially as far as XSLT is concerned.
void	setAbstract(java.lang.String abstract_string) Enables to define an abstract for the generated main HTML page, that will be displayed at the top of the release notes.
void	setBanner(java.lang.Boolean show_banner) Tells whether the generated HTML pages should present an advertising footer banner for the XRN framework.
void	setCheckValidity(java.lang.Boolean check_validity) Indicates whether the XML input release notes should be tested against its XML schema.
void	setCSS(java.io.File css_file) Defines the path of the CSS file to be used within the generated HTML pages.
void	setDebug(java.lang.Boolean debug) For internal purpose only.
void	setDeploy(java.lang.Boolean deploy) A boolean attribute that indicates whether the task just needs to deploy the XRN main resources: for instance, the default CSS style sheet will be copied, as well as the XRN XMLReleaseNotes.xsd schema file.
void	setDestination(java.io.File destination_directory) Defines the path of the directory where all generated stuff will be generated into.
void	setHTML(java.lang.String html_release_notes_file_name) Defines the name (and not the path!
void	setImplicitlyMigrate(java.lang.Boolean implicit_migration) Indicates whether implicit XRN migration should be applied if necessary.
void	setInlineCSS(java.lang.Boolean inline_css) Tells whether the generated HTML pages should inline the CSS content or not.
void	setMigrate(java.lang.Boolean migrate) Indicates that you want to perform a migration of the XRN input release notes files from their declared XRN framework version into the current XRN version.
void	setProcessor(java.lang.String xslt_transformer_factory_class_name) Defines the Fully Qualified Name (FQN) of the XLST TransformerFactory class that will be used for all transformations.
void	setSinglePage(java.lang.Boolean single_page) This attribute only makes sense when the inner fileset element is not used.
void	setUseIcons(java.lang.Boolean use_icons) This feature is still at its early stages and is still experimental.
void	setXML(java.io.File xml_release_notes_file) Defines the XRN-compliant file that describes the component release notes.

Methods inherited from class org.apache.tools.ant.Task

getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorOutput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, setProject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLReleaseNotes

public XMLReleaseNotes()

Method Detail

setXML

public void setXML(java.io.File xml_release_notes_file)

Defines the XRN-compliant file that describes the component release notes.

All operations will be performed on that release notes file.

See the fileset inner element.

setProcessor

public void setProcessor(java.lang.String xslt_transformer_factory_class_name)

Defines the Fully Qualified Name (FQN) of the XLST TransformerFactory class that will be used for all transformations.

This will set the Java system property javax.xml.transform.TransformerFactory with the implementation of interface javax.xml.transform.TransformerFactory.

createFileSet

public java.lang.Object createFileSet()

As many occurrences of this element are allowed. Enables to define multiple XRN release notes files at the same time. In that case, the task will handle all the release notes files declared hereby. It is supposed that all provided files are XRN-compliant release notes file. If one is not, the task will fail.

When defined, the xml attribute is not taken into account.

This XML element is the Ant fileset feature. This same element is being used in the Ant copy task.

Read this section for additional information.

createXSLTPath

public java.lang.Object createXSLTPath()

This feature is only relevant when the XSLT implementation lives outside from the Ant lib directory.

Indicates to Ant where the XSLT implementation jar file(s) required at runtime are located.

createURIResolverPath

public java.lang.Object createURIResolverPath()

This feature is only relevant when the XRN task jar file(s) lives outside from the Ant lib directory, and thus that you declared it via the typedef/taskdef task, with a properly defined classpath.

Indicates to Ant where the internal resources (.xsl, for the most) that are required at runtime are located. Those resources are present in the XRN Ant task jar file, so you only need to refer to this file.

Example:

 <URIResolverPath>
   <pathelement location="<the path to>/XMLReleaseNotes.jar"/>
 </URIResolverPath>
 

setDestination

public void setDestination(java.io.File destination_directory)

Defines the path of the directory where all generated stuff will be generated into.

setHTML

public void setHTML(java.lang.String html_release_notes_file_name)

Defines the name (and not the path!) of the main rendered HTML page.

This is the HTML page to be opened in order to browse the rendered HTML release notes.

This attribute is ignored if the expanded-rendering feature is disabled.

setSinglePage

public void setSinglePage(java.lang.Boolean single_page)

This attribute only makes sense when the inner fileset element is not used.

Tells whether a single HTML page or multiple HTML pages should be generated for the component release notes.

This is handy when you want your rendered release notes to be encompassed in a single HTML file.

Read this section for additional information.

setUseIcons

public void setUseIcons(java.lang.Boolean use_icons)

This feature is still at its early stages and is still experimental.

Indicates whether the generated HTML pages should contains icons or not.

setCSS

public void setCSS(java.io.File css_file)

Defines the path of the CSS file to be used within the generated HTML pages. This offers the opportunity to customize the rendered release notes layout. Copy and paste the default CSS, then modify its CSS selectors in order to customize the HTML rendering.

This file will be copied at the root of the destination directory with the name stylesheet.css.

This CSS must conform to the default CSS style sheet format.

setInlineCSS

public void setInlineCSS(java.lang.Boolean inline_css)

Tells whether the generated HTML pages should inline the CSS content or not.

When enabled, the CSS will be embedded in the generated HTML, so that HTML the release notes is stand-alone (the CSS style sheet will not be copied in the destination directory). This is especially handy when you do not want to make a reference to another file inside the generated HTML.

setAbstract

public void setAbstract(java.lang.String abstract_string)

Enables to define an abstract for the generated main HTML page, that will be displayed at the top of the release notes.

This is an opportunity to provide some overall explanation about the release notes themselves.

This element supports HTML tags.

setCheckValidity

public void setCheckValidity(java.lang.Boolean check_validity)

Indicates whether the XML input release notes should be tested against its XML schema.

This enables to check that your XRN release notes are compliant with the framework (and all the more that the file is well formed).

setBanner

public void setBanner(java.lang.Boolean show_banner)

Tells whether the generated HTML pages should present an advertising footer banner for the XRN framework.

If you want to promote the framework, you should consider letting this on.

createTitle

public java.lang.Object createTitle()

Only one occurrence of this element is allowed.

This element is ignored if the expanded-rendering feature is not enabled.

This title will be used on the HTML first page (the one that displays all components).

It enables to display extra personal information about the generated documentation.

This element supports HTML tags.

createHeader

public java.lang.Object createHeader()

Only one occurrence of this element is allowed.

This element is ignored if the expanded-rendering feature is not enabled.

This header will be displayed on multi-components HTML pages.

This element supports HTML tags.

createFooter

public java.lang.Object createFooter()

Only one occurrence of this element is allowed.

This element is ignored if the expanded-rendering feature is not enabled.

This footer will be displayed on multi-components HTML pages.

This element supports HTML tags.

setDeploy

public void setDeploy(java.lang.Boolean deploy)

A boolean attribute that indicates whether the task just needs to deploy the XRN main resources: for instance, the default CSS style sheet will be copied, as well as the XRN XMLReleaseNotes.xsd schema file.

This is a helper that extracts all the necessary resources from the jar file. The deployed resources will be copied into the destination directory.

When enabled, no other processing than deploying the XRN framework main resources will be performed.

createModel

public java.lang.Object createModel()

As many occurrences of this element are allowed. Defines a additional XSL transformations to be applied on the XML input. The result of the transformation should be some XRN-compliant XML file. The XSL transformations will be applied in the same order as they are declared, from top to bottom.

Read this explanation in order to understand how to express the XSLT that should be used.

This enables to provide multiple XSLT that aggregate information coming from another XML sources. This is part of the enrichment step.

If not defined, no preliminary XSL transformation is performed on the XML input release notes files; the layout parameter is also ignored in this case.

This element supports the XMLCatalog inner XML element, that acts as a URI resolver. Follow the previous link in order to understand what this is about.

createLayout

public java.lang.Object createLayout()

Only one occurrence of this element is allowed. Defines the XSL transformation that renders into HTML the XML release notes input.

The idea is to provide an XSLT that extends the XMLReleaseNotes2HTML.xsl default rendering so as to take into account the new model information present in the input XML. This XSL will be given the same parameters as the default ones. This is part of the layout step.

Read this explanation in order to understand how to express the XSLT that should be used.

If not defined, the usual XSL transformation renderer is used.

This element supports the XMLCatalog inner XML element, that acts as a URI resolver. Follow the previous link in order to understand what this is about.

createPluginLayout

public java.lang.Object createPluginLayout()

Only one occurrence of this element is allowed.

This element is ignored if the expanded-rendering feature is not enabled.

Defines the XSLT layout plugin that should be used when it comes to the rendering into HTML.

The idea is to provide an XSLT that extends the XRN2HTMLPlugin.xsl default rendering.

Read this explanation in order to understand how to express the XSLT that should be used.

This XSL will be given the same parameters as the default ones.

This element supports the XMLCatalog inner XML element, that acts as a URI resolver. Follow the previous link in order to understand what this is about.

createMail

public java.lang.Object createMail()

Only one occurrence of this element is allowed. Enables to send an e-mail at the end of the XSL layout final transformation.

If not defined, no e-mail will be sent. Otherwise, use this usual mail built-in Ant task in order to define the e-mail inputs.

Read this some more explanation.

setMigrate

public void setMigrate(java.lang.Boolean migrate)

Indicates that you want to perform a migration of the XRN input release notes files from their declared XRN framework version into the current XRN version. In that case, the release notes files must be writable, since they may be overwritten.

For every XRN release note file concerned, the task will attempt to perform the necessary migration from the version of the XRN declared via the ReleaseNotes/@version attribute, into the version of the present XRN task.

When enabled, the rest of the standard processing is not performed.

setImplicitlyMigrate

public void setImplicitlyMigrate(java.lang.Boolean implicit_migration)

Indicates whether implicit XRN migration should be applied if necessary. This does not stop the process once the implicit migration has been applied.

When your XRN release notes files are outdated compared to the XRN version of the Ant XRN task that you are currently using, you can ask the task to first migrate (via the integrated migration feature) your release notes, and then only, continue the standard process.

setDebug

public void setDebug(java.lang.Boolean debug)

For internal purpose only. Triggers the debug behavior.

This feature is not supposed to be used by persons not developing for the XRN framework, unless explicetly asked for.

getXRNVersion

public java.lang.String getXRNVersion()

Returns:

the XRN version this element belongs to

execute

public void execute()
             throws org.apache.tools.ant.BuildException

Overrides:

execute in class org.apache.tools.ant.Task

logRuntimeInformation

protected void logRuntimeInformation()

Logs the current runtime environment, so that it is possible to debug more easily the task, especially as far as XSLT is concerned.