# Jakarta XML Web Services
wsimport

Specification Version: 2.2

## wsimport

The `wsimport` tool generates Jakarta XML Web Services 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)

These artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation to be deployed.

wsimport tool can be launched using the command line script wsimport.sh (Unix) or wsimport.bat (windows). There is also and ant task to import and compile the wsdl, see the details below.

### Command-line

### Syntax

    wsimport [options] <wsdl>

The following table lists the `wsimport` options.``````

Table 1-1 wsimport Options

Option | Description
--- | ---
`-d <directory>` | Specify where to place generated output files
`-B <jaxbOption>` | Pass this option to JAXB schema compiler
`-b <path>` | Specify external Jakarta XML Web Services or Jakarta XML Binding (JAXB) binding files (Each `<file>` must have its own `-b`)
-catalog | Specify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Please read the XML Entity and URI Resolvers document or see wsimport_catalog sample.
`-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
`-help` | Display help
`-httpproxy:<host>:<port>` | Specify an HTTP proxy server (port defaults to 8080)
`-keep` | Keep generated files
`-p` | 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 files
`-verbose` | Output messages about what the compiler is doing
`-version` | Print version information
`-wsdllocation <location>` | `@WebService.wsdlLocation` and `@WebServiceClient.wsdlLocation` value
`-target` | `Generate code as per the given Jakarta XML Web Services specification version. Version 2.0 will generate compliant code for Jakarta XML Web Services 2.0 spec.`
`-quiet` | `Suppress wsimport output`
`-XadditionalHeaders` | `Map the headers not bound to request or response message to Java method parameters`
`-Xauthfile` | `file to carry authorization information in the format http://username:password@example.org/stock?wsdl. Default value is $HOME/.metro/auth`
`-Xdebug` | `Print debug information`
`-Xno-addressing-databinding` | `Enable binding of W3C EndpointReferenceType to Java`
`-Xnocompile` | `Do not compile generated Java files`
`-XdisableSSLHostnameVerification` | `Disbales the SSL Hostname verification while fetching the wsdls.`

Multiple Jakarta XML Web Services and Jakarta XML Binding 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 Jakarta XML Web Services and Jakarta XML Binding binding files can be found in the customization documentation.

### Ant task

An Ant task for the `wsimport` tool is provided along with the tool. The attributes and elements supported by the Ant task are listed below:

       <wsimport
          wsdl="..."
          destdir="directory for generated class files"
          sourcedestdir="directory for generated source files"
          keep="true|false"
          extension="true|false"
          verbose="true|false"
          wsdlLocation="..."
          catalog="catalog file"
          package="package name"
          target="..."
          binding="..."
          quiet="true|false"
          xadditionalHeaders="true|false"
          xauthfile="authorization file"
          xdebug="true|false"
          xNoAddressingDatabinding="true|false"
          xnocompile="true|false"
          <binding dir="..." includes="..."/>
          <arg value="..."/>
          <xjcarg value="..."/>
          <xmlcatalog refid="another catalog file"/>
       </wsimport>

Attribute | Description | Command line
`wsdl` | WSDL file | WSDL
`destdir` | Specify where to place output generated classes | `-d`
    sourcedestdir
| Specify where to place generated source files, keep is turned on with this option | `-s`
`keep` | Keep generated files, tunred on with sourcedestdir option | `-keep`
`verbose` | Output messages about what the compiler is doing | `-verbose`
`binding` | Specify external Jakarta XML Web Services or Jakarta XML Binding binding files | `-b`
`extension` | allow vendor extentions (funcionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations | `-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 | `-wsdllocation`
`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 wsimport_catalog sample. | `-catalog`
`package` | Specifies the target package | `-p`
`target` | Generate code as per the given JAXWS specification version. version 2.0 will generate compliant code for JAXWS 2.0 spec. | `-target`
`quiet` | Suppress wsimport output | `-quiet`
`xadditionalHeaders` | Map headers not bound to request or response message to Java method parameters | `-XadditionalHeaders`
`xauthfile` | File to carry authorization information in the format http://username:password@example.org/stock?wsdl. | `-Xauthfile`
`xdebug` | Print debug information | `-Xdebug`
`xNoAddressingDatabinding` | Enable binding of W3C EndpointReferenceType to Java | `-Xno-addressing-databinding`
`xnocompile` | Do not compile generated Java files | `-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 Jakarta XML Binding (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.

#### xmlcatalog

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

The ```binding` attributes is like a path-like structure and can also be set via nested `` `<binding>` elements, respectively. Before this task can be used, 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 Jakarta XML Web Services tools.

### 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}"
          wsdl="AddNumbers.wsdl">
          <binding dir="${basedir}/etc" includes="custom.xml"/>
      </wsimport>

The above example generates portable artifacts for `AddNumbers.wsdl`, stores `.java` files in the `${source.dir}` directory, stores `.class` files in the `${build.classes.home}` directory.

### Summary of Changed and Removed wsimport ant attributes

base replaced by destdir
sourceBase is replaced by sourcedestdir
wsdlFile is replaced by wsdl
httpProxy is removed. Use ant's setproxy task instead for proxy configuration.
version is removed