mazz.i18n.ant
Class I18NAntTask

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          mazz.i18n.ant.I18NAntTask

@I18NResourceBundle(baseName="i18n-anttask-messages",
                    defaultLocale="en")
public class I18NAntTask
extends org.apache.tools.ant.Task

An ANT task to generate resource bundle files containing I18N messages defined by the I18N annotations. A typical usage of this ANT task is as follows:

    <taskdef name="i18n" classpathref="i18nlog-jar.classpath" classname="mazz.i18n.ant.I18NAntTask" />

    <i18n outputdir="${classes.dir}"
          defaultlocale="en"
          verbose="true"
          append="false"
          verify="true">
       <classpath refid="my.classpath" />
       <classfileset dir="${classes.dir}"/>
    </i18n>
 

Where this says to output all resource bundles in the classes directory, assume a default locale of our application to be English, turn on verbose mode so this task can log alot of information about its progress, do not append to any existing resource bundles (we want to overwrite them) and verify that our code has not introduced duplicate or invalid messages. The classpath defines where all the classes can be found and the classfileset defines those classes that this task should process (it is these classes that will be examined for I18N message and resource bundle annotations - these classes must be found on the given classpath).

This ANT task can also output help documentation via the <helpdoc> inner tag that allows you to develop reference material for your users that further describe the meaning of the I18N messages (e.g. provide an explanation of specific error messages and how users can perform corrective action). See Helpdoc for more information.

Version:

$Revision: 1.12 $

Author:

John Mazzitelli

See Also:

Helpdoc

Field Summary

protected java.util.List<org.apache.tools.ant.types.FileSet>	m_classFilesets The file set containing the class files that will be examined for I18N annotations.
protected java.io.File	m_outputDir The base directory where the generate files will be written.
protected boolean	m_verbose Flag to indicate that this task should log some debug messages during processing.
protected boolean	m_verify Flag to indicate that this task should verify the correctness of the bundles and messages to be generated.

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

I18NAntTask()

Method Summary

void	addClassfileset(org.apache.tools.ant.types.FileSet fs) Adds a file set that contains class files this task will process.
void	addConfiguredHelpdoc(Helpdoc helpdoc) Adds the helpdoc element which indicates how to generate the help document.
org.apache.tools.ant.types.Path	createClasspath() If it does not yet exist, this will create an empty classpath.
void	execute()
void	setAppend(boolean append) If true, this task will append the messages it generates to resource bundle files that already exist.
void	setClassfilesetRef(org.apache.tools.ant.types.Reference reference) Adds a class fileset to the task given a reference to the fileset.
void	setClasspath(org.apache.tools.ant.types.Path s) Set the classpath to be used when running the Java class
void	setClasspathRef(org.apache.tools.ant.types.Reference r) Classpath to use, by reference.
void	setDefaultLocale(java.lang.String default_locale) Sets the locale that is to be considered the application's default locale.
void	setOutputDir(java.io.File directory) Sets the base output directory where the generated files will go.
void	setVerbose(boolean verbose) Sets the verbose flag which, when true, will allow this task to emit debug messages.
void	setVerify(boolean verify) Sets the verify flag which, when true, will force this task to ensure the correctness of the bundles and messages being generated (such as checking to make sure duplicate resource keys do not exist in a bundle).

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

getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

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

Field Detail

m_classFilesets

protected java.util.List<org.apache.tools.ant.types.FileSet> m_classFilesets

The file set containing the class files that will be examined for I18N annotations.

m_verbose

protected boolean m_verbose

Flag to indicate that this task should log some debug messages during processing.

m_verify

protected boolean m_verify

Flag to indicate that this task should verify the correctness of the bundles and messages to be generated.

m_outputDir

protected java.io.File m_outputDir

The base directory where the generate files will be written.

Constructor Detail

I18NAntTask

public I18NAntTask()

Method Detail

addClassfileset

public void addClassfileset(org.apache.tools.ant.types.FileSet fs)

Adds a file set that contains class files this task will process.

Parameters:

fs - the new fileset

setClassfilesetRef

public void setClassfilesetRef(org.apache.tools.ant.types.Reference reference)

Adds a class fileset to the task given a reference to the fileset.

Parameters:

reference - the fileset reference

setVerbose

public void setVerbose(boolean verbose)

Sets the verbose flag which, when true, will allow this task to emit debug messages.

Parameters:

verbose -

setVerify

public void setVerify(boolean verify)

Sets the verify flag which, when true, will force this task to ensure the correctness of the bundles and messages being generated (such as checking to make sure duplicate resource keys do not exist in a bundle).

Parameters:

verify -

setOutputDir

public void setOutputDir(java.io.File directory)

Sets the base output directory where the generated files will go.

Parameters:

directory -

setAppend

public void setAppend(boolean append)

If true, this task will append the messages it generates to resource bundle files that already exist. If false, any existing resource bundle will be overwritten.

Parameters:

append -

setDefaultLocale

public void setDefaultLocale(java.lang.String default_locale)

Sets the locale that is to be considered the application's default locale. If an i18n message does not have a declared locale (in either its I18NMessage or its enclosing I18NResourceBundle annotation), this defines its locale.

In addition, if a resource bundle is generated with the given locale, that resource bundle properties file will be copied and the new file will be named with the base bundle file excluding the locale string. This allows the running application to fallback to this given default locale, if the user's locale is not supported (that is, the application does not have a localized resource bundle for the user's locale).

Example: assume the given default_locale is "en". Assume also that this ANT task has generated a resource bundle with a base name of "my-messages" with the "en" locale (i.e. a resource bundle properties file named "my-messages_en.properties" was generated). Since this ANT task was told to assume the default locale is "en", it will copy "my-messages_en.properties" and name that copy "my-messages.properties". If a user runs the application and that user's locale does not have a resource bundle specific to it, this "my-messages.properties" file will be used to locate the i18n messages - which means the user will see English localized messages. If a default locale was not specified, the user would not see any localized messages for any language.

Parameters:

default_locale -

setClasspath

public void setClasspath(org.apache.tools.ant.types.Path s)

Set the classpath to be used when running the Java class

Parameters:

s - an Ant Path object containing the classpath.

setClasspathRef

public void setClasspathRef(org.apache.tools.ant.types.Reference r)

Classpath to use, by reference.

Parameters:

r - a reference to an existing classpath

createClasspath

public org.apache.tools.ant.types.Path createClasspath()

If it does not yet exist, this will create an empty classpath. If it was already created, it will be returned. This public method is required to support the nested classpath element.

Returns:

the classpath

addConfiguredHelpdoc

public void addConfiguredHelpdoc(Helpdoc helpdoc)
                          throws org.apache.tools.ant.BuildException

Adds the helpdoc element which indicates how to generate the help document. This is optional but only one can be specified.

Parameters:

helpdoc - the configured helpdoc element

Throws:

org.apache.tools.ant.BuildException - if the helpdoc element was specified more than once

execute

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

Overrides:

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

Throws:

org.apache.tools.ant.BuildException

See Also:

Task.execute()