Guidelines: Developing Web Services Topics Introduction Development Approaches Top-Down Development Bottom-Up Development Development Guidelines Deployment Dependencies WS-I Basic Profile Compliance Client Proxy Considerations Resources   Introduction RAD 6.0 provides an extensive set of tools to support the discovery, creation, test, deployment and publishing of Web services. They allow the development of Web services based on to the latest standards and support deployment to multiple run-time environments. The tools also provide many wizards to support and facilitate different development approaches. This document describes the various approaches provided by RAD 6.0 to develop a Web service and discusses development considerations related to Web Service deployment and level of interoperability options.   Development Approaches The Web Services wizards in RAD 6.0 allow you to create a Web service using either a top-down or bottom-up approach. Top down enables you to start with a Web Services Description Language (WSDL) document and generate either a skeleton Java bean or a skeleton Enterprise JavaBean (EJB) that can be used to create a Web service. The Bottom-up approach allows you to create a Web service from an existing Java bean, EJB, Document Access Definition Extender (DADX) file, Uniform Resource Locator (URL) or Web service Deployment Descriptor (ISD) file.   During the creation of a Web service, the wizard optionally allows you to: Test the Web service as soon as it is created using the Web Services Explorer tool. Generate a client proxy that you can use in client applications to access the Web service. Test a client proxy using the Universal Test Client (UTC) tool or a sample JSP application that the tool generates. Publish the Web service to a Universal Description, Discovery and Integration (UDDI) registry using the Web Services Explorer tool. Web services developed in RAD 6.0 must be created in a Web or EJB project and contain artifacts that comply with the following standards: Web Services Definition Language (WSDL) version 1.1 Simple Object Access Protocol (SOAP) version 1.1 (including the Apache SOAP 2.2 and 2.3 implementations) Universal Description, Discovery and Integration (UDDI) version 2.0 Web Services Inspection Language (WSIL) version 1.0 Java API for XML-based Remote Procedure Call (JAX-RPC), also known as JSR-101 JSR-109 and JSR-921(Implementing Enterprise Web Services) Web Services Interoperability (WS-I) Basic Profile 1.0 (optional compliance) WS-Security For more information on these topics see Concepts: Web Services for J2EE. Top-down Development Top-down development allows you to take the abstract definition of a Web service contained in a WSDL document and generate a concrete implementation for it. (Note: RAD 6.0 also provides a wizard to create a WSDL document). The following two approaches are supported: Creating a skeleton Java bean from a WSDL document You can create a skeleton Java bean from a WSDL document and expose it as a Web service. The generated Java bean methods correspond to the operations described the WSDL document and contain a trivial implementation which you can replace. The following considerations apply to this approach and its generated artifacts: You can enter the URI of a WSDL document, or alternatively, that of a WSIL or HTML document pointing to the WSDL file as the source for the Web service. The WSDL file must contain a service element. You can also optionally generate a standardized WSDL reference (WSIL) document for the resulting Web service. The generated Web service must be created in a Web project.   Creating a skeleton EJB from a WSDL document Similar to the one above, this approach allows you to create a skeleton Stateless Session EJB from a WSDL document and expose it a Web service. The methods in the EJB correspond to the operations described the WSDL document and contain a trivial implementation which you can replace. The following considerations apply to this approach and its generated artifacts: This approach can only be used if you select IBM WebSphere v6 as your Web service run-time environment (see Deployment Dependencies) You can enter the URI of a WSDL document, or alternatively, that of a WSIL or HTML document pointing to the WSDL file as the source for the Web service. The WSDL file must contain a service element. You can also optionally generate a standardized WSDL reference (WSIL) document for the resulting Web service. The generated Web service must be created in an EJB project. In addition, a Router project is created to enable the Web service to receive requests over the HTTP transport (Note: The JMS transport is not supported under this approach). The Router project can be a Web or EJB project and can not be the same project as the one containing the Web service but must be in the same containing EAR file. Bottom-up Development The goal of bottom-up development is to expose an existing application component or resource as a Web Service. The various approaches are discussed below. Creating a Web service from a Java bean This approach allows you to select an existing Java bean and exposes its methods as a Web service. The generated artifacts include: WSDL file: This file describes the Web service and has a .wsdl file name extension. You can choose between three styles of WSDL (Document/Literal, RPC/Literal and RPC/Encoded). For the interoperability impact of each option, see WS-I Basic Profile Compliance. Service Endpoint Interface (SEI): This Java interface defines the methods of the Web service. Its file name has a _SEI suffix. Web service Deployment Descriptor: The webservices.xml file specifies the implementation and deployment details of the Web service. JAX-RPC Mapping files: These files define how the Web service's Java elements are mapped to and from WSDL.   Creating a Web service from an EJB You can expose the methods of a Stateless Session bean as a Web service. The generated artifacts are similar to those generated for a Java bean and include a WSDL file, SEI, Web service Deployment Descriptor and JAX-RPC Mapping files. The following considerations apply to this approach and its generated artifacts: The generated Web service must be created in an EJB project. A Router project must be created to enable the Web service to receive requests from clients. If you are using SOAP over HTTP as your transport method, create the Router project as a Web project. Otherwise, if the client is using SOAP over JMS, create it as an EJB project (the JMS Router is implemented as a Message-Driven Bean in this case). The Router and Web Service projects can not be the same but must be contained in the same EAR file. If you are using the SOAP over JMS transport, configure a JMS provider in your server. You also will not be able to use the Web service Explorer to test your Web service.   Creating a Web service from a DADX file This approach enables you to wrap DB2 data accessed through DB2 XML Extender or regular SQL statements inside a Web service. Data accessed through DB2 XML Extender consists of XML documents that are mapped to a DB2 database using a Document Access Definition (DAD) document. The approach's starting point is a DADX file which specifies how to create a Web service using the set of operations defined by regular SQL statements or in a DAD file. The generated artifacts include the standard WSDL file, SEI, Web service Deployment Descriptor and JAX-RPC Mapping files. The following considerations apply to this approach and its generated artifacts: This approach can only be used if you select IBM SOAP as your Web service run-time environment (see Deployment Dependencies). You can optionally generate a DADX file from a combination of one or more SQL statements, stored procedures and DAD files. The DADX file should be contained in a DADX group which defines JDBC connection and other information shared between DADX files within the group. The generated Web service must be created in a Web project.   Creating a Web service from a URL From its URL, you can create a Web service that directly accesses a servlet running on a remote server. The wizard allows you to describe the servlet's interface in terms of ports, operations and parameters and generates a WSDL document describing the resulting Web service. The following considerations apply to this approach and its generated artifacts: This approach can only be used if you select IBM SOAP as your Web service run-time environment (see Deployment Dependencies). Usually, the port corresponds to the domain/host name part of the URL, the operation to the servlet context root and URI part, and the parameters to the servlet's input parameters. The generated Web service must be created in a Web project. There is no Web service to deploy since it is already implemented by the active URL.   Creating a Web service from a Deployment Descriptor (ISD) file When a Web service is deployed, its configuration and run-time attributes are defined in an ISD deployment descriptor file. This file provides information about the service that should be made available to clients by the SOAP run-time environment, for example, URI, methods, implementation classes (JavaBeans and EJBs), serializers and deserializers. You can create a Web service from an ISD file using this available information. This allows you to wrap existing Web service implementations and re-deploy them as new Web services without having to re-specify their configuration and mapping information. The following considerations apply to this approach and its generated artifacts: This approach can only be used if you select IBM SOAP as your Web service run-time environment (see Deployment Dependencies). The generated Web service must be created in a Web project   Development Guidelines The following sections address important considerations relevant to developing a Web service in RAD 6.0. They describe the development options available based on the deployment and WS-I compliance requirements of your Web service. Deployment Dependencies The approaches (top-down and bottom-up) that are available to create a Web service depend on the run-time environment that you are targeting for deployment. RAD 6.0 supports the following Web services run-time environments: IBM WebSphere v6 This is the default Web services run-time environment in RAD 6.0 and the one recommended for production use. It supports both a JMS and HTTP transport protocol, thus allowing Web service clients and servers to communicate either via HTTP connections or JMS queues and topics. Note that a Web service must be implemented as an EJB if it will be accessible through the JMS transport. IBM SOAP The IBM SOAP run-time environment supports the Apache SOAP version 2.2 and 2.3 protocols (see Resources) and was the only Web service run-time environment supported in WebSphere Studio version 5.0 and earlier. It should only be used for backward compatibility purposes. Apache Axis 1.0 This run-time environment supports the Apache Axis version 1.0 SOAP implementation (see Resources). It is not recommended for production use because of potential Web service interoperability problems (see Problems with using Apache Axis 1.0 run-time environment in the tool's Help Contents) It is recommended that you choose the IBM WebSphere v5 run-time environment unless your deployment target specifically requires you to use an Apache SOAP or Apache Axis implementation (if so, be aware of the associated limitations described in the tool's Limitations of Web Services Help content). Table 1 summarizes the Web service creation approaches supported by RAD 6.0 for each run-time environment. Approach IBM WebSphere v6 IBM SOAP Apache Axis 1.0 Create a skeleton JavaBean from a WSDL document Yes Yes Yes Create a skeleton EJB from a WSDL document Yes No No Create a Web Service from a JavaBean Yes Yes Yes Create a Web Service from an EJB Yes Yes No Create a Web service from a DADX No Yes No Create a Web service from a URL No Yes No Create a Web service from a Web service Deployment Descriptor (ISD) No Yes No Table 1 - Supported Web Service Creation Approach by Run-time Environment WS-I Basic Profile Compliance The Web Services-Interoperability (WS-I) Basic Profile is a set of requirements published by the WS-I organization to promote Web services interoperability across platforms, operating systems, and programming languages. It defines WSDL and protocol (SOAP/HTTP) traffic requirements that a Web service must satisfy in order to meet WS-I compliance. RAD 6.0 includes validation tools that can be used to verify a Web service's compliance to the WS-I Basic Profile 1.0 requirements. You can set a WS-I compliance level (Require, Suggest or Ignore (default)) for the workspace or project prior to developing a Web service or run the validation tools after it is developed. It is recommended that you develop Web services that are WS-I Basic Profile compliant. The following guidelines should be followed to ensure this: Use Document/literal or RPC/literal for the WSDL Style (RPC/encoded is not WS-I compliant) Use SOAP over HTTP as the message and transport protocols (SOAP over JMS is not WS-I compliant) Do not use any security options for the Web service (XML Digital Signature and XML Encryption are not WS-I compliant) Client Proxy Considerations There are 2 types of client proxies that you can optionally generate when creating a Web service: Java bean Proxy The Java bean client proxy allows you invoke the Web service methods via remote procedure calls. It can only be created in a client Web project if IBM SOAP or Apache Axis 1.0 is selected for the client run-time environment. Otherwise, for an IBM WebSphere v6 client run-time environment, it can be created in a Web, Java, EJB or Application Client project. Web Service User-Defined Function This option allows you to create a DB2 User-Defined Function (UDF) for each method of the Web service that you wish to invoke. It requires that the DB2 Web services consumer UDF package and DB2 XML Extender be installed in the database. The UDF is created and added to the database definition with all related client artifacts stored in a Web project. Select a different EAR for the Web service and the Web service client to reduce the chance of encountering run time errors. Remember that a client is expected to be a different application from the Web service, and Web services are not intended for inter-application communication.   Resources For additional information on the topics below, please refer to the corresponding link. Apache SOAP: http://xml.apache.org/soap Apache Axis: http://xml.apache.org/axis Web Services Interoperability (WS-I): http://www.ws-i.org/   © Copyright IBM Corp. 1987, 2004. All Rights Reserved.

Rational Unified Process