Generate Java artifacts for JAX-WS applications

WAS v8.5 > Develop applications > Develop web services > Develop JAX-WS web services (bottom-up)
Generate Java artifacts for JAX-WS applications

Use JAX-WS tools to generate the necessary JAX-WS and JAXB Java artifacts that are needed for JAX-WS web services applications when starting from JavaBeans or enterprise beans components.
To develop a JAX-WS web service application, first develop a service endpoint interface (SEI) implementation that explicitly or implicitly describes the SEI.
When using a bottom-up approach to develop JAX-WS web services, use the wsgen command-line tool on the existing service endpoint implementation. The wsgen tool processes a compiled service endpoint implementation class as input and generates the following portable artifacts:

JAXB classes required to marshal and unmarshal the message contents.
a Web Services Description Language (WSDL) file if the optional -wsdl argument is specified.

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.

Best practice: WAS provides JAX-WS and JAXB tooling. The wsimport, wsgen, schemagen and xjc command-line tools are located in...
app_server_root/bin
Similar tooling is provided by the Java SE Development Kit (JDK) 6. 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 the app_server_root\bin\ directory.
You are not required to develop a WSDL file when developing JAX-WS Web services using the bottom-up approach of starting with JavaBeans. The use of annotations provides all of the WSDL information necessary to configure the service endpoint or the client. The application server supports WSDL 1.1 documents that comply with Web Services-Interoperability (WS-I) Basic Profile 1.1 specifications and are either Document/Literal style documents or RPC/Literal style documents. Additionally, WSDL documents with bindings that declare a USE attribute of value LITERAL are supported while the value, ENCODED, is not supported. For WSDL documents that implement a Document/Literal wrapped pattern, a root element is declared in the XML schema and is used as an operation wrapper for a message flow. Separate wrapper element definitions exist for both the request and the response.
To ensure the wsgen command does not miss inherited methods on a service endpoint implementation bean, either add the @WebService annotation to the desired superclass or we can override the inherited method in the implementation class with a call to the superclass method.
Although a WSDL file is typically optional when developing a JAX-WS service implementation bean, it is required if your JAX-WS endpoints are exposed using the SOAP over JMS transport and you are publishing your WSDL file. If you are developing an enterprise JavaBeans service implementation bean that is invoked using the SOAP over JMS transport, and to publish the WSDL so the published WSDL file contains the fully resolved JMS endpoint URL, then have wsgen tool generate the WSDL file by specifying the -wsdl argument. In this scenario, you must package the WSDL file with the web service application.
In addition to using the tools from the command-line, we 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.

Locate your service endpoint implementation class file.

Run the wsgen command to generate the portable artifacts. The wsgen tool is located in the app_server_root/bin/ directory.

app_server_root\bin\wsgen.bat [options] service_implementation_class

app_server_root/bin/ wsgen.sh [options] service_implementation_class

(Optional) Use the following options with the wsgen command:

Use the -verbose option to see a list of generated files along with additional informational messages.

Use the -keep option to keep generated Java files.

Use the -wsdl option to generate a WSDL file. If you are developing a service implementation bean that will be invoked using the HTTP transport, then the WSDL file generated by the wsgen command-line tool during this step is optional. However, if you are developing a service implementation bean that will be invoked using the SOAP over JMS transport, then the WSDL file generated by the wsgen tool during this step is required in subsequent developing JAX-WS applications steps, so it is not optional.

Read about wsgen to learn more about this command and additional options that we can specify.

Results

You have the required Java artifacts to create a JAX-WS web service.
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 that we have classes 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.

Beginning with Sun and HP JDK v1.6 containing JAX-WS tooling v2.1.6, the behavior of the JAX-WS runtime environments and tooling has changed in how it determines which methods are exposed as web services operations in an effort to better adhere to the JAX-WS specifications. Applications that might be affected by this change include web services applications that do not specify a WSDL file or an explicit service endpoint interface (SEI). To learn more, see the exposing methods in SEI-based JAX-WS web services information. gotcha
With JAX-WS applications, the wsgen command-line tool might not locate shared class files. We 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.

Example

The following example demonstrates how to use the wsgen command to process the service endpoint implementation class to generate JAX-WS artifacts. This example EchoService service implementation class uses an explicit JavaBeans service endpoint.
Copy the sample EchoServicePortTypeImpl service implementation class file and the associated EchoServicePortType service interface class file into a directory. The directory must contain a directory tree structure that corresponds to the com.ibm.was.wssample.echo package name for the class file.
/* This is a sample EchoServicePortTypeImpl.java file.    */
package com.ibm.was.wssample.echo;


@javax.jws.WebService(serviceName = "EchoService", endpointInterface = 
"com.ibm.was.wssample.echo.EchoServicePortType", 
targetNamespace="http://com/ibm/was/wssample/echo/",
portName="EchoServicePort")

public class EchoServicePortTypeImpl implements EchoServicePortType {

 public EchoServicePortTypeImpl() {
 }

 public String invoke(String obj) {
  System.out.println(">> JAXB Provider Service: 
Request received.\n");
  String str = "Failed";
  if (obj != null) {
   try {
    str = obj;
   } catch (Exception e) {
    e.printStackTrace();
   }
  }
  return str;

 }
} 
/* This is a sample EchoServicePortType.java file.    */
package com.ibm.was.wssample.echo;

import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.xml.ws.RequestWrapper;
import javax.xml.ws.ResponseWrapper;


@WebService(name = "EchoServicePortType", targetNamespace = 
"http://com/ibm/was/wssample/echo/", 
 wsdlLocation="WEB-INF/wsdl/Echo.wsdl")

public interface EchoServicePortType {


    /**
     * 
     * @param arg0
     * @return
     *     returns java.lang.String
     */
    @WebMethod
    @WebResult(name = "response", targetNamespace = 
    "http://com/ibm/was/wssample/echo/")
    @RequestWrapper(localName = "invoke", targetNamespace = 
    "http://com/ibm/was/wssample/echo/", 
     className = "com.ibm.was.wssample.echo.Invoke")
    @ResponseWrapper(localName = "echoStringResponse", 
     targetNamespace = "http://com/ibm/was/wssample/echo/", 
     className = "com.ibm.was.wssample.echo.EchoStringResponse")
    public String invoke(
        @WebParam(name = "arg0", targetNamespace = 
        "http://com/ibm/was/wssample/echo/")
        String arg0);
}
Run the wsgen command from the app_server_root\bin\ directory. The -cp option specifies the location of the service implementation class file. The -s option specifies the directory for the generated source files. The -d option specifies the directory for the generated output files. When using the -s or -d options, first create the directory for the generated output files.
app_server_root\bin\wsgen.bat -wsdl -s c:\generated_source\ -cp c:\my_application\classes\ 
com.ibm.was.wssample.echo.EchoServicePortTypeImpl -verbose -d c:\generated_artifacts\
Run the wsgen command; for example:
app_server_root/bin/wsgen.sh -wsdl -s c:/generated_source/ -cp c:/my_application/classes/ 
com.ibm.was.wssample.echo.EchoServicePortTypeImpl -verbose -d c:/generated_artifacts/
After generating the Java artifacts using the wsgen command, the following files are generated:
/generated_source/com/ibm/was/wssample/echo/EchoStringResponse.java
/generated_source/com/ibm/was/wssample/echo/Invoke.java
/generated_artifacts/EchoService.wsdl
/generated_artifacts/EchoService_schema1.xsd
/generated_artifacts/com/ibm/was/wssample/echo/EchoStringResponse.class
/generated_artifacts/com/ibm/was/wssample/echo/Invoke.class
The EchoStringResponse.java and Invoke.java files are the generated Java class files. The compiled versions of the generated Java files are EchoStringResponse.class and Invoke.class files. The EchoService.wsdl and EchoService_schema1.xsd files are generated because the -wsdl option was specified.

Complete the implementation of your JAX-WS web service application.

Subtopics

Directory conventions
References in product information to app_server_root, profile_root, and other directories imply specific default directory locations. This article describes the conventions in use for WAS.
wsgen command for JAX-WS applications
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.
Map between Java language, WSDL and XML for JAX-WS applications
Data for JAX-WS applications flows as extensible Markup Language (XML). JAX-WS applications use mappings to describe the data conversion between the Java language and extensible Markup Language (XML) technologies, including XML Schema, Web Services Description Language (WSDL) and SOAP that are supported by the application server.

Related concepts:

JAX-WS
WSDL
Development and assembly tools

Related

Implement web services applications with JAX-WS
Exposing methods in SEI-based JAX-WS web services
Develop JAX-WS web services with annotations
Completing the JavaBeans implementation for JAX-WS applications
Completing the EJB implementation for JAX-WS applications
Use SOAP over JMS to transport web services

Reference:

Java virtual machine custom properties

Related information:

Web services specifications and APIs

JAX-WS API documentation

+
Search Tips | Advanced Search