org.apache.ws.jaxme.generator

Class XJCTask


public class XJCTask
extends Task

An Ant task for running JaxMe, designed to be JAXB compatible.

This task supports the following attributes:

NameDescriptionRequired/Default
schemaName of a schema file being compiledThis or nested <schema> elements are required
bindingAn external binding file being applied to the schema fileNo
forceSetting this option to true forces the up-to-date check to fail. This option is mainly useful while working on the JaxMe generator. For JaxMe users, which only change schema files, this option isn't of much use. It is designed for JaxMe developers.No, false
packageSpecifies the generated Java sources package name. Overrides package specifications in the schema bindings, if any.No, a package may be specified in the schema bindings.
targetSpecifies the target directory for generated Java source files. A package structure will be created below that directory. For example, with target="src" and package="org.acme", you will have files being created in "src/org/acme".No, defaults to the current directory
resourceTargetSpecifies the target directory for generated resource files. A package structure will be created below that directory. For example, with target="src" and package="org.acme", you will have files being created in "src/org/acme".No, defaults to the "target" directory
readonlyGenerated Java source files are in read-only mode, if true is specifiedNo, defaults to false
extensionIf set to true, the XJC binding compiler will run in the extension mode. Otherwise, it will run in the strict conformance mode.No, defaults to false
stackSizeSpecify the thread stack size for the XJC binding compiler (J2SE SDK v1.4 or higher). The XJC binding compiler can fail to compile large schemas with StackOverflowError and, in that case, this option can be used to extend the stack size. If unspecified, the default VM size is used. The format is equivalent to the -Xss command-line argument for Sun Microsystems JVM. This value can be specified in bytes (stackSize="2097152"), kilobytes (stackSize="2048kb"), or megabytes (stackSize="2mb").
This attribute is ignored by the JaxMe ant task and present for compatibility reasons only.
No, defaults to false
removeOldOutputIf one or more nested <produces> elements are specified and this attribute is set to true, then the Ant task will ensure that only generated files will remain. In other words, if you had removed an element named "Foo" from the previous schema version, then the Ant task will remove "Foo.java".No, defaults to false
validatingSets whether the XML schema parser is validating. By default it isn't.No, defaults to false

Besides the attributes, the ant task also supports the following nested elements:

NameDescriptionRequired/Multiplicity
schemaMultiple schema files may be compiled in one or more nested <schema> elements. The element syntax is equivalent to a nested <fileset>. Use of a nested <schema> element is mutually exclusive with the use of a "schema" attribute.0 - Unbounded
bindingMultiple external binding files may be specified. The element syntax is equivalent to a nested <fileset>. Use of a nested <binding> element is mutually exclusive with the use of a "binding" attribute.0 - Unbounded
classpathThis nested element is ignored by the JaxMe ant task and exists for compatibility to the JAXB ant task only. In the case of JAXB it specifies a classpath for loading user defined types (required in the case of a <javaType> customization) 0 - Unbounded
argThis nested element is ignored by the JaxMe ant task and exists for compatibility to the JAXB ant task only. In the case of JAXB it specifies additional command line arguments being passed to the XJC. For details about the syntax, see the relevant section in the Ant manual.
This nested element can be used to specify various options not natively supported in the xjc Ant task. For example, currently there is no native support for the following xjc command-line options:
  • -nv
  • -catalog
  • -use-runtime
  • -schema
  • -dtd
  • -relaxng
0 - Unbounded
dtdIf this nested element is used to specify, that the input files aren't instances of XML Schema, but DTD's. The nested element may have an attribute "targetNamespace", which specifies an optional target namespace. No
dependsBy default the JaxMe Ant tasks up-to-date check considers the specified schema and binding files only. This is insufficient, if other schema files are included, imported or redefined.
The nested <depends> element allows to specify additional files to consider for the up-to-date check. Typically these are the additional schema files.
Syntactically the <depends> element specifies a nested <fileset>.
0 - Unbounded
producesSpecifies the set of files being created by the JaxMe ant task. These files are considered as targets for the up-to-date check. The syntax of the <produces> element is equivalent to a nested <fileset>. However, you typically do not need to set the "dir" attribute, because it defaults to the target directory.0 - Unbounded
propertySets a property value. These properties may be used by the various source generators to configure the behaviour. For example, the JDBC schema reader uses the options "jdbc.driver", "jdbc.url", "jdbc.user", and "jdbc.password" to configure the database connection. Each property must have attributes "name" (the property name) and "value" (the property value).0 - Unbounded
schemaReaderConfigures the schema reader to use. Defaults to "org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader", which is the JAXB compliant schema reader. An alternative schema readers is, for example, "org.apache.ws.jaxme.generator.sg.impl.JaxMeSchemaReader" (a subclass of JAXBSchemaReader with JaxMe specific extensions).0 - 1
sgFactoryChainIf the schema reader is an instance of JAXBSchemaReader, then you may add instances of SGFactoryChain to the schema generation process. For example, such chains are used to create the persistency layer. The best example is the JaxMeJdbcSG, which is able to populate the schema with tables and columns read from a database via JDBC metadata.0 - Unbounded
xmlCatalogAdds an XML catalog to our internal catalog, which is used to resolve external entities and URI's. See the Ant documentation for details on XML catalogs.0 - Unbounded

By default, the JaxMe ant task will always run the generator and create new files. This is typically inappropriate for an ant script where your desire is to have as little modifications as possible, because new files also need to be recompiled, which is slow and time consuming.

To achieve a better behaviour, use the nested <produces> and <depends> elements. If one or more <produces> element is specified, then an up-to-date check is performed as follows:

  1. If either of the filesets specified by the <produces> elements is empty, then the binding compiler will run.
  2. Otherwise the sets of source and target files will be created. The set of source files is specified by the "schema" and "binding" attributes, and by the nested <schema>, <binding>, and <depends> elements. If any of the files in the source set is newer than any of the files in the target set, then the binding comoiler will run.
Author:
Jochen Wiedmann

Nested Class Summary

static class
XJCTask.ClassType
static class
XJCTask.Dtd
This class is used to store the nested element "dtd".
class
XJCTask.MyClassLoader
static class
XJCTask.Property

Method Summary

void
addArg(Commandline.Argument pArg)
This nested element is ignored by the JaxMe ant task and exists for compatibility to the JAXB ant task only.
void
addBinding(FileSet pBindings)
Multiple external binding files may be specified.
void
addClasspath(Path pClasspath)
This nested element is ignored by the JaxMe ant task and exists for compatibility to the JAXB ant task only.
void
addConfiguredXMLCatalog(XMLCatalog pXmlCatalog)
Adds an XML catalog to our internal catalog.
void
addDepends(FileSet pDepends)
By default the JaxMe Ant tasks up-to-date check considers the specified schema and binding files only.
void
addSchema(FileSet pSchemas)
Multiple schema files may be compiled in one or more nested <schema> elements.
XJCTask.Dtd
createDtd()
Creates a nested element "dtd".
FileSet
createProduces()
Specifies the set of files being created by the JaxMe ant task.
XJCTask.Property
createProperty()
Sets a property value.
XJCTask.ClassType
createSGFactoryChain()
Configures a new instance of SGFactoryChain being included into the schema generation process.
XJCTask.ClassType
createSchemaReader()
Configures the schema reader to use.
void
execute()
void
finish()
File
getBinding()
Returns an external binding file being applied to the schema file.
FileSet[]
getBindings()
Multiple external binding files may be specified.
FileSet[]
getDepends()
By default the JaxMe Ant tasks up-to-date check considers the specified schema and binding files only.
String
getDescription()
Returns the ant tasks description.
XJCTask.Dtd
getDtd()
Returns the nested element "dtd".
String
getPackage()
Returns the generated Java sources package name.
FileSet[]
getProduces()
Returns the set of files being created by the JaxMe ant task.
XJCTask.Property[]
getProperties()
Returns the configured property values.
File
getResourceTarget()
Returns the target directory for generating resource files.
XJCTask.ClassType[]
getSGFactoryChains()
Returns the array of configured instances of SGFactoryChain.
File
getSchema()
Returns the name of the schema file being compiled.
SchemaReader
getSchemaReader()
Returns the configured schema reader to use.
FileSet[]
getSchemas()
Multiple schema files may be compiled in one or more nested <schema> elements.
String
getStackSize()
Returns the thread stack size for the XJC binding compiler (J2SE SDK v1.4 or higher).
File
getTarget()
Returns the target directory for generating Java source files.
void
init()
Initialize internal instance of XMLCatalog
LoggerFactory
initLogging()
boolean
isExtension()
Returns, whether the XJC binding compiler will run in the extension mode.
boolean
isForce()
Setting this option to true forces the up-to-date check to fail.
boolean
isReadOnly()
Returns, whether generated Java source files are in read-only mode.
boolean
isRemoveOldOutput()
If one or more nested <produces> elements are specified and this attribute is set to true, then the Ant task will ensure that only generated files will remain.
boolean
isSettingLoggerFactory()
Returns whether the ant task is setting the LoggerFactory.
boolean
isUpToDate(File[] pSchemaFiles, File[] pBindingFiles, File[] pDependsFiles, List pProducesList)
boolean
isValidating()
Returns whether the XML schema parser is validating.
void
setBinding(File pBinding)
Sets an external binding file being applied to the schema file.
void
setExtension(boolean pExtension)
Sets, whether the XJC binding compiler will run in the extension mode.
void
setForce(boolean pForce)
Setting this option to true forces the up-to-date check to fail.
void
setPackage(String pPackageName)
Sets the generated Java sources package name.
void
setPackageName(String pPackageName)
Deprecated. Use setPackage(String).
void
setReadOnly(boolean pReadOnly)
Sets, whether generated Java source files are in read-only mode.
void
setRemoveOldOutput(boolean pRemoveOldOutput)
If one or more nested <produces> elements are specified and this attribute is set to true, then the Ant task will ensure that only generated files will remain.
void
setResourceTarget(File pTarget)
Sets the target directory for generating resource files.
void
setSchema(File pSchema)
Sets the name of the schema file being compiled.
void
setSettingLoggerFactory(boolean pIsSettingLoggerFactory)
Sets whether the ant task is setting the LoggerFactory.
void
setStackSize(String pStackSize)
Sets the thread stack size for the XJC binding compiler (J2SE SDK v1.4 or higher).
void
setTarget(File pTarget)
Sets the target directory for generating Java source files.
void
setValidating(boolean pValidating)
Sets whether the XML schema parser is validating.
void
stopLogging(LoggerFactory pFactory)

Method Details

addArg

public void addArg(Commandline.Argument pArg)
This nested element is ignored by the JaxMe ant task and exists for compatibility to the JAXB ant task only. In the case of JAXB it specifies additional command line arguments being passed to the XJC. For details about the syntax, see the relevant section in the Ant manual.
This nested element can be used to specify various options not natively supported in the xjc Ant task. For example, currently there is no native support for the following xjc command-line options:
  • -nv
  • -catalog
  • -use-runtime
  • -schema
  • -dtd
  • -relaxng

addBinding

public void addBinding(FileSet pBindings)
Multiple external binding files may be specified. The element syntax is equivalent to a nested <fileset>. Use of a nested <binding> element is mutually exclusive with the use of a "binding" attribute.

addClasspath

public void addClasspath(Path pClasspath)
This nested element is ignored by the JaxMe ant task and exists for compatibility to the JAXB ant task only. In the case of JAXB it specifies a classpath for loading user defined types (required in the case of a <javaType> customization)

addConfiguredXMLCatalog

public void addConfiguredXMLCatalog(XMLCatalog pXmlCatalog)
Parameters:

addDepends

public void addDepends(FileSet pDepends)
By default the JaxMe Ant tasks up-to-date check considers the specified schema and binding files only. This is insufficient, if other schema files are included, imported or redefined.
The nested <depends> element allows to specify additional files to consider for the up-to-date check. Typically these are the additional schema files.
Syntactically the <depends> element specifies a nested <fileset>.

addSchema

public void addSchema(FileSet pSchemas)
Multiple schema files may be compiled in one or more nested <schema> elements. The element syntax is equivalent to a nested <fileset>. Use of a nested <schema> element is mutually exclusive with the use of a "schema" attribute.

createDtd

public XJCTask.Dtd createDtd()
Creates a nested element "dtd".

createProduces

public FileSet createProduces()
Specifies the set of files being created by the JaxMe ant task. These files are considered as targets for the up-to-date check. The syntax of the <produces> element is equivalent to a nested <fileset>.

createProperty

public XJCTask.Property createProperty()
Sets a property value. These properties may be used by the various source generators to configure the behaviour. For example, the JDBC schema reader uses the options "jdbc.driver", "jdbc.url", "jdbc.user", and "jdbc.password" to configure the database connection. Each property must have attributes "name" (the property name) and "value" (the property value).

createSGFactoryChain

public XJCTask.ClassType createSGFactoryChain()
Configures a new instance of SGFactoryChain being included into the schema generation process. This option is valid only, if the schema reader is an instance of JAXBSchemaReader, because its method JAXBSchemaReader.addSGFactoryChain(Class) must be invoked.

The order of the chain elements may be significant. The schema reader itself will always be the last element in the chain.


createSchemaReader

public XJCTask.ClassType createSchemaReader()
Configures the schema reader to use. Defaults to "org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader", which is the JAXB compliant schema reader. An alternative schema readers is, for example, "org.apache.ws.jaxme.generator.sg.impl.JaxMeSchemaReader" (a subclass of JAXBSchemaReader with JaxMe specific extensions).

execute

public void execute()

finish

public void finish()

getBinding

public File getBinding()
Returns an external binding file being applied to the schema file.

getBindings

public FileSet[] getBindings()
Multiple external binding files may be specified. The element syntax is equivalent to a nested <fileset>. Use of a nested <binding> element is mutually exclusive with the use of a "binding" attribute.

getDepends

public FileSet[] getDepends()
By default the JaxMe Ant tasks up-to-date check considers the specified schema and binding files only. This is insufficient, if other schema files are included, imported or redefined.
The nested <depends> element allows to specify additional files to consider for the up-to-date check. Typically these are the additional schema files.
Syntactically the <depends> element specifies a nested <fileset>.

getDescription

public String getDescription()
Returns the ant tasks description.

getDtd

public XJCTask.Dtd getDtd()
Returns the nested element "dtd".

getPackage

public String getPackage()
Returns the generated Java sources package name. A non-null package specification overrides package specifications in the schema bindings, if any.

getProduces

public FileSet[] getProduces()
Returns the set of files being created by the JaxMe ant task. These files are considered as targets for the up-to-date check. The syntax of the <produces> element is equivalent to a nested <fileset>.

getProperties

public XJCTask.Property[] getProperties()
Returns the configured property values. These properties may be used by the various source generators to configure the behaviour. For example, the JDBC schema reader uses the options "jdbc.driver", "jdbc.url", "jdbc.user", and "jdbc.password" to configure the database connection. Each property must have attributes "name" (the property name) and "value" (the property value).

getResourceTarget

public File getResourceTarget()
Returns the target directory for generating resource files. A package structure will be created below that directory. For example, with target="src" and package="org.acme", you will have files being created in "src/org/acme". By default, the same directory is being used for Java source files and resource files.

getSGFactoryChains

public XJCTask.ClassType[] getSGFactoryChains()
Returns the array of configured instances of SGFactoryChain. The order of the array is significant. The schema reader itself will always be the last element in the chain. Therefore, it is not present in the array.

getSchema

public File getSchema()
Returns the name of the schema file being compiled.

getSchemaReader

public SchemaReader getSchemaReader()
Returns the configured schema reader to use. Defaults to "org.apache.ws.jaxme.generator.sg.impl.JAXBSchemaReader", which is the JAXB compliant schema reader. An alternative schema readers is, for example, "org.apache.ws.jaxme.generator.sg.impl.JaxMeSchemaReader" (a subclass of JAXBSchemaReader with JaxMe specific extensions).

getSchemas

public FileSet[] getSchemas()
Multiple schema files may be compiled in one or more nested <schema> elements. The element syntax is equivalent to a nested <fileset>. Use of a nested <schema> element is mutually exclusive with the use of a "schema" attribute.

getStackSize

public String getStackSize()
Returns the thread stack size for the XJC binding compiler (J2SE SDK v1.4 or higher). The XJC binding compiler can fail to compile large schemas with StackOverflowError and, in that case, this option can be used to extend the stack size. If unspecified, the default VM size is used. The format is equivalent to the -Xss command-line argument for Sun Microsystems JVM. This value can be specified in bytes (stackSize="2097152"), kilobytes (stackSize="2048kb"), or megabytes (stackSize="2mb").

This attribute is ignored by the JaxMe ant task and present for compatibility reasons only.


getTarget

public File getTarget()
Returns the target directory for generating Java source files. A package structure will be created below that directory. For example, with target="src" and package="org.acme", you will have files being created in "src/org/acme".

init

public void init()
Initialize internal instance of XMLCatalog

initLogging

public LoggerFactory initLogging()

isExtension

public boolean isExtension()
Returns, whether the XJC binding compiler will run in the extension mode. By default, it will run in the strict conformance mode.

isForce

public boolean isForce()
Setting this option to true forces the up-to-date check to fail. This option is mainly useful while working on the JaxMe generator. For JaxMe users, which only change schema files, this option isn't of much use. It is designed for JaxMe developers.

isReadOnly

public boolean isReadOnly()
Returns, whether generated Java source files are in read-only mode.

isRemoveOldOutput

public boolean isRemoveOldOutput()
If one or more nested <produces> elements are specified and this attribute is set to true, then the Ant task will ensure that only generated files will remain. In other words, if you had removed an element named "Foo" from the previous schema version, then the Ant task will remove "Foo.java".

isSettingLoggerFactory

public boolean isSettingLoggerFactory()
Returns whether the ant task is setting the LoggerFactory. This option is only useful, if you are using the Ant task from another Java class and not from within Ant.

isUpToDate

public boolean isUpToDate(File[] pSchemaFiles,
                          File[] pBindingFiles,
                          File[] pDependsFiles,
                          List pProducesList)

isValidating

public boolean isValidating()
Returns whether the XML schema parser is validating.

setBinding

public void setBinding(File pBinding)
Sets an external binding file being applied to the schema file.

setExtension

public void setExtension(boolean pExtension)
Sets, whether the XJC binding compiler will run in the extension mode. By default, it will run in the strict conformance mode.

setForce

public void setForce(boolean pForce)
Setting this option to true forces the up-to-date check to fail. This option is mainly useful while working on the JaxMe generator. For JaxMe users, which only change schema files, this option isn't of much use. It is designed for JaxMe developers.

setPackage

public void setPackage(String pPackageName)
Sets the generated Java sources package name. A non-null package specification overrides package specifications in the schema bindings, if any.

setPackageName

public void setPackageName(String pPackageName)

Deprecated. Use setPackage(String).


setReadOnly

public void setReadOnly(boolean pReadOnly)
Sets, whether generated Java source files are in read-only mode.

setRemoveOldOutput

public void setRemoveOldOutput(boolean pRemoveOldOutput)
If one or more nested <produces> elements are specified and this attribute is set to true, then the Ant task will ensure that only generated files will remain. In other words, if you had removed an element named "Foo" from the previous schema version, then the Ant task will remove "Foo.java".

setResourceTarget

public void setResourceTarget(File pTarget)
Sets the target directory for generating resource files. A package structure will be created below that directory. For example, with target="src" and package="org.acme", you will have files being created in "src/org/acme". By default, the same directory is being used for Java source files and resource files.

setSchema

public void setSchema(File pSchema)
Sets the name of the schema file being compiled.

setSettingLoggerFactory

public void setSettingLoggerFactory(boolean pIsSettingLoggerFactory)
Sets whether the ant task is setting the LoggerFactory. This option is only useful, if you are using the Ant task from another Java class and not from within Ant.

setStackSize

public void setStackSize(String pStackSize)
Sets the thread stack size for the XJC binding compiler (J2SE SDK v1.4 or higher). The XJC binding compiler can fail to compile large schemas with StackOverflowError and, in that case, this option can be used to extend the stack size. If unspecified, the default VM size is used. The format is equivalent to the -Xss command-line argument for Sun Microsystems JVM. This value can be specified in bytes (stackSize="2097152"), kilobytes (stackSize="2048kb"), or megabytes (stackSize="2mb").

This attribute is ignored by the JaxMe ant task and present for compatibility reasons only.


setTarget

public void setTarget(File pTarget)
Sets the target directory for generating Java source files. A package structure will be created below that directory. For example, with target="src" and package="org.acme", you will have files being created in "src/org/acme".

setValidating

public void setValidating(boolean pValidating)
Sets whether the XML schema parser is validating.

stopLogging

public void stopLogging(LoggerFactory pFactory)