The wsgen command-line tool generates
the necessary artifacts required for Java API
for XML Web Services (JAX-WS) applications when starting from Java code. The generated artifacts
are Java 5 compliant, making
them portable across different Java versions
and platforms.
When using a bottoms-up approach to develop JAX-WS web services
and you are starting from a service endpoint implementation, use the wsgen tool
to generate the required JAX-WS artifacts.
Supported configurations: The wsimport, wsgen, schemagen and xjc command-line
tools are not supported on the z/OS® platform.
This functionality is provided by the assembly tools provided with WebSphere® Application Server running on
the z/OS platform. Read about these command-line
tools for JAX-WS applications to learn more about these tools.sptcfg
Best practice: WebSphere Application
Server provides Java API for XML-Based Web Services
(JAX-WS) and Java Architecture for XML Binding
(JAXB) tooling. The wsimport, wsgen, schemagen and xjc command-line
tools are located in the app_server_root\bin\ directory.
Similar tooling is provided by the Java SE
Development Kit (JDK) 6. On some occasions, the artifacts generated
by both the tooling provided by WebSphere Application
Server and the JDK support the same levels of the specifications.
In general, the artifacts generated by the JDK tools are portable
across other compliant runtime environments. However, it is a best
practice to use the tools provided with this product to achieve seamless
integration within the WebSphere Application Server
environment and to take advantage of the features that may be only
supported in WebSphere Application Server. To take advantage
of JAX-WS and JAXB V2.2 tooling, use the tools provided with the application
server that are located in the app_server_root\bin\
directory.bprac
The
wsgen tool accepts a properly annotated
service endpoint implementation using the @WebService annotation as
input and generates the following artifacts:
- any additional Java Architecture
for XML Binding (JAXB) classes that are required to marshal and unmarshal
the message contents.
- a WSDL file if the optional -wsdl argument is
specified. The wsgen tool does not automatically
generate the WSDL file.
When
using JAX-WS V2.2 tools, java.lang.RuntimeException and java.rmi.RemoteException
references and their subclasses are no longer mapped in the WSDL file.
This behavior change complies with the JAX-WS V2.1 specification conformance
rule that is described in section 3.7 of the specification. This conformance
rule specifies that the java.lang.RuntimeException and java.rmi.RemoteException
classes and their subclasses cannot be treated as service-specific
exceptions and mapped in the WSDL file.
In addition to using the tools from the command
line, you can invoke these JAX-WS tools from within the Ant build
environments. Use the com.sun.tools.ws.ant.WsGen Ant
task from within the Ant build environment to invoke the wsgen tool.
To function properly, this Ant task requires that you invoke Ant using
the ws_ant script.
Avoid trouble: The
wsgen command does
not differentiate the XML namespace between multiple XMLType annotations
that have the same @XMLType name defined within different Java packages. When this scenario occurs, the
following error is produced:
Error: Two classes have the same XML type name ....
Use @XmlType.name and @XmlType.namespace to assign different names to them...
This
error indicates you have class names or @XMLType.name values that
have the same name, but exist within different Java packages. To prevent this error, add the
@XML.Type.namespace class to the existing @XMLType annotation to differentiate
between the XML types.
gotcha
With JAX-WS applications, the wsgen command-line
tool might not locate shared class files. You can specify the location
of these class files using the com.ibm.websphere.webservices.wsdl_generation_extra_classpath
custom property. For more information, see the documentation about
the Java virtual machine custom
properties.
Syntax
The command-line syntax is:
app_server_root/bin/wsgen [options] service_implementation_class
Parameters
The service_implementation_class name
is the only parameter that is required. The following parameters are
optional for the wsgen command:
- -classpath <path>
- Specifies the location of the service implementation class.
- -cp <path>
- Specifies the location of the service implementation class. This
parameter is the same as -classpath <path>.
- -d <directory>
- Specifies where to place the generated output files.
- -extension
- Specifies whether to enable custom extensions for functionality
not specified by the JAX-WS specification. Use of the extensions can
result in applications that are not portable or do not interoperate
with other implementations.
- -help
- Displays the help menu.
- -keep
- Specifies whether to keep the generated source files.
- -r <directory>
- This parameter is only used with the -wsdl parameter.
Specifies where to place the generated WSDL file.
- -s <directory>
- Specifies the directory to place the generated source files.
- -verbose
- Specifies to output messages about what the compiler is doing.
- -version
- Prints the version information. If you specify this option, only
the version information is output and normal command processing does
not occur.
- -wsdl [:protocol]
- By default, the wsgen tool does not generate
a WSDL file. This optional parameter causes wsgen to
generate a WSDL file and is typically only used to enable a developer
to review a WSDL file before the endpoint is deployed. The protocol is
optional and specifies the protocol used in the wsdl:binding.
Valid values for protocol are soap 1.1 and Xsoap
1.2. The default value is soap 1.1. The Xsoap
1.2 value is not standard and is only used with the -extension option.
- -servicename <name>
- This parameter is only used with the -wsdl option.
Specifies a wsdl:service name to be generated in
the WSDL file. For example,
-service name "{http://mynamespace/}MyService"
- -portname
- This parameter is only used with the -wsdl option.
Specifies a wsdl:port name to be generated in the
WSDL file. For example,
-portname "{http://mynamespace/}MyPort"