SAAJ

SAAJ

To read and manipulate SOAP header blocks in JAX-RPC you have to use message handlers, which are covered in Chapter 14. Message handlers, however, use SOAP with Attachments API for Java (SAAJ), version 1.2, to represent an XML SOAP message. Therefore, you need to understand how to use SAAJ before you can learn how to use message handlers. It's the purpose of this chapter to teach you how to create, read, and manipulate SOAP messages using SAAJ. While SAAJ is central to the JAX-RPC Message Handler API, it's also useful by itself. In fact, it's easier to understand SAAJ by discussing it outside the context of JAX-RPC. This chapter explains the SAAJ programming model and explains how to use it as a standalone API. Chapter 14: Message Handlers explains how to use SAAJ with JAX-RPC.

SAAJ is an API-based SOAP toolkit, which means that it models the structure of SOAP messages. SAAJ models SOAP Messages with Attachments (SwA) in Java. SwA is the MIME message format for SOAP.^[1] For all practical purposes SwA is a standard and is used throughout the Web services industry. While SAAJ models plain SOAP messages as well as SwA, the WS-I Basic Profile does not endorse SwA, so it's not covered in this part of the book. You're very likely to encounter SwA messaging at some time, though, so this book provides detailed coverage of SAAJ's support for SwA in Appendix F.

^[1] The SwA specification is actually a Note maintained by the World Wide Web Consortium (W3C). A W3C "Note" is not a finished specification (which W3C calls a "Recommendation"), but simply a suggestion or a work in progress.

SAAJ (rhymes with "page") is an API you can use to create, read, or modify SOAP messages using Java. It includes classes and interfaces that model the SOAP Envelope, Body, Header, and Fault elements, along with XML namespaces, elements, and attributes, and text nodes and MIME attachments. SAAJ is similar to JDBC, in that it's a hollow API. You can't use it by itself; you need a vendor implementation. Each J2EE vendor will provide its own SAAJ implementation. They should all function the same way, although some may be more efficient than others.

You can use SAAJ to manipulate simple SOAP messages (just the XML without any attachments) or more complex SOAP messages with MIME attachments. SAAJ is used in combination with JAX-RPC (Java API for XML-based RPC), which is the J2EE standard API for sending and receiving SOAP messages. SAAJ can also be used independently of JAX-RPC and has its own, optional facilities for basic Request/ Response-style messaging over HTTP or other protocols.

SAAJ's network communication is based on the java.net.URL class, which can be extended to support any network protocol, not just HTTP. HTTP is the only protocol actually sanctioned by the Basic Profile, however.

Java developers can use SAAJ to work with SOAP messages within any SOAP application, including initial senders, intermediaries, and ultimate receivers. For example, you might develop a SOAP intermediary that processes a specific header block before sending the message on to the next receiver. Using SAAJ you can easily examine a SOAP message, extract the appropriate header block, then send the message along to the next node in the message path. Similarly, an ultimate receiver can use SAAJ to process the application-specific content of the SOAP body.

SAAJ is based on the Abstract Factory Pattern,^[2] which means SAAJ is a family of types in which each type of object is manufactured by another type in the SAAJ family. The root of the Abstract Factory Pattern in SAAJ is the MessageFactory class. It's responsible for manufacturing an instance of itself, which can in turn be used to manufacture a SOAPMessage. A SOAPMessage contains a SOAPPart, which represents the SOAP document, and zero or more AttachmentPart objects, which represent MIME attachments (such as GIFs and PDFs).

^[2] Erich Gamma, et al. Design Patterns: Elements of Reusable Object-Oriented Software. Reading, MA: Addison-Wesley, 1995, p. 87.

The SOAPPart contains a family of objects that model the SOAP document, including the Envelope, Header, and Body elements. You can obtain a clearer understanding of SAAJ by examining the basic structure of the SAAJ API alongside a diagram of an SwA message. As you can see from Figure, the SAAJ API models the exact structure of an SwA message.

SAAJ 1.2 is also based, in part, on the W3C Document Object Model (DOM), version 2. This relationship is explained in more detail in Section 13.6: SAAJ 1.2 and DOM 2.