# wsimport Ant Task

## `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)

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

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

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

Attribute | Description | Required | Command line
`wsdl` | WSDL file. | Yes. | WSDL location
`destdir` | Specify where to place output generated classes. | No. Defaults to current working directory. | `-d`
`sourcedestdir` | Specify where to place generated source code files, keep is turned on with this option. | No. Defaults to current working directory. | `-s`
`encoding` | Set the encoding name for generated sources, such as UTF-8. | No. Defaults to platform default. | `-encoding`
`keep` | Keep generated source code files, turned on with `sourcedestdir` option. | No. Defaults to false. | `-keep`
`verbose` | Output JAX-WS RI version and messages about what the compiler is doing | No. Defaults to false. | `-verbose.`
`binding` | Specify external JAX-WS or JAXB binding files or additional schema files (Each `<file>` must have its own `-b`). | No. No defaults. | `-b`
`extension` | allow 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`
`wsdllocation` | The 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`
`clientJar` | Creates the jar file of the generated artifacts along with the WSDL metadata required for invoking the web service. | No. | `-clientJar`
`catalog` | Specify 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 users-guide-catalog. | No. No defaults. | `-catalog`
`package` | Specifies the target package. | No. It default to the WSDL/Schema targetNamespace to package mapping as defined by the JAXB 2.1 spec. | `-p`
`target` | Generate 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`
`quiet` | Suppress `wsimport` output. | No. Defaults to false. | `-quiet`
`fork` | Used to execute wsgen using forked VM. | No. Defaults to false. | None.
`failonerror` | Indicates whether errors will fail the build. | No. Defaults to true. | None.
`xadditionalHeaders` | Map headers not bound to request or response message to Java method parameters. | No. Defaults to false. | `-XadditionalHeaders`
`xauthfile` | File 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`
`xdebug` | Print debug information. | No. Defaults to false. | `-Xdebug`
`xdisableAuthenticator` | Disables Authenticator used by JAX-WS RI, `-Xauthfile` option will be ignored if `-XdisableAuthenticator` is set. | No. Defaults to false. | `-XdisableAuthenticator`
`xNoAddressingDatabinding` | Enable binding of W3C EndpointReferenceType to Java. | No. Defaults to false. | `-Xno-addressing-databinding`
`xnocompile` | Do not compile generated Java files. | No. Defaults to false. | `-Xnocompile`

### Nested Elements

`wsimport` supports the following nested element parameters.

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

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

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

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

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

#### xmlcatalog

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

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

## `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 users-guide-wsdl-customization.