Developing SOAP Web Services in Java Version 2.2 Instructor s Guide
Overview This course begins with an intentionally broad definition of a web service, and the first chapter expands on the idea that many sorts of software might legitimately claim to be web services. In the Java world there has been a corresponding diffusion of technology: adding web services to J2EE for the 1.4 release brought four new required standards (JAX-RPC, SAAJ, JAXR, WS4J2EE) and one optional one (JAXM); and there s been the sneaking suspicion of a scattershot approach by those in charge of the platform specs. Java EE 5 found sharper focus by consolidating the SOAP-oriented architecture under JAX-WS. But of course there are also RESTful services! and Java EE 6 makes JAX-RS a required technology as well. We now offer an array of JWS courseware, and, after that more balanced overview, this course focuses on SOAP-oriented services and JAX-WS. This standard plays the kingpin role that belonged to JAX-RPC before, but more than being only the most attractive of a handful of approaches, JAX-WS succeeds (in my opinion) in unifying the many possibly strategies for SOAP web-service development under one consistent programming model. (As the coursebook describes, when we say JAX-WS we probably mean JAX-WS plus WS4JEE plus WSMetadata; but still the core JAX-WS specification draws in SAAJ, JAXB, and other XML technology, via the Provider/Dispatch APIs.) I ve tried to get typical JAX-WS practices in front of students as early as is manageable. Even so, there s a lot to talk about before we can start building JAX-WS services and really know what we re doing. The overview modules gives some decent initial exposure, but then we pause for several chapters to consider JAXB, SOAP, and WSDL, before getting into JAX-WS in earnest. From that point on, students get as much JAX-WS as they can handle, with six straight chapters forming a mini-module in the center of the coursebook and five more covering alternatives and advanced topics.
Timeline The following breakdowns are approximate, and every class will vary. Day 1 2½ hours Module 1, Chapter 1 2½ hours Module 1, Chapter 2 3 hours (spans days) Module 2, Chapter 1 Day 2 1½ hours Module 3, Chapter 1 2½ hours Module 3, Chapter 2 1 hour Module 3, Chapter 3 Day 3 2½ hours Module 3, Chapter 4 2 hours Module 3, Chapter 5 2 hours Module 3, Chapter 6 Day 4 1 hour Module 3, Chapter 7 2 hours Module 3, Chapter 8 1½ hours Module 3, Chapter 9 2½ hours (spans days) Module 3, Chapter 10 Day 5 2½ hours Module 3, Chapter 11 2½ hours Module 3, Chapter 12 1½ hours Module 3, Chapter 13 If your student group isn t moving at the necessary pace over the first couple days, consider skipping the Metadata chapter, the Provider/Dispatch chapter, and if it comes to it just about anything after Module 3, Chapter 8. The material is all valuable, but generally speaking none of the contents of those last five chapters is essential or couldn t be learned after class time.
Teaching Notes I hope that the coursebook is sufficiently clear and detailed, and so the following notes just capture a few ideas about how to approach a given topic, additional concepts to add to your lectures and discussions, and any surprises you might encounter. Module 1, Chapter 2 Note in Lab 2A that it s possible to get a successful run of test.bat without finishing work on webservices.xml. The service and port names are important to the WSDL, but the prepared requests sent via SOAPPad don t rely on any of that. We do expect service at a non-default URL, but, in a quirky extension of the spec, GlassFish will use the <webservice-description> content as a service URI if none is provided via web.xml. So we actually have that in place in advance. In fact, for a few steps towards the end of the lab, this service is in a state similar to the failed experiment in relying too heavily on JAX-WS defaults for a WSDL-to-Java service, found in Prototype/WSDLToJava/Default and discussed in Module 3, Chapter 9.
Module 3, Chapter 1 If one looks closely at JAX-WS s implementation of mustunderstand, it can be seen to interpret this attribute differently than what s stated in the coursebook. Frankly, I believe they got this wrong. They essentially implement the handler framework to consider a header entry to be misunderstood if there are no handlers registered to process entries of its actor attribute. My interpretation (and I m pretty sure the consensus outside of this RI code) is that a header entry is misunderstood if there is code to process it, based on actor, but that code fails to parse the header entry or otherwise trips up during processing. There is a whitepaper on how to register service WSDLs in a UDDI repository, and that serves as the most formal glue available on combining these technologies: find it at http://uddi.org/bestpractices.html. We leave security topics alone for the rest of the course, after the very brief and perhaps appetite-whetting overview at the end of this chapter. Capstone Courseware offers a separate, three-day course in Securing Java Web Services. If your students have a strong interest in this topic, please contact us for supplemental materials: we can send you chapter presentation PDFs and point you to lab software, so that you can do an informal presentation. After the lab(s), I recommend that everyone change their GlassFish domain.xml file, adding the following line along with the other JVM options: <jvm-options>-dcom.sun.xml.ws.fault.soapfaultbuilder.disablecapturestacktrace=false</jvm-options> This will quiet down those very long stack traces that appear in SOAP fault responses from GlassFish. It s nice to know it can do this, but for most of our inclass purposes it s just a distraction. You will need to restart the server for this change to take effect.
Module 3, Chapter 2 The namespace attribute in a <soap:body> is generally not well understood, and it s one of those things that often gets overlooked as students are a bit overwhelmed with language details already. You might want to take a little extra time to highlight this and explain exactly what it means. Note that the WSDL s own targetnamespace governs the names of abstract-model components and concrete-model components, but never involves anything related to a particular protocol; then, the targetnamespace of any schema that s involved would govern the namespaces used in all document-style elements and of everything under the operation element in RPC style. That leaves a gap, and this attribute simply fills the gap. Try varying this value in a working service, and then notice the impact on SOAP messages that work with the service. The Dynamic client should be an interesting illustration of the power of metadata; but it s worth noting the simplifying assumptions that go into it. The target service must be RPC-style, use only single-value parts, and mustn t rely on any imported WSDL descriptors. These are all limitations of this piece of software, and not of WSDL itself. There is a library WSDL4J, from Apache, that provides a nice intuitive object model for WSDL, much as SAAJ does for SOAP. The Dynamic client could be rewritten to use this library, instead of doing all its work via DOM processing. (In fact a version like this was written; it got more aggressive about parsing all imported schema, and then ran afoul of the weird URL rewriting being done by AS9. But the code was a lot smaller!) After Lab 2B is probably the right time to explain a bit about how our client applications find the right service URLs using the AddressUtil project and class. See the final page of Appendix A for some detail on this, and it is also mentioned briefly in Chapter 5. But students should at least be given to understand at this point that they need to build and test service and client in the same environment: deploy from command line, test from command line; or build from Eclipse, test from Eclipse. Module 3, Chapter 3 This chapter just gives the barest overview of JAX-WS before we dive into detailed study of each of three paths W2J services, W2J clients, J2W services and then circle back in exception handling and best practices chapters. I see this six-chapter span as something of a module within the larger module.
Module 3, Chapter 4 It may be worth mentioning the doc/wrapped and doc/bare JAX-WS styles at this point; but note that they are covered in depth in Chapter 6, so it s probably good to keep it to a quick mention and foreward-reference. Module 3, Chapter 5 Our trick of pointing the bindings XML at /WSDL/Restaurant.xsd MOSTLY works; or it works for this purpose. But note that this version of the WSDL document gets no <soap:address> rewriting by the server. So we have to hardcode a service URL which, naturally, can t be correct for both Ant and Eclipse deployments. The saving grace is AddressUtil fixes the endpoint address at runtime, overriding everything else and it does get it right. But be aware of this bit of mechanics in case a student's lab seems to go off track. Module 3, Chapter 7 A bit more about the difficulty of running the Unfortunate client application from Eclipse: this is a case of JAX-WS versionitis, in which the GlassFish deployment of the API JARs and those in the Eclipse class path don t entirely jibe. The result is that code generated by the Ant WSDL-to-Java target will call a method that doesn t exist in the earlier API in Eclipse s runtime class path. If you or one of your students really wants to make this work from the IDE, do this: o Add three JARs to the project s class path, before rt.jar: webservicesosgi.jar, jaxb-osgi.jar, and gmbal.jar, all found in the main GlassFish lib directory. o Add a system argument to the launch, filling in the GlassFish root: -Djava.endorsed.dirs=<GF root>\glassfish\modules\endorsed.
Module 3, Chapter 8 This is the first time we use the LoveIsBlind database and therefore the Derby RDBMS and the EclipseLink JPA provider. So, if anyone has done any mucking around with servers starting/stopping, reconfiguring, etc. it may suddenly show up now. Pay close attention to the instructions for the LoveIsBlind/JPA project, to get these examples off on the right foot. It may seem that the Lumberyard project has an unnecessary W2J builder, in both Ant and Eclipse builds. But no: we use this application as an example of webservices.xml for handler-chain configuration. This forces us to state the exact location of a WSDL descriptor; it s not schema-valid to leave it out, and GlassFish will choke if we leave it blank or put a fake path there. So, we have to go this extra mile, even though the service isn t really a W2J service and the WSDL isn t really meant for publication. Module 3, Chapter 11 Generally, SAAJ is labor-intensive, and the investment of time in either or both of the labs may or may not be worthwhile for a given student. We mark the second lab optional to give a general sense of the weight of labs for the chapter. But feel free to limit work here or allow students to do so: do one lab or the other, maybe do just parts of the first lab and stub out others. One of the most frustrating things about SAAJ parsing has been the need to test for the presence of non-element nodes in the iterator returned by the getchildelements overload that takes no arguments. SAAJ 1.3 at least clarifies that this can happen, but it leaves us with a very clumsy algorithm for most cases. Oddly, the SAAJ 1.3 RI does not include whitespace-only text nodes in this iteration, where the 1.2 RI did. So in practice it would be possible to skip all the instanceof Element testing and just get all the elements, or the first one or only one or whatever. But since the spec says text nodes can appear, it s really still necessary to code defensively, in the style shown in the chapter and in SAAJ-based services in this course.
Module 3, Chapter 12 One unpleasant surprise with the JAX-WS RI and GlassFish is that if you use @HandlerChain but don t provide the required configuration file... it fails quietly! Well, there is a server warning. But the deployment succeeds, the application is started, and the service will answer requests. The handler(s) just won t be configured. Nasty. Exception handling over handlers is buggy when attached to @WebServiceProviders. To wit, if you throw an exception from a handler, it should interrupt processing and result in a SOAP fault. And we ve see in earlier demos that this works correctly, for the most part. But with a Provider-based service, the handler processing changes such that your exception will be swallowed. Must assume this will be fixed in GF3.1... Very alert students will notice the use of xsi:type in our handler-chain configuration files. This is not called out as an appropriate technique by the standards but it is practically necessary thanks to a gap in those standards. JSR 181 purports to define a schema in which <handler-chains> elements are toplevel elements which they are not in the JSR-109 schema for webservices.xml. But the schema is only found in the specification text, and as a schema it is not even well-formed XML. There is no normative reference to a public schema to fill the gap. So we have an expectation that we ll use an element in a certain way for which there is no normative schema to sanction it. Hence our workaround: use the JSR-109 schema and let the configuration file declare the type of the root element. We used to have a demonstration of client-side handlers using @WebServiceRef. Sadly, this technique falls apart in GlassFish 3.0.1: we get a java.lang.illegalargumentexception: class org.glassfish.webservices.jaxwsservlet has neither @WebService nor @WebServiceProvider annotation, whether we do the chain declaration in web.xml or using @HandlerChain on the service reference. We ve removed the demo from the coursebook for now, and hope to re-instate it in a later revision. After the schema-validation demo, you might want to mention a proprietary solution that does something similar: Metro supports a @SchemaValidation annotation. See http://metro.java.net/guide/schema_validation.html.
Module 3, Chapter 13 Just a general advice to try out the MTOM examples in advance and get very familiar with them. Every little piece has to be in place for MTOM to come into force, and it can be tricky to understand if and when it seems to fail to do so. Remember that the client must solicit an MTOM response, and the service must be configured to be in a posture to send one. And we have different clients in JAX- WS proxy-based applications and SOAPPad, each of which is capable of soliciting MTOM but in different ways and under different conditions. You might try <mtom-enabled> and <mtom-threshold> configurations on the XRay application, to show an alternative to the Java annotations used in LoveIsBlind. Test with SOAPPad using the mtom switch, or tweak the code for the client application.
Revision History Version 2.2 updates the course for Java EE 6. This means JAXB 2.2, JAX-WS 2.2, and JAX-RS 1.1, among other things. The course is also broken into modules, to support a new multi-course strategy for web services: An introductory module gives an overview of web services on Java EE 6. This is also used standalone as a one-day course, and is used in Courses 563 (JAX-RS focus) and 564 (mix of JAX-WS/JAX-RS) as well. o This includes working examples of RESTful services, using JAX-RS. o It spends less time on JSR-109 and takes a less complicated approach to it, deferring serious study of the XML and annotation options for a later chapter. A one-chapter module on JAXB this too is used in Courses 563 and 564. o There is a new starter lab that lets students experiment with XML-to-Java code generation as they complete the Restaurant schema. o There is now a lab on Java-to-XML development. o The customizations lab has been demoted to an example. The bulk of the course is in a module on JAX-WS. This module is much as it was in the previous version, with chapters renumbered. But, some other changes: o Service projects are restructured to be more Ecliipse-friendly, so that we can deploy and test them from within the Eclipse Helios IDE. Mostly this means the WDSL directory is gone and now lives at docroot/web- INF/wsdl; see also Appendix A in the coursebook on the AddressUtil. o The SOAPPad tool is much improved, now supporting a command-line interface so that it can be scripted to test our services. Each service now carries such a test script along with it, which just sends the canned request that we had lying around anyway. This test can be driven from the service project, with a single command for Ant users or a double-click from Eclipse. o We ve broken exception handling and the nuts-and-bolts treatment of JAX-WS metadata out into two new chapters. o We ve expanded the handlers chapter, with more detailed explorations of the mechanism and more examples of usage. o We ve dropped the EJBs-as-services chapter due to very low interest.
Version 2.1 mostly keeps up with evolving tools: JAXB 2.1, JAX-WS 2.1, and the Java EE 5 SDK, Update 7 (meaning GlassFish 2.1). Beyond these updates and basic re-testing, and various small cleanups and fixes, here are significant changes: In Chapter 4: under JAXB 2.1, the custom converter for java.util.date results in a binding directly to that type, and not to JAXBElement<Date> as before. In Chapter 7: we ve removed the note about wsimport.bat needing to be fixed to sneak extra nodes into the classpath. It s still true, but now our builds use the <WsImport> Ant task, which doesn t suffer this limitation and is the recommended practice generally. In Chapter 7: the Series of Unfortunate Events demo has been modified slightly. To make the point more blatantly that the client s interpretation of the SOAP fault is entirely dependent on the WSDL and the incoming SOAP, we redirect the client to a couple of JSPs that produce the appropriate SOAP for a normal fault and an IKnewItException, and see how the client reacts. In Chapter 8: there is an additional third step to this same case study, which shows the BraveAttempts.java client explicitly catching IKnewItExceptions. In Chapter 10: JAX-WS 2.1 exhibits different behavior with regard to polymorphism, and the Gimme, Gimme example produces different results. See the Chapter 10 teaching notes for more on this. In Chapter 11, and later chapters: JAX-WS 2.1 requires a more complete WSDL when hosting a @WebService Provider: just service and port don t do it anymore. So many case studies have more complete (though in some cases still incomplete) WSDLs. This doesn t really show to students, but there it is. In Chapter 12: there was a bug pretty well hidden away in the Examples/LoveIsBlind/SAAJ tree. I say hidden because in the normal run of the course, taking all instructions as written, it wouldn t surface; but when it did it was a doozy. The SQL scripts in the SAAJ version were not the same as those in the JAX-WS version a difference in how the enumerated type Sex was being mapped but the entities were the same. So, if for any reason a student or instructor re-built the database while working on the SAAJ labs, everything would fall apart. This has been fixed.
Version 2.0 re-invents the course for JAX-WS, JAXB, and other Java EE 5 standards. more has changed than has stayed the same, but some of the major differences are: More focus on WS-I Basic Profile in theory, and most services in the course are indeed WS-I BP conformant. Especially, we ve gotten rid of SOAP Section 5 encoding completely (hurrah!). Stripped down approach to the first two overview chapters, trying (a) to get code in front of students sooner and (b) to present the simpler Java EE picture more simply. New JAXB Chapter 4. New JAX-WS Chapters 6-10. New Provider/Dispatch Chapter 11. New Chapter 13 on JAX-WS handlers, which share much of their mission with JAX-RPC ones but which work differently in configuration and at the API level. New Chapter 14 on EJB services, simplified and of course targeting EJB3. New Chapter 15 on handling binary content, including MTOM/XOP. Labs work to Java EE 5 SDK, the only other tool being MySQL for a few exercises that use databases. Some interesting examples of using JAXB overlapping with JPA. JAXM is gone. More focus on standalone clients and use of SOAPPad to test services, and therefore less on web applications, except as front ends to the web services (see the TrackingUI project in Chapter 10). Instructors should plan for significant preparation time before teaching this version, even if they ve taught earlier versions many times before.
Revision 1.5.3 is a maintenance release with fixes for typos and other minor defects. This is the final revision for J2EE 1.4. We ve also undertaken some broader updates: Labs have been reworked to deploy to the 1.4_03 version of the J2EE SDK, which is current at the time of this release. Ant files have been centralized and are imported from individual build.xml files. The short name of the module, used in file paths, has been changed from WSJava to JavaWS. This lines up with Capstone s naming convention and especially with the follow-on course on Securing Java Web Services, which has the name JavaWSSecurity. The JAXM RI is now bundled with labs; no need to set it up separately. Revision 1.5.2 is a maintenance release with fixes for typos and other minor defects. Revision 1.5.1 is a maintenance release with fixes for typos and other minor defects. Revision 1.5 restructures the course from three separate modules into a single five-day course, while preserving the feasibility of shorter timelines based on subsets of the total chapter list. It also brings all the material up to the J2EE 1.4 final release and runs on the J2EE 1.4 SDK (aka AppServer 8). Revision 1.4 brings all the material up to the final drafts of the J2EE 1.4 specifications and runs on the J2EE reference implementation beta. Revision 1.0 is the initial public release.
Troubleshooting If you run into any trouble with code exercises, the first and best thing to do is to doublecheck that the classroom machines have been set up precisely according to the course setup guide. Especially, the wrong version of a tool can cause significant problems; don t wander off-book in this way unless absolutely sure you can support the software that you prefer and that we haven t tested. Check environment variable settings carefully, too; these are the cause of a great many classroom glitches. Below are some specific pitfalls that have come up in previous offerings of the course: If you encounter the error message Service MyService seems to be a JAXRPC based web service but without the mandatory WSDL and Mapping file. Deployment cannot proceed at deploy time, double-check that you ve built the project before deploying from Eclipse. This odd-looking message is often the most immediate manifestation of this much bigger problem. Remember too that while Run as Java Application automatically builds before launching, Run on Server does not. The fix is to Remove from the server, build, and re-deploy. If you see an error message during the deployment phase of the build, to the effect that the server can t find <impl-class>service.wsdl, when the actual WSDL has a different name entirely, know that this is a secondary error that indicates some sort of failure to parse the service metadata. Often it means that webservices.xml is out of synch with either the names and namespaces in the WSDL, or with the name of a Java SIB class or its @WebService annotation. The best advice is just to comb through web.xml, webservices.xml, the WSDL and/or Java source files, and make sure that the namespace URI and the service and port names all match. In the server log, a NullPointerException with a stack trace that includes a lot of preprocessxxx calls near the top is a different manifestation of the same sorts of problems as the can t find the <impl-class>service.wsdl mentioned above. In testing a deployed service via SOAPPad, or seeing the traffic via a SOAPSniffer, if you see a fault response with the message Could not find the dispatch method, this means that the request message s operation element couldn t be resolved to a Java method on the SIB. Look at the WSDL porttype and operation names, vs. the Java class/interface and method names, and at any Java annotations that affect how those names are mapped. Frankly, when this happens in a lab it s almost always a simple mistype in a source file somewhere. A missing custom-binding file can cause this, too in our Ant builds, be sure that any custom-binding file is declared via the build.properties file so that the wsimport or wsgen command includes it with the b switch.
If you see an unexpected argument name fault response, this indicates a mismatch of the XML content against the schema-declared content model so not about an RPC-style operation element but about document-style body content that doesn t match the message schema. Common causes include a missing endpointinterface attribute on the @WebService annotation, and a missing @WebParam annotation to customize a method parameter name so that it s not expected to be arg0. A successful message roundtrip, but with an empty response operation element, or other well-formed but unlikely response messages, usually indicate that arguments under the operation element in an RPC-style service were not as expected. Strangely this doesn t produce a fault; binding will proceed and arguments that were expected but not matched will be zero, false, or null. However this is handled in the SIB will dictate the response content, but for instance a null return value will appear as a response operation element with no child elements.
Errata The following issues have been reported since the public release of this version of the course: In Lab 13, the first three steps call for changes to Profile.java. By this time in the case study, this source file has moved to the supporting domain/persistence project in Examples/LoveIsBlind/JPA. And it already has the changes mentioned in those instructions. So this is more a review of code that s already in place. In lieu of those first three steps, just remind students to build the JPA project so that the JAR that it exports is available for their builds of the lab project. Feedback We very much appreciate whatever feedback we can get on our courseware especially from the instructor s perspective. Naturally, the more specific, the better, and we strongly encourage you to make notes on issues you may encounter in the classroom, whether they re typos, missing files, or suggestions for clearer language to explain a concept. We can t guarantee that we ll act on every suggestion, but we re aggressive about stamping out problems and try to be highly responsive. Hopefully this means that when you give us good feedback, you get a better course the next time you need to teach it. Please direct all courseware feedback to Will Provost Capstone Courseware mailto:provost@capcourse.com 877-227-2477 For anyone who s interested, we have a very informal defect-tracking system, based in Excel spreadsheets with columns to capture defect location, nature, status, and author feedback. Ultimately, feedback goes into these sheets, so if you want a template, we ll be happy to provide one, to facilitate the reporting process.