# Java TM API for XML Web Services
(JAX-WS)
APT

Specification Version: 2.2
Implementation Version: 2.2.5

- Overview
- Wsimport
- Wsimport Ant Task
- Wsgen
- Wsgen Ant Task
- Apt

## Apt

The `apt` tool provides 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 `apt` tool generates the portable artifacts used in JAX-WS services.

To run on JDK 6 follow these instructions.

### Command-line

### Syntax

    apt <apt and javac options> <source files>

The following table lists the `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-WS to 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 RI 2.2.5. 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"
      deprecaption="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=""
        sourcedestdir=""
        sourcepath="/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/src">
        <classpath refid="jaxws.classpath"/>
        <source dir="/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/src" includes="*.java"/>
        </source>
    </apt>

The above example processes the Java source files in the `/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/src` directory and generates the source and class files in ``. `/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/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=""
        sourcedestdir=""
        sourcepath="/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/src">
        <classpath refid="jaxws.classpath"/>
        <option key="r" value="/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/build"/>
        <source dir="/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/src">
          <include name="**/server/*.java"/>
        </source>
    </apt>

The above example processes the Java source files in `/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/src/**/server`, generates the source and class files in ``, compiles with debug information on, prints a message about what the compiler is doing, and passes the `-Dr=/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/build` option to the annotation processor(s). `/net/jws-sparc.us.oracle.com/bld1/BUILD_AREA/jaxws2.2.5/ws/jaxws2.2.5fcs/jaxws-ri/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.