Table of Contents
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.
For more information on this tool please see: apt.
The wsimport tool generates JAX-WS portable artifacts used in JAX-WS clients and services. The tool reads a WSDL and generates all the required artifacts for web service development, deployment, and invocation.
For more information on this tool please see: wsimport.
The wsgen tool reads a service endpoint implementation class and generates all of the portable artifacts for a JAX-WS web service..
For more information on this tool please see: wsgen.
Copy
JAXWS_HOME/lib/jaxws-api.jar
to
$JDK6_HOME/jre/lib/endorsed
directory
Copy
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.
The following lists the process to create a web service starting from Java sources, classes, and a WSDL file (server side):
Starting from Java sources:
Use apt to generate the artifacts required by the JAX-WS specification.
Package the web.xml
,
sun-jaxws.xml
, service endpoint
interface and implementation class, value types, and
generated classes, if any, into a WAR file,
Deploy the WAR to a web container.
Starting from Java classes:
Use wsgen to generate portable artifacts.
Package the web.xml
,
sun-jaxws.xml
, service endpoint
interface and implementation class, value types, and
generated classes, if any, into a WAR file,
Deploy the WAR to a web container.
Starting from a WSDL file:
Use wsimport to generate portable artifacts.
Implement the service endpoint.
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.
Deploy the WAR to a web container.
The following lists the process to invoke a web service (client side):
Starting from deployed web service's WSDL
Use wsimport to generate the client-side artifacts.
Implement the client to invoke the web service.
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.2.7 also provides a wsimport Ant Task.
Solaris/Linux
JAXWS_HOME/bin/wsimport.sh -help
Windows
JAXWS_HOME\bin\wsimport.bat -help
To run on JDK 6 follow these Running on JDK6.
wsimport
[OPTION]... <WSDL>
The following table lists the wsimport options:
Option | Description |
---|---|
-d <directory> | Specify where to place generated output files. |
-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. |
-catalog | Specify 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. |
-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 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. |
-verbose | Output messages about what the compiler is doing. |
-version | Print version information. |
-fullversion | Print 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. |
-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. |
-XdisableAuthenticator | Disables Authenticator used by JAX-WS RI, -Xauthfile option will be ignored if -XdisableAuthenticator is set. |
-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 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.
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.
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)
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.
<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" 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="..."/> <xmlcatalog refid="another catalog file"/> </wsimport>
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 supports the following parameter attributes.
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 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 |
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 . | 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 |
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.
The xmlcatalog element is used to resolve entities when parsing schema documents.
To run on JDK 6 follow these Running on JDK6.
<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.
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.2.7 also provides a wsgen Ant Task.
Solaris/Linux
JAXWS_HOME/bin/wsgen.sh -help
Windows
JAXWS_HOME\bin\wsgen.bat -help
To run on JDK 6 follow these Running on JDK6.
wsgen
[OPTION]... <SEI>
The following table lists the wsgen options:
Option | Description |
---|---|
-classpath
<path> | Specify where to find input class files. |
-cp <path> | Same as -classpath
<path> . |
-d <directory> | Specify where to place generated output files. |
-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. |
-keep | Keep 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. |
-verbose | Output messages about what the compiler is doing. |
-version | Print version information. Use of this option will ONLY print version information. Normal processing will not occur. |
-fullversion | Print 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
-servicename "{http://mynamespace/}MyService" |
-portname
<name> | Used only in conjunction with the
-portname "{http://mynamespace/}MyPort" |
-inlineSchemas | Used to inline schemas in a generated wsdl.
Must be used in conjunction with the
-wsdl option. |
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.
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.
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.
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" <classpath refid="..."/> </wsgen>
Attribute | Description | Command line |
---|---|---|
sei | Name of the service endpoint implementation class. | SEI |
destdir | Specify where to place output generated classes. | -d |
classpath | Specify where to find input class files. | -classpath |
cp | Same as -classpath . | -cp |
resourcedestdir | Used only in conjunction with the -wsdl option. Specify where to place generated resource files such as WSDLs. | -r |
sourcedestdir | Specify where to place generated source files. | -s |
encoding | Set the encoding name for generated sources, such as UTF-8. | -encoding |
keep | Keep generated files. | -keep |
verbose | Output JAX_WS RI version and messages about what the compiler is doing. | -verbose |
genwsdl | Specify that a WSDL file should be generated. | -wsdl |
protocol | Used 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. | -wsdl:soap11 |
servicename | Used in conjunction with the genwsdl
option. Used to specify a particular
servicename="{http://mynamespace/}MyService" | -servicename |
portname | Used in conjunction with the genwsdl
option. Used to specify a particular
portname="{http://mynamespace/}MyPort" | -servicename |
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. | -extension |
inlineSchemas | Used to inline schemas in a generated wsdl.
Must be used in conjunction with the
wsdl option. | -inlineSchemas |
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="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.
To run on JDK 6 follow these Running on JDK6.
<wsgen resourcedestdir="${wsdl.dir}" sei="fromjava.server.AddNumbersImpl"> <classpath refid="compile.classpath"/> </wsgen>
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 Running on JDK6.
apt
[APT_AND_JAVAC_OPTION]... <SOURCE_FILE>...
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.
An Ant task for the apt tool is provided with JAX-WS RI 2.2.7.
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.
To run on JDK 6 follow these Running on JDK6.
<apt destdir="${build.classes.home}" sourcedestdir="${build.classes.home}" sourcepath="${basedir}/src"> <classpath refid="jaxws.classpath"/> <source dir="${basedir}/src" includes="*.java"/> </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.