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, ...]| |api:package-summary:package name[?key1=value1, key2=value2, ...]|key=value properties is used to control
attributes of the created links. The following keys are recognized:
linkClass- The created links'
classattributes. This overrides any value set in the linkClass property. title- The created links'
titleattributes. 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 linksparameters:- Setter method:
clearApiLinks()Clear the list of API links.
| bufferSize | top |
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
| inputEncoding | top |
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.
| linkClass | top |
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)
| logFooter | top |
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
| logHeader | top |
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
| outputEncoding | top |
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
| overwriteStrategy | top |
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 ofparameters:truemeans that the DoOverwriteAndLogWarning strategy is used. A value of false gives the DontOverwriteAndThrowException strategy.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
| reportLevel | top |
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 levelparameters:l– The new report level.
| source (required) | top |
The source HTML file.
- Setter method:
setSource(Object o)
parameters:- See also:
- inputEncoding
| target (required) | top |
The target file.
- Setter method:
setTarget(Object o)
parameters:- See also:
- outputEncoding
- overwriteStrategy
| tempDirectory | top |
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.
| traceLogging | top |
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.
JavaScript
JRuby
Jython
Example 2
Use an explicit package link to insert an API link to the
org.foo.bar package in the doc.html file.
JavaScript
* 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.