444 WebSphere Studio Application Developer Version 5 Programming Guide neutral protocol that allows a client to call a remote service. The message format is XML. WSDL (Web services description language) is an XML-based interface and implementation description language. The service provider uses a WSDL document in order to specify the operations a Web service provides, as well as the parameters and data types of these operations. A WSDL document also contains the service access information. UDDI (universal description, discovery, and integration) is both a client side API and a SOAP-based server implementation which can be used to store and retrieve information on service providers and Web services. Figure 13-2 shows a first glance at the relationship between the core elements of the SOA. Figure 13-2 Main building blocks in a SOA approach based on Web services All elements use XML, including XML namespaces and XML schemas. Service requestor and provider communicate with each other. WSDL is one alternative to make service interfaces and implementations available in the UDDI registry. WSDL is the base for SOAP server deployment and SOAP client generation. WSDL UDDI (Broker) SOAP HTTP J2EE other other Provider Requestor XSD SOA Runtime Metadata/vocabulary Runtime transports Implementation Service description XML Chapter 13. Developing Web services 445 Web services tools in Application Developer Application Developer provides tools to create Web services in bottom-up and top-down approaches, as well as tools for Web services client development. Bottom-up development of a Web service Application Developer provides a wizard for bottom-up Web services development. The following data structures can be used to build a Web service: JavaBean—The Web service wizard assists you in creating a new Web service, configuring it for deployment, and deploying the Web service to a server (which can be the test environment that comes with Application Developer, or an external application server). EJB—The Web service wizard assists you in creating a new Web service, configuring it for deployment, and deploying the Web service to a server. DADX—Document access definition extension (DADX) is an XML document format that specifies how to create a Web service using a set of operations that are defined by DAD documents and SQL statements. A DADX Web service enables you to wrap DB2 XML Extender or regular SQL statements inside a standard Web service. The DADX file defines the operations available to the DADX run-time environment, and the input and output parameters for the SQL operation. URL—The Web service wizard assists you in creating a new Web service that directly accesses a servlet running on a remote server. ISD—An ISD file is a Web service deployment descriptor and provides information to the SOAP run-time about the service that should be made available to clients, for example URI, methods, implementation classes (JavaBean, EJB), serializers, and deserializers. ISD files are concatenated into the SOAP deployment descriptor, dds.xml. Top-down development of a Web service For top-down development, Application Developer provides these functions: JavaBean from WSDL—The Web service wizard assists you in creating a skeleton JavaBean from an existing WSDL document. The skeleton bean contains a set of methods that correspond to the operations described in the WSDL document. When the bean is created, each method has a trivial implementation that you replace by editing the bean. JavaBean from XSD—The Web services tools support the generation of JavaBeans from an XML schema. Using these beans, you can create a JavaBean Web service. 446 WebSphere Studio Application Developer Version 5 Programming Guide Client development To assist in development of Web service clients, Application Developer provides this function: Java client proxy and sample application from WSDL—The Web service client wizard assists you in generating a proxy JavaBean and a sample application. The sample Web application demonstrates how to use the proxy bean in a client program. Note that the proxy and sample can also be generated in bottom-up and top-down approaches for testing of the generated Web service. Preparation for samples We will use a new Web project named ItsoProGuideWebServ to work with Web Services: Create the ItsoProGuideWebServ project as part of the ItsoProGuide enterprise application, with a dependency to the ItsoProGuideJava utility project (we are using the exception classes and some model classes). Create a package named itso.webserv.model (under Java Source). Import the three model classes into the itso.webserv.model package using the code in: \sg246957\sampcode\dev-webserv\initial The three classes are Banking (a subset of the Banking class used in the previous projects), AccountDB (which accesses the ACCOUNT table to retrieve and update accounts using JDBC), and Account (a subset of the Account model class without transaction records). You can also import the RunBanking.jsp into the Web Content folder for testing. Creating a Web service from a JavaBean As explained above, Web services can be created using any number of existing or new applications. Here, we will create a Web service from an existing JavaBean. The imported application contains the Banking JavaBean that can be used to get details about a particular Account, and to deposit, withdraw, and transfer funds. It acts as a facade, hiding the database access. Behind the facade is another JavaBean, AccountDB, that accesses the EJBBANK database. Two helper classes Chapter 13. Developing Web services 447 (Account and TransRecord, the same as the data transfer objects used for the EJBs) and one new exception (AccountDatabaseException) round off the model. Using a facade allows us to change the way the application accesses the database, for example using EJBs instead of JavaBeans, without affecting the remainder of the application. You should already have created and configured the ItsoServer with an EJBBANK data source. We will describe how to use WebSphere Studio wizard to create a Web service that returns information from the Banking service. The wizard guides us through generating the WSDL document from the JavaBean, creating a proxy bean, and testing the Web service in a Web browser using the generated test JSPs. Creating the Web service using the Web Service wizard To create the Web service, including the WSDL document, deployment descriptor, proxy, and test sample, we use the Web Service wizard. Select File -> New -> Other . Select Web Services to display the various Web service wizards. Select Web Service and click Next to start the Web Service wizard. We go through all the pages of the wizard. Click Next on each page to get to the next dialog. From the Web service type drop-down menu select Java bean Web service . Ensure that Start Web service in Web project is selected (this will start the server). Select all the following check boxes: Generate a proxy (for testing) Test the generated proxy Overwrite files without warning Create folders when necessary From the Client proxy type drop down menu, ensure that Java proxy is selected. Figure 13-3 shows the dialog after making these selections. Note: A Java proxy provides a remote procedure call interface to the Web service. It is used by other Java classes to access the Web service. 448 WebSphere Studio Application Developer Version 5 Programming Guide Figure 13-3 Web Service wizard Deployment Settings The Web Service Deployment Settings page allows you to select from supported run-time protocols and deployment servers. Select Use Defaults and make sure that ItsoProGuideWebServ is selected as the Web project. Java Bean Selection The Web Service Java Bean Selection page allows you to specify the Java bean to be turned into a Web service. Click Browse files (or Browse classes ) and locate the itso.webserv.model.Banking JavaBean. Java Bean Identity On the Web Service Java Bean Identity page, you specify the Web service uniform resource identifier (URI), scope, and the names of the generated files. We now briefly describe the options before we continue: Web service URI — A URI is a name that uniquely identifies a Web service to a client. The URI for the Web service is automatically generated by the wizard from the artifact you selected to turn into a Web service: Chapter 13. Developing Web services 449 http://tempuri.org/itso.webserv.model.Banking You could overwrite the default name, for example, urn:Banking, but we leave the default name. Web service scope—Three alternatives are available to define the scope of the Web service: – Request—A new service bean is constructed by the server for each SOAP request. The object is available for the duration of the request. – Session—One service bean is constructed by the server for each new client session to the Web service, and is maintained by sending cookies to the client side. The bean is available for the duration of the session in a similar way to HTTP session data. – Application—A single instance of the service bean is constructed for the life of the Web application. This is the best option for good performance, but requires that the JavaBean is written in reentrant fashion so that multiple requests can run through the code in parallel. This is the default for a JavaBean. Select Request , our bean is not thread safe. This information will be part of the deployment descriptor for the Web service. Use static methods—If this option is selected, the bean’s static methods become Web service operations and no object is instantiated. Do not select. Enable SOAP security—The Web service wizard also provides an option to apply security to the SOAP router servlet when deploying the Web services in the project to a WebSphere instance and configuration. Do not select. Because one instance of the SOAP router servlet exists for each Web application (WAR file), this option can only be edited when creating the first Web service for the project. When creating further Web services with the Web service wizard, this option will be disabled, showing the status of the first selection. This can be changed manually after generation by editing the deployment descriptor (web.xml). The generated files include the ISD file and four WSDL files. Java Bean Methods The Web Service Java Bean Methods page (Figure 13-4) shows a summary of public methods in your bean. For the example we select all methods. Also, select Show server (Java to XML) type mappings. When you select a method, the input and output encoding are displayed. The encoding style defines how the Java types in the client and server are mapped to the XML types in the SOAP message: 450 WebSphere Studio Application Developer Version 5 Programming Guide For all three methods, SOAP encoding is selected by default. SOAP encoding covers all basic data types as well as JavaBeans containing basic data types. Literal XML encoding would be used for a document object model (DOM) element (org.w3c.dom.Element). The XML source is then inserted directly into the SOAP message. Figure 13-4 Method selection Java to XML Mappings On the Web Service Java to XML Mappings page, review the Web service type mappings. At run time, the mappings govern serialization and deserialization. Figure 13-5 illustrates the mappings between Java and XML for the Web service to operate, assuming both a Java client and a Java server. Figure 13-5 mapping and encoding stages for a Web service Client Proxy Server Java to XML mapping Java to XML mapping XML to Java mapping XML to Java mapping Input encoding style Output encoding style 1 2 4 3 SOAP messages Chapter 13. Developing Web services 451 There are four steps in the process, indicated by the numbers in Figure 13-5: 1. Client input mapping (Java to XML) —This takes the parameter from the Java client and maps it using the input encoding style. 2. Server input mapping (XML to Java) —The inbound parameters are deserialized from the SOAP encoding style in the message to Java types, which are then used to invoke the method in the JavaBean. 3. Server output mapping (Java to XML)— Once the JavaBean has completed its method execution, the return value is inserted into the SOAP reply using the output encoding style. 4. Client output mapping (XML to Java) —The final stage is performed by SOAP for the client proxy, which maps the returned XML elements into Java types. The current page of the wizard shows the language mapping from Java types to XML types (Figure 13-6). Figure 13-6 Defining Java to XML bindings 452 WebSphere Studio Application Developer Version 5 Programming Guide Binding Proxy Generation In the Web Service Binding Proxy Generation page (Figure 13-7), review the bindings that are used in the WSDL. The client proxy provides a remote procedure call interface to your Web service. Using the proxy, the application calls a remote method on the Web service as if the method were a local one. Once the application makes the remote call, the proxy handles all of the communication details between the application and the Web service using SOAP. Note that the proxy is generated into a separate Web project named ItsoProGuideWebServClient. You could change the default project name if you wanted. The name of the proxy defaults to proxy.soap.BankingProxy. Select the Show mappings check box. Figure 13-7 Proxy generation Note: The types that are displayed are method input parameters (String, BigDecimal), method results (Account, TransRecord), as well as data types inside the Account bean (String, BigDecimal). Chapter 13. Developing Web services 453 XML to Java Mappings In the Web Service XML to Java Mappings page (Figure 13-8), review the mapping for deserialization from XML to Java types. For each XML type the Java type is displayed in the Class field. Figure 13-8 Defining XML to Java bindings SOAP Binding Mapping Configuration In the Web Service SOAP Binding Mapping Configuration page, review the Web service SOAP binding mapping configuration. These are set based on our previous definitions in the wizard and cannot be changed in our example. Test In the Web Service Test page (Figure 13-9), you decide which facility to use to test the Web service. The choices are: Web service sample JSPs—Generates a set of four JSPs into the folder sample/Banking in the client Web project (select this option). Web tools Java bean JSPs—Generates an HTML page, a result JSP, and a ViewBean class into the client Web project (does not function with the BigDecimal class). Universal Test Client—The universal test client is started and the proxy bean is instantiated. You can always use the universal test client even if you generate a sample. . JavaBean Web service. 446 WebSphere Studio Application Developer Version 5 Programming Guide Client development To assist in development of Web service clients, Application Developer provides this. service. It is used by other Java classes to access the Web service. 448 WebSphere Studio Application Developer Version 5 Programming Guide Figure 13-3 Web Service wizard Deployment Settings The Web. client and server are mapped to the XML types in the SOAP message: 450 WebSphere Studio Application Developer Version 5 Programming Guide For all three methods, SOAP encoding is selected by default.