+

Search Tips   |   Advanced Search

wsgen command for JAX-WS applications

The wsgen command-line tool generates the necessary artifacts required for 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 we are starting from a service endpoint implementation, use the wsgen tool to generate the required JAX-WS artifacts.

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.

WAS provides 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 in WAS traditional.The xjc and schemagen commands are located in the app_server_root\jaxb\bin\ directory in Liberty profile. On some occasions, the artifacts generated by both the tooling provided by WAS 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 WAS environment and to take advantage of the features that may be only supported in WAS. To take advantage of JAX-WS and JAXB V2.2 tooling, use the tools provided with the application server located in...

bprac

Use the wsimport, wsgen, schemagen and xjc command-line tools with both Liberty and the WAS traditional of the application server.

The wsgen tool accepts a properly annotated service endpoint implementation using the @WebService annotation as input and generates the following artifacts:

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, we can invoke these JAX-WS tools from within the Ant build environments for WAS traditional. 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.

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

With JAX-WS applications, the wsgen command-line tool might not locate shared class files in the full profile. We can specify the location of these class files using the com.ibm.websphere.webservices.WSDL_Generation_Extra_ClassPath custom property. See documentation about the Java virtual machine custom properties.


Syntax

The command-line syntax is:

(Windows) 

app_server_root\bin\wsgen.bat [options] service_implementation_class
(UNIX) 
app_server_root/bin/wsgen.sh [options] service_implementation_class
(iSeries) 
app_server_root/bin/wsgen [options] service_implementation_class


Parameters

The service_implementation_class name is the only parameter required. The following parameters are optional for the wsgen command:

-classpath <path>

Location of the service implementation class.

-cp <path>

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

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

Display the help menu.

-keep

Specifies whether to keep the generated source files.

-r <directory>

Only used with the -wsdl parameter. Specifies where to place the generated WSDL file.

-s <directory>

Directory to place the generated source files.

-verbose

To output messages about what the compiler is doing.

-version

Prints the version information. If we 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 is soap 1.1. The Xsoap 1.2 value is not standard and is only used with the -extension option.

-servicename <name>

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

Only used with the -wsdl option. Specifies a wsdl:port name to be generated in the WSDL file. For example, 
-portname "{http://mynamespace/}MyPort"


Related:

  • Development and assembly tools
  • Exposing methods in SEI-based JAX-WS web services
  • Developing JAX-WS web services with annotations
  • Generate Java artifacts for JAX-WS applications
  • Implement web services applications with JAX-WS
  • wsimport command for JAX-WS applications
  • Java virtual machine custom properties
  • Web services specifications and APIs
  • JAX-WS API documentation
  • JAX-WS 2.2 Tools Reference implementation