ApiLinksTF

Insert links to Javadoc documentation in an HTML file.

Task package:org.schmant.task.base
Java package:org.schmant.task.text.apilinks
Category:HTML tasks
Since:0.8
EntityFS-aware?Yes*
Implements:ActionTaskFactory
GeneratorTaskFactory
ProcessTaskFactory
Produces:The interpreted target property. The exact type depends on the type used for the target.

Description:

This task replaces fully qualified class names with links to Javadoc documentation. The task uses a list of ApiLink objects containing a Java package name and a URL (the apiLinks property). Fully qualified class names that match any of the packages or any of their subpackages are replaced with a Javadoc link created from the URL for the package. The class name may be followed by a hash (#) and then a method or a constant name, in which case the link will be to the referenced method or constant.

The task can also replace explicit API links to classes or packages. An explicit class link has the format:

  |api:class:fully qualified class name[?key1=value1, key2=value2, ...]|
An explicit package link has the format:
  |api:package-summary:package name[?key1=value1, key2=value2, ...]|
The optional set of key=value properties is used to control attributes of the created links. The following keys are recognized:
linkClass
The created links' class attributes. This overrides any value set in the linkClass property.
title
The created links' title attributes. If this is not set, the titles will be set to the fully qualified class or package names.
displayText
The created links' display text. If this is not set, the display texts will be the fully qualified package or class names.

To preserve a fully qualified class name in the HTML page, prefix it with dr. (Don't Replace). The dr. prefix is removed by the task, but the fully qualified class name is preserved.

Required properties

Properties

apiLinks (required)top

A list of ApiLink objects.

The package name of the API links objects should end with a dot so that packages with similar names are not accidentally included. For instance, the package name org.foo.bar will also include packages under org.foo.barbequeue. org.foo.bar. will not.

Setter method:
addApiLink(ApiLink l)
Add one API link.
parameters:
l – An API link object
Setter method:
addApiLinks(Object o)
Add one or several API links
parameters:
o – One API link or an array or collection of API links (ApiLink objects).
Setter method:
clearApiLinks()
Clear the list of API links.
bufferSizetop

The size of internal buffers used when replacing text.

Setter method:
setBufferSize(int i)
parameters:
i – The buffer size, in bytes.
Default value:
8192 bytes
inputEncodingtop

The character encoding of the input file. Use this if the input file has a non-standard encoding, i.e. an encoding different from the Java virtual machine's (platform dependent) default charset.

Setter method:
setInputEncoding(Charset c)
parameters:
c – The input charset.
Setter method:
setInputEncoding(String s)
parameters:
s – The name of a character encoding.
Default value:
The platform's default encoding.
linkClasstop

The value of each inserted hypertext link's class attribute.

Setter method:
setLinkClass(String n)
parameters:
n – The attribute value.
Default value:
None (the class attribute is not set)
logFootertop

The message that is logged to info level after the task has been successfully run.

Setter method:
setLogFooter(String s)
parameters:
s – The footer message.
Default value:
Empty (no footer message is logged.)
See also:
logHeader
logHeadertop

The message that is logged to info level before the task is run.

Setter method:
setLogHeader(String s)
parameters:
s – The header message.
Default value:
A task class specific message.
See also:
logFooter
outputEncodingtop

The character encoding of the output file. Use this if the output file should have a non-standard encoding, i.e. an encoding different from the Java virtual machine's (platform dependent) default charset.

Setter method:
setOutputEncoding(Charset c)
parameters:
c – The output charset.
Setter method:
setOutputEncoding(String s)
parameters:
s – The name of a character encoding.
Default value:
The platform's default encoding.
See also:
target
overwriteStrategytop

The overwrite strategy decides how the task will react if there already is an entity (file or directory) in a location where it wants to create a new entity.

If the strategy is to not overwrite existing entities, the task will fail when it cannot create the entities that it wants to create.

Non-empty directories are never overwritten, regardless of the chosen strategy.

Setter method:
setOverwrite(boolean b)
Setting this to a value of true means that the DoOverwriteAndLogWarning strategy is used. A value of false gives the DontOverwriteAndThrowException strategy.
parameters:
b – Should an existing entity be overwritten?
Setter method:
setOverwriteStrategy(OverwriteStrategy strat)
Set the overwrite strategy.
parameters:
strat – The overwrite strategy.
Default value:
DontOverwriteAndThrowException
See also:
target
reportLeveltop

This property is used to change the Report level for all task created by this task factory. The report level is changed for the thread running the task when the it is run, and is restored to its previous level when the it is done.

Setter method:
setReportLevel(Level l)
Set the report level
parameters:
l – The new report level.
source (required)top

The source HTML file.

Setter method:
setSource(Object o)
parameters:
o – The source file.
Interpreted by InterpretAsReadOnlyFileStrategy.
See also:
inputEncoding
target (required)top

The target file.

Setter method:
setTarget(Object o)
parameters:
o – The target file.
Interpreted by InterpretAsNewWritableFileStrategy.
See also:
outputEncoding
overwriteStrategy
tempDirectorytop

A temporary files directory where intermediate replace results are put.

Setter method:
setTempDirectory(Object o)
parameters:
o – The temporary files directory.
Interpreted by |si:ai_directory;InterpretAsDirectoryStrategy|.
Default value:
The target file system's default temporary files directory.
traceLoggingtop

If trace logging is enabled for a task, it reports its configuration before it is run.

Trace logging may also be enabled globally for all tasks by calling TraceMode.setTraceMode(boolean).

Setter method:
setTraceLogging(boolean b)
Enable or disable trace logging.
parameters:
b – Enable trace logging?

Examples

Example 1

Build Javadocs from the Java source files in the directory hierarchy under src and put them in the api directory. Walk through all created HTML files and replace fully qualified class names in them with links to the classes' API documentation.

// Build Javadocs for the source files in the directory src. Put them in the // directory api. new ExtJavadocTF(). setSource(src). addPackageName("org.myproject"). setSubPackages(true). // // The dependencies object is a Map with dependency names mapped to Jar files. addClasspathEntry(dependencies.get("junit4")). addDecorator( new ExtStandardDocletDecorator(). setTarget(api). setWindowTitle("MyProject Javadocs")).run(); // Create an in-memory file system to hold temporary files. ramDir = SchmantFileSystems.createRamFileSystem(); // Replace fully qualified class names in the API documentation with links to // their Javadocs. // Use a RecursiveActionTF to iterate through the Javadocs. (Don't use a // RecursiveProcessTF since we're using the ReplaceSourceFileTF to replace the // original files.) new RecursiveActionTF(). setSource( // Use a DirectoryAndFilter that only matches HTML files. new DirectoryAndFilter( api, new EFileNameExtensionFilter(".html"))). setTaskFactory( // // Use a ReplaceSourceFileTF to replace the original files. new ReplaceSourceFileTF(). setTaskFactory( new ApiLinksTF(). // // Use the RAM directory for temporary files. setTempDirectory(ramDir). addApiLink( new ApiLink( "org.myproject.", "index.html")). addApiLink( new ApiLink( "org.entityfs.", "http://entityfs.sf.net/releases/current/api/index.html")). addApiLink( new ApiLink( "java.", "http://java.sun.com/javase/6/docs/api/index.html")). addApiLink( new ApiLink( "org.xml.", "http://java.sun.com/javase/6/docs/api/index.html")))).run();

Example 2

Use an explicit package link to insert an API link to the org.foo.bar package in the doc.html file.

// f is a File or an EFile object referencing the doc.html file new ReplaceSourceFileTF(). setSource(f). setTaskFactory( new ApiLinksTF(). addApiLink( new ApiLink( "org.foo.", "http://www.foo.org/api/index.html"))).run(); // If doc.html contains the following before it is processed: // Jada |api:package-summary:org.foo.bar?linkClass = nice| jada. // // It will contain the following after it is processed: // Jada <a class="nice" title="org.foo.bar" \ // href="http://www.foo.org/api/index.html?org/foo/bar/package-summary.html" \ // >org.foo.bar</a> jada.

* An EntityFS-aware task is implemented using EntityFS. This means that it uses the filter settings of DirectoryView:s and also that it often can work with other file system implementations than File-based, such as the RAM file system.