JAX-WS 2.0 Beta
APT

Last Modified: 11/3/05

`apt`

The apt tool provides a facility for programmatically processing the annotations added to Java by JSR 175, Metadata Facility for the Java^TMProgramming 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 apt tool generates the portable artifacts used in JAX-WS services.

Command-line

Syntax

apt <apt and javac options> <source files>

The following table lists the apt options.

Table 1-1 apt Options

Option	Description
`-classpath <path>`	Specifies where to find user class files and annotation processor factories
`-cp <path>`	Same as `-classpath <path>`
`-d <path>`	Specifies where to place processor and `javac` generated class files
`-s <path>`	Specifies where to place processor generated source files
`-source <release>`	Provide source compatibility with the specified release
`-version`	Version information
`-help`	Print a synopsis of standard options; use `javac -help` for more options
`-X`	Print a synopsis of non-standard options
`-J<flag>`	Pass <flag> directly to the runtime system
`-A[key[=value]]`	Options to pass to annotation processors
`nocompile`	Do not compile source files to class files
`-print`	Print out a textual representation of the specified types
`-factorypath <path>`	Specify where to find annotation processor factories
`-factory <class>`	Name of `AnnotationProcessorFactory` to use; bypasses default discovery process
`-g`	Generate all debugging info
`-g:none`	Generate no debugging info
`-g:{lines,vars,source}`	Generate only some debugging info
`-nowarn`	Generate no warnings
`-verbose`	Output messages about what `apt` and `javac` are doing
`-deprecation`	Output source locations where deprecated APIs are used
`-sourcepath <path>`	Specify where to find input source files
`-bootclasspath <path>`	Override location of bootstrap class files
`-endorseddirs <dirs>`	Override location of endorsed standards path
`-encoding <encoding>`	Specify character encoding used by source files
`-target <release>`	Generate class files for a specific virtual machine version

It is important when using apt with JAX-WSto specify all of the JAR files in the distributed JAX-WS bundle in the classpath passed to apt. The -sourcepath <path> option must also be provided so that apt and the JAX-WS annotation processor can find all types referenced by a web service endpoint implementation class.

For more information on apt please refer to the apt documentation here.

Ant task

An Ant task for the apt tool is provided with JAX-WS 2.0 EA. The attributes and elements supported by the Ant task are listed below:

<apt
    
  verbose="true|false"
    
  classpath="classpath"
    
  destdir="directory for generated class files"
    
  sourcedestdir="directory for generated source files"
    
  nocompile="true|false"
    
  print="true|false"
    
  factorypath="<path>"
    
  factory="name of AnnotationProcessorFactory to use"
    
  xlistannotationtypes="true|false"
    
  xlistdeclarations="true|false"
    
  xprintaptrounds="true|false"
    
  xprintfactoryinfo="true|false"
    
  xclassesasdecls="true|false"
    
  debug="true|false"
    
  debuglevel="lines|vars|source"
    
  nowarn="true|false"
    
  deprecation="true|false"
    
  bootclasspath="<path>"
    
  extdirs="<path>"
    
  endorseddirs="<path>"
    
  sourcepath="<path>"
    
  encoding="specify character encoding used by source files"
    
  target="generate class files for specific virtual machine version">
    
  <option key="keyname" value="keyvalue"/>
  <source ... > ... </source>
    
  <classpath ... > ... </classpath>
</apt>

Attribute	Description	Command line
`verbose`	Output messages about what the compiler is doing	`-verbose`
`classpath`	Specify where to find user class files and annotation processor factories	`-classpath` or `-cp`
`destdir`	Specify where to place processor and `javac` generated class files	`-d <path>`
`sourcedestdir`	Specify where to place processor generated source files	`-s <path>`
`nocompile`	Do not compile source files to class files	`-nocompile`
`print`	Print out a textual representation of the specified types	`-print`
`factorypath`	Specify where to find annotation processor factories	`-factorypath <path>`
`factory`	Name of the `AnnotationProcessorFactory` to use; bypasses default discovery process	`-factory <class>`
`xlistannotationtypes`	List the found annotation types	`-xlistannotationtypes`
`xlistdeclarations`	List specified and included declarations	`-xlistdeclarations`
`xprintaptrounds`	Print information about initial and recursive `apt` rounds	`-xprintaptrounds`
`xprintfactoryinfo`	Print information about which annotations a factory is asked to process	`-xprintfactoryinfo`
`xclassesasdecls`	Treat both class and source files as declarations to process	`-xclassesasdecls`
`debug`	Generate all debugging info	`-g`
`debuglevel`	Debug level: lines, vars, sources	`-g:{lines,vars,source}`
`nowarn`	Generate no warnings	`-nowarn`
`deprecation`	Output source locations where deprecated APIs are used	`-deprecation`
`bootclasspath`	Override location of bootstrap class files	`-bootclasspath <path>`
`extdirs`	Override location of installed extensions	`-extdirs <dirs>`
`endorseddirs`	Override location of endorsed standards path	`-endorseddirs <dirs>`
`sourcepath`	Specify where to find input source files	`-sourcepath <path>`
`encoding`	Specify character encoding used by source files	`-encoding <encoding>`
`target`	Generate class files for a specific virtual machine version	`-target <release>`
`option`	Specify options to pass to annotation processors	`-Akey=value;`

The list of source files to be processed are specified via a nested <source> 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="apt" classname="com.sun.tools.ws.ant.Apt">

 <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.

Examples

<apt    
    destdir="${build.classes.home}"
    sourcedestdir="${build.classes.home}"
    sourcepath="${basedir}/src">
    <classpath refid="jaxws.classpath"/>
    <source dir="${basedir}/src" includes="*.java"/>
    </source>
</apt>

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 apt rounds. The classpath is a reference to a path-like structure jaxws.classpath, defined elsewhere in the build environment.

<apt
    debug="true"
    verbose="true"
    destdir="${build.classes.home}"
    sourcedestdir="${build.classes.home}"
    sourcepath="${basedir}/src">
    <classpath refid="jaxws.classpath"/>
    <option key="r" value="${build.home}"/>
    <source dir="${basedir}/src">
      <include name="**/server/*.java"/>
    </source>
</apt>

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, and passes the -Dr=${build.home} option to the annotation processor(s). ${basedir}/src is the directory used to search for source files for multiple apt 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 apt process using the default java executable.