Links: Table of Contents | Single HTML | Single PDF

Tools

Table of Contents

1. Overview
1.1. How do I pick a tool?
1.2. Running tools on JDK6
1.3. Maven plugins
2. wsimport
2.1. wsimport Overview
2.2. Launching wsimport
2.3. wsimport Syntax
2.4. wsimport Example
3. wsimport Ant Task
3.1. wsimport Task Overview
3.2. Using wsimport Task
3.3. wsimport Examples
4. wsgen
4.1. wsgen Overview
4.2. Launching wsgen
4.3. wsgen Syntax
4.4. wsgen Example
5. wsgen Ant Task
5.1. wsgen Task Overview
5.2. Using wsgen Task
5.3. wsgen Task Examples
6. Annotation Processing
6.1. javac annotation processing
6.2. javac Annotation Processing Syntax
7. annotationProcessing Ant Task
7.1. annotationProcessing Task Overview
7.2. annotationProcessing Task Attributes
7.3. annotationProcessing Task Examples
7.4. Apt Ant task
8. apt

1. Overview

1.1. How do I pick a tool?

The following lists the process to create a web service starting from Java sources, classes, and a WSDL file (server side):

  1. Starting from Java sources:

    1. Use annotationProcessing Ant task to generate the artifacts required by the JAX-WS specification.

    2. Package the web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file,

    3. Deploy the WAR to a web container.

  2. Starting from Java classes:

    1. Use wsgen to generate portable artifacts.

    2. Package the web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file,

    3. Deploy the WAR to a web container.

  3. Starting from a WSDL file:

    1. Use wsimport to generate portable artifacts.

    2. Implement the service endpoint.

    3. Package the WSDL file, schema documents, web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file.

    4. Deploy the WAR to a web container.

The following lists the process to invoke a web service (client side):

  1. Starting from deployed web service's WSDL

    1. Use wsimport to generate the client-side artifacts.

    2. Implement the client to invoke the web service.

1.2. Running tools on JDK6

  • Copy JAXWS_HOME/lib/javax.annotation-api.jar JAXWS_HOME/lib/jsr181-api.jar JAXWS_HOME/lib/jaxws-api.jar JAXWS_HOME/lib/jaxb-api.jar to $JDK6_HOME/jre/lib/endorsed directory

For details see Endorsed Directory Mechanism. Above, JAXWS_HOME points to the root directory of the extracted JAX-WS RI bundle. JDK6_HOME points to JDK 6 installation directory.

1.3. Maven plugins

You can use all jaxws tools within your maven build. Information about maven plugin and its usage is located at the plugin homepage.

2. wsimport

2.1. wsimport Overview

The wsimport tool generates JAX-WS portable artifacts, such as:

  • Service Endpoint Interface (SEI)

  • Service

  • Exception class mapped from wsdl:fault (if any)

  • Async Reponse Bean derived from response wsdl:message (if any)

  • JAXB generated value types (mapped java classes from schema types)

These artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation to be deployed. JAX-WS RI 2.3.0-SNAPSHOT also provides a wsimport Ant Task.

2.2. Launching wsimport

  • Solaris/Linux

    • JAXWS_HOME/bin/wsimport.sh -help
  • Windows

    • JAXWS_HOME\bin\wsimport.bat -help

2.3. wsimport Syntax

wsimport [OPTION]... <WSDL>

The following table lists the wsimport options:

OptionDescription
-d <directory>Specify where to place generated output files.
-classpath <path>Specify where to find user class files and wsimport extensions.
-cp <path>Specify where to find user class files and wsimport extensions.
-b <path>Specify external JAX-WS or JAXB binding files or additional schema files (Each <file> must have its own -b).
-B <jaxbOption>Pass this option to JAXB schema compiler.
-catalogSpecify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Please read the documentation of Catalog and see catalog sample.
-extensionAllow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.
-helpDisplay help.
-httpproxy:<host>:<port>Specify an HTTP proxy server (port defaults to 8080).
-J<javacOption>Pass this option to Javac compiler. Note: use '=' instead of space as a delimiter between option name and its value.
-keepKeep generated source code files. It is enabled when -s option.
-p <pkg>Specifying a target package via this command-line option, overrides any wsdl and schema binding customization for package name and the default package name algorithm defined in the specification.
-s <directory>Specify where to place generated source code files. keep is turned on with this option.
-encoding <encoding>Set the encoding name for generated sources, such as EUC-JP or UTF-8. If -encoding is not specified, the platform default encoding is used.
-verboseOutput messages about what the compiler is doing.
-versionPrint version information.
-fullversionPrint full version information.
-clientjar <jarfile>Creates the jar file of the generated artifacts along with the WSDL metadata required for invoking the web service.
-wsdllocation <location>@WebServiceClient.wsdlLocation value.
-target <version>Generate code as per the given JAX-WS specification version. For example, "-target 2.0" generates compliant code for JAX-WS 2.0 spec. Default value is 2.2.
-quietSuppress wsimport output.
-XadditionalHeadersMap the headers not bound to request or response message to Java method parameters.
-XauthfileFile to carry authorization information in the format http://username:password@example.org/stock?wsdl. The asterisk character ("*") can be used to match multiple URL patterns. Default value is $HOME/.metro/auth
-XdebugPrint debug information.
-XdisableAuthenticatorDisables Authenticator used by JAX-WS RI, -Xauthfile option will be ignored if -XdisableAuthenticator is set.
-Xno-addressing-databindingEnable binding of W3C EndpointReferenceType to Java.
-XnocompileDo not compile generated Java files.
-XdisableSSLHostnameVerificationDisbales the SSL Hostname verification while fetching the wsdls.

Multiple JAX-WS and JAXB binding files can be specified using -b option and they can be used to customize various things like package names, bean names, etc. More information on JAX-WS and JAXB binding files can be found in the WSDL Customization.

2.4. wsimport Example

wsimport -p stockquote http://stockquote.xyz/quote?wsdl

This will generate the Java artifacts and compile them by importing the http://stockquote.xyz/quote?wsdl.

3. wsimport Ant Task

3.1. wsimport Task Overview

The wsimport generates JAX-WS portable artifacts, such as:

  • Service Endpoint Interface (SEI)

  • Service

  • Exception class mapped from wsdl:fault (if any)

  • Async Reponse Bean derived from response wsdl:message (if any)

  • JAXB generated value types (mapped java classes from schema types)

3.2. Using wsimport Task

To use this wsimport task, a <taskdef> element needs to be added to the project as given below:

<taskdef name="wsimport" classname="com.sun.tools.ws.ant.WsImport">
    <classpath path="jaxws.classpath"/>
</taskdef>

where jaxws.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.

3.2.1. Environment Variables

  • ANT_OPTS - command-line arguments that should be passed to the JVM. For example, you can define system properties or set the maximum Java heap size here.

3.2.2. wsimport Task Attributes

wsimport supports the following parameter attributes:

<wsimport
        wsdl="..."
        destdir="directory for generated class files"
        sourcedestdir="directory for generated source files"
        keep="true|false"
        encoding="..."
        extension="true|false"
        verbose="true|false"
        wsdlLocation="..."
        clientJar="jar file"
        catalog="catalog file"
        package="package name"
        target="target release"
        binding="..."
        quiet="true|false"
        fork="true|false"
        failonerror="true|false"
        xadditionalHeaders="true|false"
        xauthfile="authorization file"
        xdisableAuthenticator="true|false"
        xdebug="true|false"
        xNoAddressingDatabinding="true|false"
        xnocompile="true|false">
    <binding dir="..." includes="..."/>
    <arg value="..."/>
    <xjcarg value="..."/>
    <javacarg value="..."/>
    <jvmarg value="..."/>
    <xmlcatalog refid="another catalog file"/>
    <depends file="..."/>
    <produces dir="..."/>
</wsimport>
AttributeDescriptionRequiredCommand line
wsdlWSDL file.Yes.WSDL location
destdirSpecify where to place output generated classes.No. Defaults to current working directory.-d
sourcedestdirSpecify where to place generated source code files, keep is turned on with this option.No. Defaults to current working directory.-s
encodingSet the encoding name for generated sources, such as UTF-8.No. Defaults to platform default.-encoding
keepKeep generated source code files, turned on with sourcedestdir option.No. Defaults to false.-keep
verboseOutput JAX-WS RI version and messages about what the compiler is doingNo. Defaults to false.-verbose.
bindingSpecify external JAX-WS or JAXB binding files or additional schema files (Each <file> must have its own -b).No. No defaults.-b
extensionallow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.No. Defaults to false.-extension
wsdllocationThe wsdl URI passed thru this option will be used to set the value of @WebService.wsdlLocation and @WebServiceClient.wsdlLocation annotation elements on the generated SEI and Service interface.No. Defaults to the wsdl URL passed to wsdl attribute.-wsdllocation
clientJarCreates the jar file of the generated artifacts along with the WSDL metadata required for invoking the web service.No.-clientJar
catalogSpecify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Additionally, ant xmlcatalog type can be used to resolve entities, see catalog sample and Catalog.No. No defaults.-catalog
packageSpecifies the target package.No. It default to the WSDL/Schema targetNamespace to package mapping as defined by the JAXB 2.1 spec.-p
targetGenerate code as per the given JAXWS specification version. For example, 2.0 value generates compliant code for JAXWS 2.0 spec.No. Defaults to 2.2.-target
quietSuppress wsimport output.No. Defaults to false.-quiet
forkUsed to execute wsgen using forked VM.No. Defaults to false.None.
failonerrorIndicates whether errors will fail the build.No. Defaults to true.None.
xadditionalHeadersMap headers not bound to request or response message to Java method parameters.No. Defaults to false.-XadditionalHeaders
xauthfileFile to carry authorization information in the format http://username:password@example.org/stock?wsdl. The asterisk character ("*") can be used to match multiple URL patterns.No. Defaults to $HOME/.metro/auth.-Xauthfile
xdebugPrint debug information.No. Defaults to false.-Xdebug
xdisableAuthenticatorDisables Authenticator used by JAX-WS RI, -Xauthfile option will be ignored if -XdisableAuthenticator is set.No. Defaults to false.-XdisableAuthenticator
xNoAddressingDatabindingEnable binding of W3C EndpointReferenceType to Java.No. Defaults to false.-Xno-addressing-databinding
xnocompileDo not compile generated Java files.No. Defaults to false.-Xnocompile

3.2.3. Nested Elements

wsimport supports the following nested element parameters.

3.2.3.1. binding

To specify more than one external binding file at the same time, use a nested <binding> element, which has the same syntax as <fileset>.

3.2.3.2. arg

Additional command line arguments passed to the wsimport. 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 wsimport Ant task. For example, currently there is no native support for the following wsimport command-line options:

  • -XdisableSSLHostnameVerification

This nested element can be used to pass the -X command-line options directly like "-XadditionalHeaders". To use any of these features from the wsimport Ant task, you must specify the appropriate nested <arg> elements.

3.2.3.3. xjcarg

The usage is similar to <arg> nested element, except that these arguments are directly passed to the XJC tool (JAXB Schema Compiler), which will be used for compiling the schema referenced in the wsdl. For details about the syntax, see the relevant section in the Ant manual.

3.2.3.4. javacarg

The usage is similar to <arg> nested element, except that these arguments are directly passed to the Javac Compiler, which will be used for compiling sources generated during processing the referenced wsdl. For details about the syntax, see the relevant section in the Ant manual.Note: use '=' instead of space as a delimiter between option name and its value.

3.2.3.5. jvmarg

Use nested <jvmarg> elements to specify arguments for the the forked VM (ignored if fork is disabled), see the relevant section in the Ant manual.

3.2.3.6. xmlcatalog

The xmlcatalog element is used to resolve entities when parsing schema documents.

3.2.3.7. depends/produces

Files specified with this nested element are taken into account when the task does a modification date check. For proper syntax, see <fileset>.

3.3. wsimport Examples

<wsimport
        destdir="${build.classes.home}"
        debug="true"
        wsdl="AddNumbers.wsdl"
        binding="custom.xml"/>

The above example generates client-side artifacts for AddNumbers.wsdl, stores .class files in the ${build.classes.home} directory using the custom.xml customization file. The classpath used is xyz.jar and compiles with debug information on.

<wsimport
        keep="true"
        sourcedestdir="${source.dir}"
        destdir="${build.classes.home}"
        extension="true"
        wsdl="AddNumbers.wsdl">
    <xjcarg value="-cp"/>
    <xjcarg file="path/to/fluent-api.jar" />
    <xjcarg value="-Xfluent-api"/>
</wsimport>

The above example shows how to generates artifacts for AddNumbers.wsdl while passing options to JAXB xjc tool for XML Schema to Java compilation using your JAXB plugin. Note extension attribute which is set to true. You need to set this to use JAXB plugins.

Multiple JAX-WS and JAXB binding files can be specified using -b option and they can be used to customize various things like package names, bean names, etc. More information on JAX-WS and JAXB binding files can be found in the WSDL Customization.

4. wsgen

4.1. wsgen Overview

The wsgen tool generates JAX-WS portable artifacts used in JAX-WS web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation. JAX-WS RI 2.3.0-SNAPSHOT also provides a wsgen Ant Task.

4.2. Launching wsgen

  • Solaris/Linux

    • JAXWS_HOME/bin/wsgen.sh -help
  • Windows

    • JAXWS_HOME\bin\wsgen.bat -help

4.3. wsgen Syntax

wsgen [OPTION]... <SEI>

The following table lists the wsgen options:

OptionDescription
-classpath <path>Specify where to find input class files.
-cp <path>Same as -classpath <path>.
-d <directory>Specify where to place generated output files.
-extensionAllow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.
-helpDisplay help.
-J<javacOption>Pass this option to Javac compiler. Note: use '=' instead of space as a delimiter between option name and its value.
-keepKeep generated files.
-r <directory>Used only in conjunction with the -wsdl option. Specify where to place generated resource files such as WSDLs.
-s <directory>Specify where to place generated source files.
-encoding <encoding>Set the encoding name for generated sources, such as EUC-JP or UTF-8. If -encoding is not specified, the platform default encoding is used.
-verboseOutput messages about what the compiler is doing.
-versionPrint version information. Use of this option will ONLY print version information. Normal processing will not occur.
-fullversionPrint full version information. Use of this option will ONLY print version information. Normal processing will not occur.
-wsdl[:protocol]By default wsgen does not generate a WSDL file. This flag is optional and will cause wsgen to generate a WSDL file and is usually only used so that the developer can look at the WSDL before the endpoint is deploy. The protocol is optional and is used to specify what protocol should be used in the wsdl:binding. Valid protocols include: soap1.1 and Xsoap1.2. The default is soap1.1. Xsoap1.2 is not standard and can only be used in conjunction with the -extension option.
-servicename <name>

Used only in conjunction with the -wsdl option. Used to specify a particular wsdl:service name to be generated in the WSDL. Example:

-servicename "{http://mynamespace/}MyService"
-portname <name>

Used only in conjunction with the -wsdl option. Used to specify a particular wsdl:port name to be generated in the WSDL. Example:

-portname "{http://mynamespace/}MyPort"
-inlineSchemasUsed to inline schemas in a generated wsdl. Must be used in conjunction with the -wsdl option.
-x <path>Used to specify External Web Service Metadata xml descriptor to be used. If there are more such files, the option must be used before each of those.
-XnocompileDo not compile generated Java files.

4.4. wsgen Example

wsgen -d stock -cp myclasspath stock.StockService

This will generate the wrapper classes needed for StockService annotated with @WebService annotation inside the stock directory.

wsgen -wsdl -d stock -cp myclasspath stock.StockService

This will generate a SOAP 1.1 WSDL and schema for your Java class stock.StockService annotated with @WebService annotation.

wsgen -wsdl:Xsoap1.2 -d stock -cp myclasspath stock.StockService

Will generate a SOAP 1.2 WSDL.

Note

You don't have to generate WSDL at the development time as JAX-WS runtime will automatically generate a WSDL for you when you deploy your service.

5. wsgen Ant Task

5.1. wsgen Task Overview

wsgen generates JAX-WS portable artifacts used in JAX-WS web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation.

5.2. Using wsgen Task

Before this task can be used, a <taskdef> element needs to be added to the project as given below:

<taskdef name="wsgen" classname="com.sun.tools.ws.ant.WsGen">
    <classpath path="jaxws.classpath"/>
</taskdef>

where jaxws.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.

5.2.1. Environment Variables

  • ANT_OPTS - command-line arguments that should be passed to the JVM. For example, you can define system properties or set the maximum Java heap size here.

5.2.2. wsgen Task Attributes

The attributes and elements supported by the Ant task are listed below:

<wsgen
        sei="..."
        destdir="directory for generated class files"
        classpath="classpath" | cp="classpath"
        resourcedestdir="directory for generated resource files such as WSDLs"
        sourcedestdir="directory for generated source files"
        keep="true|false"
        encoding="..."
        verbose="true|false"
        genwsdl="true|false"
        protocol="soap1.1|Xsoap1.2"
        servicename="..."
        portname="..."
        extension="true|false"
        inlineSchemas="true|false"
        fork="true|false"
        failonerror="true|false"
        xnocompile="true|false">
    <classpath refid="..."/>
    <externalmetadata file="..."/>
    <javacarg value="..."/>
    <jvmarg value="..."/>
</wsgen>
AttributeDescriptionRequiredCommand line
seiName of the service endpoint implementation class.Yes.SEI
destdirSpecify where to place output generated classes.No. Defaults to current working directory.-d
classpathSpecify where to find input class files.One of these or nested classpath element. -classpath
cpSame as -classpath.-cp
resourcedestdirUsed only in conjunction with the -wsdl option. Specify where to place generated resource files such as WSDLs.No. Defaults to destDir.-r
sourcedestdirSpecify where to place generated source files.No. Defaults to current working directory.-s
encodingSet the encoding name for generated sources, such as UTF-8.No. Defaults to platform default.-encoding
keepKeep generated files.No. Defaults to false.-keep
verboseOutput JAX_WS RI version and messages about what the compiler is doing.No. Defaults to false.-verbose
genwsdlSpecify that a WSDL file should be generated.No. Defaults to false.-wsdl
protocolUsed in conjunction with genwsdl to specify the protocol to use in the wsdl:binding. Value values are "soap1.1" or "Xsoap1.2", default is "soap1.1". "Xsoap1.2" is not standard and can only be used in conjunction with the -extensions option.No. Defaults to -wsdl:soap11.-wsdl[:protocol]
servicename

Used in conjunction with the genwsdl option. Used to specify a particular wsdl:service name for the generated WSDL. Example:

servicename="{http://mynamespace/}MyService"
No. No defaults.-servicename
portname

Used in conjunction with the genwsdl option. Used to specify a particular wsdl:portname name for the generated WSDL. Example:

portname="{http://mynamespace/}MyPort"
No. No defaults.-portname
extensionAllow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.No. Defaults to false.-extension
inlineSchemasUsed to inline schemas in a generated wsdl. Must be used in conjunction with the wsdl option.No. Defaults to false.-inlineSchemas
forkUsed to execute wsgen using forked VM.No. Defaults to false.None.
failonerrorIndicates whether errors will fail the build.No. Defaults to true.None.
xnocompileDo not compile generated Java files.No. Defaults to false.-Xnocompile

The classpath/cp attribute is a path-like structure and can also be set via nested <classpath> elements.

5.2.3. Nested Elements

wsgen supports the following nested element parameters.

5.2.3.1. external-metadata

An optional element external-metadata can be used if there are any web service metadata to be specified in xml file instead of java annotations:

<wsgen
        resourcedestdir="${wsdl.dir}"
        sei="fromjava.server.AddNumbersImpl">
    <classpath refid="compile.classpath"/>
    <external-metadata file="metadata-AddNumbersImpl.xml"/>
</wsgen>

For details see External Web Service Metadata.

5.2.3.2. javacarg

The usage is similar to <arg> nested element, except that these arguments are directly passed to the Javac Compiler, which will be used for compiling sources generated during processing the referenced wsdl. For details about the syntax, see the relevant section in the Ant manual. Note: use '=' instead of space as a delimiter between option name and its value.

5.2.3.3. jvmarg

Use nested <jvmarg> elements to specify arguments for the the forked VM (ignored if fork is disabled), see the relevant section in the Ant manual.

5.3. wsgen Task Examples

<wsgen
        resourcedestdir="${wsdl.dir}"
        sei="fromjava.server.AddNumbersImpl">
    <classpath refid="compile.classpath"/>
</wsgen>

6. Annotation Processing

6.1. javac annotation processing

As an improvement for the apt Pluggable Annotation Processing API was introduced in Java SE 6. It provides an API to allow the processing of JSR 175 annotations (metadata); this will require modeling elements of the Java TM programming language as well as processing-specific functionality.

The javac generates the portable artifacts used in JAX-WS services.

6.2. javac Annotation Processing Syntax

javac [JAVAC_OPTION]... <SOURCE_FILE>...

The following table lists the javac options useful for annotation processing:

OptionDescription
-classpath <path> Specifies where to find user class files and annotation processor factories.
-d <path>Specifies where to place processor generated class files.
-s <path>Specifies where to place processor generated source files.
-source <release>Provide source compatibility with the specified release.
-XprintPrint out textual representation of specified types for debugging purposes; perform neither annotation processing nor compilation. The format of the output may change.
-XprintProcessorInfoPrint information about which annotations a processor is asked to process.
-XprintRoundsPrint information about initial and subsequent annotation processing rounds.
-A[key[=value]]Options to pass to annotation processors.
-proc:{none,only}Control whether annotation processing and/or compilation is done.
-sourcepath <path> Specify where to find input source files.
-endorseddirs <dirs> Override location of endorsed standards path.
-processor <class1>[,<class2>...]Names of the annotation processors to run; bypasses default discovery process
-processorpath <path>Specify where to find annotation processors

More options and detailed information on javac can be found here.

It is important when using javac with JAX-WS to specify all of the JAR files in the distributed JAX-WS bundle in the classpath passed to javac. As JAX-WS annotation processor you have to specify com.sun.tools.ws.processor.modeler.annotation.WebServiceAp. The -sourcepath <path> option must also be provided so that javac and the JAX-WS annotation processor can find all types referenced by a web service endpoint implementation class. In case you don't have additional annotation processors it's recommended to use annotationProcessing Ant Task.

7. annotationProcessing Ant Task

7.1. annotationProcessing Task Overview

An Ant task for the annotationProcessing is provided with JAX-WS RI 2.3.0-SNAPSHOT.

7.2. annotationProcessing Task Attributes

The attributes and elements supported by the Ant task almost the same as for the javac ant task. With only one restriction: by default jax-ws annotation processor will be used. There several additional attributes for usability improvement:

AttributeDescriptionRequired
procOnlyControl whether annotation processing and compilation is done. Can be true or false. Default is false.false
sourcedestdirSpecify where to place processor generated source files. -s <path>true

The list of source files to be processed are specified via a nested <srcdir> element. That is, a path-like structure. The classpath attribute is a path-like structure and can also be set via nested <classpath> elements. Before this task can be used, a <taskdef> element needs to be added to the project as given below:

<taskdef name="annotationProcessing"
        classname="com.sun.tools.ws.ant.AnnotationProcessingTask">
    <classpath refid="jaxws.classpath"/>
</taskdef>

where jaxws.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.

7.3. annotationProcessing Task Examples

<annotationProcessing
        destdir="${build.classes.home}"
        sourceDestDir="${build.classes.home}"
        srcdir="${basedir}/src"
        includes="*.java"
        sourcepath="${basedir}/src">
    <classpath refid="jaxws.classpath"/>
</annotationProcessing>

The above example processes the Java source files in the ${basedir}/src directory and generates the source and class files in ${build.classes.home}. ${basedir}/src is directory used to search for source files for multiple annotationProcessing rounds. The classpath is a reference to a path-like structure jaxws.classpath, defined elsewhere in the build environment.

<annotationProcessing
        debug="true"
        verbose="true"
        destdir="${build.classes.home}"
        srcdir="${basedir}/src""
        includes="**/server/*.java"
        sourceDestDir="${build.classes.home}"
        sourcepath="${basedir}/src">
    <classpath refid="jaxws.classpath"/>
</annotationProcessing>

The above example processes the Java source files in ${basedir}/src/**/server, generates the source and class files in ${build.classes.home}, compiles with debug information on, prints a message about what the compiler is doing. ${basedir}/src is the directory used to search for source files for multiple annotationProcessing rounds. The classpath is a reference to a path-like structure jaxws.classpath, defined elsewhere in the build environment. This will also fork off the annotationProcessing process using the default java executable.

7.4. Apt Ant task

For backwards compatibility Apt Ant task still exists, but is marked as deprecated, and can be used with certain restrictions.

8. apt

The apt tool provided a facility for programmatically processing the annotations added to Java by JSR 175, Metadata Facility for the Java TM Programming Language. In brief, JSR 175 allows programmers to declare new kinds of structured modifiers that can be associated with program elements, fields, methods, classes, etc.

The javac completely replaced functionality provided by apt. It was done within implementation of JSR 269, Pluggable Annotation Processing API. So it's expected programmers to use javac instead of apt.

Using javac with JAX-WS annotation processor will generate portable artifacts used in JAX-WS services.

Be aware that the apt tool and its associated API, com.sun.mirror.\*, are being deprecated in JDK 7.

For more information on this compiler please see Annotation Processing.