Web Services Handbook – An Excerpt 1-800-COURSES www.globalknowledge.com Expert Reference Series of White Papers Written and provided by ibm.com/redbooks Web Services Handbook for WebSphere Application Server Version 6.1 Ueli Wahli Owen Burroughs Owen Cline Alec Go Larry Tung Review of Web services standards and specifications WebSphere 6.1 support of new standards Web services development and deployment Front cover © Copyright IBM Corp. 2006. All rights reserved. 197 Chapter 11. Best practices In this chapter, we describe some best practices for Web services and service-oriented architectures. The best practices are broad in their scope because they cannot take any problem domain or solution into account. However, they can serve as a high-level check list when designing and implementing Web services. 11 198 Web Services Handbook for WebSphere Application Server 6.1 Generic best practices In this section, we describe some best practices that apply to any Web service solution, independent of the product vendor and the problem domain. Be WS-I compliant Being WS-I compliant means that your application follows the industry’s conformance standards with regards to interoperability. If the development tool you are using supports the development of WS-I compliant Web services 1 , you should turn this feature on and follow its advice. (You can find more information about WS-I in Chapter 9, “Web services interoperability” on page 165.) However, conforming to WS-I does not mean that your application will be interoperable in any case, because some other party might not be WS-I compliant. Also, there are some ambiguities in the WS-I profiles. Use simple data types Even though Web services were designed with interoperability in mind, it is best to use simple data types where possible. By simple, we mean integers and strings. In addition, compound data types (comparable with structs in C, or records in Pascal) and arrays of simple types are simple. Anything that does not fall into this pattern should be used carefully. In particular, the Java collection classes and similarly complex data types should be avoided altogether because there might be no proper counterparts at the client side. Avoid nillable primitives Nillable primitive types are allowed for Web services, but there are interoperability issues when using them. The best advice is to not use them at all, and use dedicated flags to signal the condition that a value does not exist. Avoid fine-grained Web services Web services use a very simple, yet powerful format for their main protocol: XML. While being able to read and structure XML documents with just any simple text editor eases the use of SOAP, the process of automatically creating and interpreting XML documents is more complex. 2 1 As does Application Server Toolkit and Rational Application Developer. 2 This process is also referred to as “marshalling” and “demarshalling.” Chapter 11. Best practices 199 Therefore, there is always a point where the complexity of dealing with the protocol is higher than performing the actual computation. To avoid this problem, design Web services that perform more complex business logic. This can also mean that your Web service allows for bulk processing instead of multiple invocations with one parameter only. Avoid Web services for intra-application communication This best practice is closely related to the previous practice. Intra-application communication (that is, communication within an application) is generally not exposed to any third-party clients. Therefore, there is no need to allow for an interoperable interface in this case. However, try to take into consideration that this might change in the future. Use short attribute, property, and tag names This is another practice that is closely related to the previous practices. As each attribute, property, and tag name is transmitted verbatim, the length of a message is directly dependent on the length on the attribute and property names. The general guideline is the shorter the attribute, property, and tag names are, the shorter the transmitted message and the faster the communication and processing. 3 Avoid deep nesting of XML structures This is yet another practice that is closely related to the previous practices. Because parsing of deeply nested XML structures increases processing time, deeply nested compound data types should be avoided. This also increases comprehension of the data type itself. If you are familiar with CORBA or EJBs, apply what you learned there—CORBA applications share many concepts with Web services. In fact, a service-oriented architecture can be implemented with CORBA as well. Almost all best practices that you learned when designing and implementing CORBA-based solutions apply also in the domain of Web services. 3 There are means of using Web services without this drawback: WebSphere Application Server allows for direct invocation of EJBs (see “Multiprotocol binding” on page 386 for more details), and it is being investigated whether ASN.1 can be used for Web services bindings: see: http://java.sun.com/developer/technicalArticles/WebServices/fastWS/ 200 Web Services Handbook for WebSphere Application Server 6.1 Apply common sense (also known as being defensive) If a standard or specification is not clear enough, try to implement your Web service such that it can handle any of the interpretations you can think of. An example from a different, although not less instructive, domain is the following excerpt from the TCP/IP specification (RFC 793): Postel's Law: Be conservative in what you do, be liberal in what you accept from others. 4 http://www.ietf.org/rfc/rfc0793.txt?number=793 Avoid extremely large SOAP messages When designing your Web service, try to not send very large SOAP messages (for example, more than one megabyte). It is important to remember that a large percentage of processing time is spent in just the parsing of the SOAP messages. Therefore, large SOAP messages will cause a great a mount of parsing. This will result in high processing loads, and low throughput. Also, avoid sending large chunks of binary data within the SOAP message. Java byte arrays (byte[]) can either be mapped to xsd:base64Binary or xsd:hexBinary. In both these cases, the raw binary data must be converted into another format (base64 or hexadecimal) that takes up more space. Moreover, there is the added performance penalty of converting a byte array into the XSD format, and from the XSD format to the byte array. SOAP with Attachments (SwA) may be an alternative. However, SOAP with Attachments is not interoperable with .NET Web services. Use top-down development when possible Customers have two choices when developing Web services with the WebSphere tooling:  Start with the WSDL, and generate the Java files (top-down)  Start with the Java files, and generate the WSDL (bottom-up) Although using bottom-up development is usually easier for beginners, it is not recommended for more complicated designs. The bottom-up approach may result in Java-specific information. For example, java.util.Vector and java.util.HashMap map to nonstandard XSD types, which will cause interoperability problems. 4 The complete statement in the RFC is: “Robustness Principle—TCP implementations will follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others.” Chapter 11. Best practices 201 Do not use unsupported Technology Previews in production IBM is dedicated to providing the latest Web services technology to customers. One of the vehicles for delivering this technology is through Technology Previews. Unfortunately, IBM does not provide support for Technology Previews, so if you encounter problems or defects, IBM is unable to help. Avoid using Technology Previews in production. WebSphere Application Server best practices This section lists some best practices for Web service design and deployment when WebSphere Application Server is the platform of choice for your Web service implementation. Use the WebSphere Web services engine The WebSphere SOAP runtime includes many performance improvements that can help with the performance of your application. Customers are discouraged from using third-party engines, such as Apache Axis. If there is a defect with a third-party engine, then IBM will not be able to provide support to fix it. Use caching of Web services as provided by the platform WebSphere Application Server provides an excellent caching framework that allows for caching of information at various levels. Among these, you can also cache Web service requests, thus save processing time. The cache is easy to set up and can be used on any existent Web service. In addition, caching can be also turned on at the client, thus allowing for even more performance improvements. More information about caching of Web services can be found in Chapter 26, “Web services caching” on page 699. 202 Web Services Handbook for WebSphere Application Server 6.1 Summary In this chapter, we described some best practices when designing and implementing Web services and service-oriented architectures. Most of these are not tied to any specific vendor product. However, because there are always product-dependent best practices, we included some that can be exploited when using the WebSphere Application Server product. More information For more information, see the following papers and sites:  Web services interoperability: http://www.ws-i.org  The paper Best practices for Web services, available at: http://www.ibm.com/developerworks/library/ws-bestcol.html  The paper Performance patterns for distributed components and services, parts 1 and 2, available at: http://www.ibm.com/developerworks/library/ws-interface1/ http://www.ibm.com/developerworks/library/ws-interface2/  The paper Performance Best Practices for Using WebSphere Application Server Web Services, available at: http://www.sys-con.com/websphere/article.cfm?id=394 © Copyright IBM Corp. 2006. All rights reserved. 309 Chapter 16. Test and monitor Web services In this chapter, we talk about the techniques and functions provided by IBM WebSphere Application Server and WebSphere Application Server Toolkit to test and monitor Web services. First, we describe the Application Server Toolkit test facilities, and then we show how to monitor Web services with WebSphere Application Server functions. Throughout this chapter, we use the weather forecast application as generated from the WeatherJavaBean. The weather forecast application must be running, and the database must have been created as described in “Setting up the WEATHER database” on page 738. All samples in this chapter use the test data created with the JavaBean weather forecast application. 16 310 Web Services Handbook for WebSphere Application Server 6.1 Testing Web services Web services testing has the same approach as testing any other distributed application. The simplified goal of testing is to verify that the application, running on a server, is acting as expected; that is, does the response on the client side match the expected return value? Because each distributed application has several layers, there are a number of places to define and run tests. Depending on the actual Web service implementation (JavaBean, EJB), the well-known application development test approaches should be used. Applying test techniques is to verify the functions of the Web service implementation and all its components. Testing modes There are two kinds of test modes: automated and manual. As a best practice, the approach should be to implement all tests as automated tests whenever possible. Automated tests have following advantages:  Consistent approach—Documented test cases with reproducible test results lead to high confidence that the application performs as designed.  Repeatable process—Anyone can easily rerun tests scripts, increasing development efficiency. Development can run tests early and often, ensuring no regressions are introduced into the application.  Sharable—Test definitions and scripts have to be created only once and can be shared within development teams. This helps to create a consistent test environment, and all team members use the same tests to verify the application functions as expected. With WebSphere Application Server Toolkit (AST), automated and manual tests can be accomplished. We talk about the test features in the following sections:  Web Services Explorer—Manual test  Web services test client JSPs—Manual test  Universal Test Client—Manual test There are a number of Web services component test tools available as Open Source projects. [...]... applied for Web services development, respectively, for the actual Web services implementation and all sub-layers (JavaBeans, EJBs) Web Services Explorer In this section, we discuss the Web Services Explorer test functions We show some best practices about how to use the Web Services Explorer to test Web services Also, the Web Services Explorer provides more functions than performing Web services tests;... ibm.etools.webservice.was.atk.ui.doc/concepts/ctestover.html Chapter 16 Test and monitor Web services 311 Important: The Web Services Explorer can only be used to test HTTP bound Web services It is not possible to test SOAP/JMS Web services To test SOAP/JMS services, use the Web services sample test JSPs (see Web services sample test JSPs” on page 317) In the sections that follow, we explain the Web Services. .. functions and how to use them Starting the Web Services Explorer To test a Web service available in Application Server Toolkit, we recommend that you start the Web Services Explorer from the service WSDL file: Start the Web Services Explorer from a service WSDL file Select a WSDL file (under Dynamic Web Projects) WeatherJavaBeanWeb/ WebContent /WEB- INF/wsdl/WeatherJavaBean.wsdl and Web Services → Test with Web. .. Services → Test with Web Services Explorer The Web Services Explorer opens (Figure 16-1) Figure 16-1 Web Services Explorer: WSDL page 312 Web Services Handbook for WebSphere Application Server 6.1 Working with the Web Services Explorer The first time you start the Web Services Explorer it takes a while, but then the WSDL page of the explorer opens The methods and the endpoint of the Web service are listed... Generating client-side code The Web Service Client wizard generates proxy classes and, optionally, test client JSPs For example, we can regenerate the client code for the JavaBean Web service: In the Project Explorer, expand Web Services → Services, and select the WeatherJavaBeanService and Generate Client (context) In the Web Services page, select Java proxy and Test the Web service (Figure 16-7) Figure... monitoring data in the Tivoli Performance Viewer, expand the server1 → Performance Modules tree and select Web services Tivoli Performance Viewer provides several types of measured data for Web services Table 16-1 shows and explains the counters Table 16-1 Tivoli Performance Viewer Web services counters Counter name Provided data LoadedWebServiceCount The number of loaded Web services ReceivedRequestCount... Monitoring and Tuning → Performance Viewer → Current Activity: Select the check box next to server1 and click Start Monitoring Run some of the Web services that you have created in Chapter 15, “Develop Web services with Application Server Toolkit 6.1” on page 247 Click server1 to open the Tivoli Performance Viewer window 334 Web Services Handbook for WebSphere Application Server 6.1 To view the Web services. .. Chapter 16 Test and monitor Web services 317 In the Web Service Selection page, the WSDL is preselected In the Client Environment Configuration page, select Web as the client type, and make sure that the projects are set to WeatherJavaBeanClientWeb and WeatherJavaBeanClient Note that you can enter names of new projects and they will be created and added to the selected server To change the Web service... bar 316 Web Services Handbook for WebSphere Application Server 6.1 Web services sample test JSPs The Web Service wizard of Application Server Toolkit (AST) can create test JavaServer Pages (JSP) for a Web service This function is part of generating client-side code, such as proxy classes, into a client Web project: The test client can be generated by the Web Service wizard when generating server and client... wizard when generating server and client code (see Web Service Client Test page” on page 256) The test client can be generated by the Web Service Client wizard when generating a client from a WSDL file Note: Web services client JSPs have an advantage over the Web Services Explorer, because they can also be used to test SOAP/JMS Web services You can also use automated test frameworks such as HTTP unit . Projects) WeatherJavaBeanWeb/ WebContent /WEB- INF/wsdl/WeatherJavaBean.wsdl and Web Services → Test with Web Services Explorer. The Web Services Explorer opens. with the JavaBean weather forecast application. 16 310 Web Services Handbook for WebSphere Application Server 6.1 Testing Web services Web services testing