Creating a web service from a Java bean using the IBM WebSphere JAX-WS runtime environment

The web service wizard assists you in creating a new web service, configuring it for deployment, and deploying the web service to a server. Once your web service is deployed, the wizard assists you in generating the client proxy and sample application to test the web service. When you have completed testing, you can publish your web service to a UDDI Business Registry using the Export wizard.

Before you begin

  • If you are using WebSphere® Application Server, it is strongly suggested that you start the server before running the web service wizard because it may take several minutes to start the WebSphere Application Server depending on the speed of your computer. To start the server, select it in the Servers view (Window > Show View > Servers), right-click and select Start.
  • Create or import a bean into the Java™ source folder of a web project or Java project. To import, select the Java Resources: src folder, and from the File menu select Import > General > File System and browse to where your package is.

About this task

To create a web service from a bean using the IBM® WebSphere JAX-WS runtime environment:

Procedure

  1. Switch to the Java EE perspective (Window > Open Perspective > Java EE).
  2. In the Enterprise Explorer view, select the bean that you created or imported into the source folder of your Web project.
  3. Click File > New > Other. Select Web Services in order to display the various web service wizards. Select the Web Service wizard. Click Next.
  4. In the Web Services page page, select Bottom up Java bean Web service as your web service type. You can optionally choose to do the following:
    1. Select the stages of web services development that you want to complete using the slider. This will set several default values on the remaining wizard panels:
      • Develop: this will develop the WSDL definition and implementation of the web service. This includes such tasks as creating the modules which will contain the generated code, WSDL files, deployment descriptors, and Java files when appropriate.
      • Assemble: this ensures the project that will host the web service or client gets associated to an EAR when required by the target application server.
      • Deploy: this will create the deployment code for the service.
      • Install: this will install and configure the Web module and EARs on the target server. If any changes to the endpoints of the WSDL file are required they will be made in this stage.
      • Start: this will start the server once the service has been installed on it.
      • Test: this will provide various options for testing the service, such as using the Generic Services Client, Web Service Explorer or sample JSPs.
    2. Select your Server runtime: the default server is displayed. If you want to deploy your service to a different server click the server link and specify a different server.
      This task supports the following server runtime environments:
      • WebSphere Application Server V7.0 or later
      • WebSphere Application Server Liberty V8.5.5
    3. Select your Web service runtime: the default runtime is displayed. To deploy your service to the IBM WebSphere JAX-WS runtime click the runtime link and select it in the window that opens.
    4. Select the Service project and Service EAR project: the project selected in your workspace is displayed. Only web projects with the Java 5.0, Java 6.0, or Java 7.0 facet enabled are supported. To select a different project and EAR click on the project link, or enter a name and allow the wizard to create a project for you.
      Ensure that the project selected as the Client Web Project is different from the Service Web Project, or the service will be overwritten by the client's generated artifacts. For JAX-WS web services, the server and client projects can share the same EAR.
    5. If you want to create a client, select the type of proxy to be generated and repeat steps 1 through 4 for the client.
      The client can be created later using the steps outlined in: Generating a web service client from a WSDL document using the IBM WebSphere JAX-WS runtime environment
    6. Monitor the Web service: this will send the web service traffic through the TCP/IP Monitor, which allows you to watch the SOAP traffic generated by the web service and to test this traffic for WS-I compliance. Alternately you can manually set up a TCP/IP monitor as described in Using the TCP/IP Monitor to test web services.
  5. WebSphere JAX-WS Bottom Up Web Service Configuration:
    • Delegate class name: Enter the class name of the delegate Java implementation or accept the default. The delegate class is a wrapper that contains all the methods from the Java bean as well as the JAX-WS annotation the runtime recognizes as a web service. It is generated into the same package as the original bean.
    • Java to WSDL mapping style: The style defines encoding style for messages sent to and from the web service. The parameter style determines whether the method's parameters represent the entire message body or whether parameters are elements wrapped inside a top-level element named after the operation. The valid combinations are RPC, Document/Wrapped, or Document/Bare.
    • Generate @WebParam annotations for method parameters: If you select this check box, the parameters in a method declaration is going to have the @WebParam annotation set for the respective arguments. The @WebParam annotation customizes the mapping of an individual parameter to a web service message part and XML element. For more details about @WebParam annotation, search for javax.jws.WebParam in the JAX-WS annotations topic available in the WebSphere Application Server documentation.
      Tip: You can enable this option by default in the Preference page by going to the toolbar and selecting Window > Preferences > WebSphere > JAX-WS Code Generation. Select Generate @WebParam annotations for method parameters check box under the Bottom Up section.
    • Enable SOAP 1.2 binding: If you do not select this, SOAP 1.1 bindings will be used. For additional information on the differences between SOAP 1.1 and 1.2, refer to: SOAP Overview
    • Enable MTOM support: If you select this check box the SOAP Message Transmission Optimization Mechanism will be enabled to optimize the transmission of binary content. For more information on MTOM refer to: MTOM Overview
    • Generate WSDL file into the project: Because the annotations in the delegate class are used to tell the runtime that the bean is a web service, a static WSDL file is no longer generated into your project automatically. The runtime can dynamically generate a WSDL file from the information in the bean. Select this to generate a static WSDL file for the web service. This is a convenient option if you plan to create the client at a later time or publish the WSDL for other users. You can configure the WSDL using the next page of the wizard.
    • Generate Web Service Deployment Descriptor: For JAX-WS web services deployment information is generated dynamically by the runtime; static deployment descriptors are no longer required. Selecting this checkbox will generate them.
    • Allow vendor extensions: If you select this check box, the -extension option is added to the wsgen or wsimport command. The -extension option specifies whether to enable or accept 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. For details, see wsgen command for JAX-WS applications and wsimport command for JAX-WS applications topics available in the WebSphere Application Server documentation.
    Note: If the bean already has a @javax.jws.WebService annotation, most of the fields on this page will be disabled because the wizard does not need to generate a delegate bean for you. You will only be able to select to generate a WSDL file. If you have added only the @javax.jws.WebService to your Java bean and want to enable other options such as SOAP 1.2 binding or MTOM, you should exit the wizard and either remove the annotation or proceed to create the web service using the annotations documentation. The wizard will not allow you to append new annotations to a pre-existing partially annotated bean.
  6. WebSphere JAX-WS WSDL Interface Configuration page:
    If on the previous page you selected to generate a WSDL file, this page will display, allowing you to configure the generated WSDL file. You can configure the following:
    • WSDL target namespace
    • WSDL service name
    • WSDL port name
  7. Test Web Service page: If you selected to test the web service, select the test facility for the generated web service and click Launch. This will open the web service in the Web Services Explorer or Generic Services Client. Select the operation you want to test, enter the required information, and click Go. The result will display in the Status pane. Click Next.
  8. WebSphere JAX-WS Web Services Client Configuration page: if you have selected to generate a client, you can specify the following options for it on this page:
    • Output folder: This is the location where the client code will be generated
    • Target package: The web services client wizard generates a number of Java files. By default it will create a package name based on the namespace specified in the WSDL file. To override this default behavior you can specify your own package name.
    • Generate portable client: Selecting this checkbox would allow you to move your web service client code from one machine to another or from one instance of WebSphere Application Server to another. If this option is selected, the WSDL document and all the XML Schema and other WSDL documents that it depends upon will be copied into the client project under WEB-INF/wsdl and a file:relativeURL pointing to this copy will then be injected into the JAX-WS Service class's static initialization block.
    • Enable asynchronous invocation for generated client: If you select to enable an asynchronous client, for each method in the web service two additional methods will be created. These are polling and callback methods which allow the client to function asynchronously.
    • Specify JAX-WS or JAXB binding files: If you have created JAX-WS or JAXB custom binding files, select this check box to use them to create the web service client. If this is selected the next page of the wizard will allow you to browse to the custom binding declaration files.
    • Customize client proxy class name: Select this check box if you want to change the default port name to service implementation class name mapping
  9. Custom Binding Declarations page: If you have selected to specify JAX-WS or JAXB binding files you can browse to the files on this page.
  10. Proxy Generation Configuration page: For each port defined, you can enter a name for the proxy class or accept the default.
  11. Web Service Client Test page:
    • Test the generated proxy: If selected, the sample client will be launched in a Web browser enabling you to test the functionality.
    • Select your test facility.
    • Folder: If you selected to test the proxy through a JSP, you can select the folder where the JSP will be located, and you can select the methods that will be included in the JSP.
    • Methods: Select the methods to expose. If you selected to enable asynchronous invocation, the asynchronous methods should be listed as well.
    • Run test on server: this will start the server for you automatically.

Results

After the web service has been created, the following may occur depending on the options you selected:
  • If you have selected to test the generated proxy using web service JSPs, the proxy is launched in a Web browser at the following URL: http://localhost:port/WebProjectClient/sampleBeanName/WebServiceName/TestClient.jsp You can use this sample application to test the web service by selecting a method, entering a value for the method, and clicking Invoke. The result of the method will display in the results pane.
  • If you have selected to test the generated proxy using the Universal Test Client, it will be launched in a browser window at a URL similar to the following: http://localhost:port/UTC/preload?object=BeanPackage.BeanServiceProxy. Under Objects, expand the proxy stub to display the methods of the web service. Click the method you want to test, enter a value in the Parameters pane, and click Invoke. The result will be automatically generated.
  • If you have selected to test the web service using the Web Services Explorer, the Explorer will open. Select the operation you want to test, enter the required information, and click Go. The result will display in the Status pane.
Restriction:

When generating a JAX-WS web service from a class file that depends on other classes contained in separate JAR files, the project needs to reference such external jar files either from the Java EE Module Dependencies or from User Libraries. Using Java EE Module dependencies is possible when the jars are contained in the EAR project.

In the case where the jars are part of a Shared Library configured on WebSphere Application Server, then a User Library must be used to configure the project for development before generating the web service. To add a user library to the project:
  1. Right-click the project and click Properties > Java Build Path > Libraries
  2. Click Add Library > User Library > User Libraries
  3. Create a user library, and add your utility jar to it.