Jaxm 0 - 9 - 3 PRD Spec

Java API for XML Messaging
TM
(JAXM) v0.93
Please send technical comments to: jaxm-expertgroup@eng.sun.com

Please send business comments to: jaxm-business@eng.sun.com
FT
RA
D
Public Review Draft 2– August 2001
Nicholas Kassem <Nick.Kassem@sun.com>

Anil Vijendran <Anil.Vijendran@sun.com>
Rajiv.Mordani <Rajiv.Mordani@sun.com>
i
ii
TM
Java API for XML Messaging Specification (“Specification”)
Version: 0.93
Status: Public Review Draft 2
Release: August, 2001
Copyright 1999-2001 Sun Microsystems, Inc.

901 San Antonio Road, Palo Alto, CA 94303, U.S.A.
All rights reserved.
NOTICE.
This Specification is protected by copyright and the information described herein may be protected by one or more
U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of
this Specification may be reproduced in any form by any means without the prior written authorization of Sun
Microsystems, Inc. (“Sun”) and its licensors, if any. Any use of this Specification and the information described
herein will be governed by the terms and conditions of this license and the Export Control and General Terms as set
forth in Sun's website Legal Terms. By viewing, downloading or otherwise copying this Specification, you agree that
you have read, understood, and will comply with all of the terms and conditions set forth herein.
Subject to the terms and conditions of this license, Sun hereby grants you a fully-paid, non-exclusive, non-
transferable, worldwide, limited license (without the right to sublicense) under Sun’s intellectual property rights to
review the Specification internally for the purposes of evaluation only. Other than this limited license, you acquire
no right, title or interest in or to the Specification or any other Sun intellectual property. The Specification contains
the proprietary and confidential information of Sun and may only be used in accordance with the license terms set
forth herein. This license will expire ninety (90) days from the date of Release listed above and will terminate
immediately without notice from Sun if you fail to comply with any provision of this license. Upon termination, you
must cease use of or destroy the Specification.
TRADEMARKS.
No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun's licensors is granted
hereunder. Sun, Sun Microsystems, the Sun logo, Java, the Java Coffee Cup Logo, Java Naming and Directory
Interface, and Java Community Process are trademarks or registered trademarks or service marks of Sun
Microsystems, Inc. in the U.S. and other countries.
DISCLAIMER OF WARRANTIES.
THIS SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR
DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY SUN. SUN MAKES NO
REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO,
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT
THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY
PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY
PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any
commitment to release or implement any portion of this Specification in any product.
THIS SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.

CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE
INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SUN MAY MAKE IMPROVEMENTS
AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS
SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current
license for the applicable version of the Specification.
LIMITATION OF LIABILITY.
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR
SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING,
PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
You will indemnify, hold harmless, and defend Sun and its licensors from any claims based on your use of the
Specification for any purposes other than those of internal evaluation, and from any claims that later versions or
releases of any Specification furnished to you are incompatible with the Specification provided to you under this
license.
Public Review Draft 2

iii
RESTRICTED RIGHTS LEGEND.
If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor
or subcontractor (at any tier), then the Government’s rights in the Software and accompanying documentation shall
be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department
of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).
REPORT.
You may wish to report any ambiguities, inconsistencies, or inaccuracies you may find in connection with your
evaluation of the Specification (“Feedback”). To the extent that you provide Sun with any Feedback, you hereby: (i)
agree that such Feedback is provided on a non-proprietary and non-confidential basis and (ii) grant Sun a perpetual,
non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of
sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the
Specification and future versions, implementations, and test suites thereof.
iv

Contents
JavaTM API for XML Messaging ...........................................i

Contents ................................................................................v
Status .....................................................................................ix
JAXM.S.1 Status of This Document .................................ix
JAXM.S.2 Acknowledgements ..........................................ix
JAXM.S.3 Terminology ....................................................x
Preface ..................................................................................xiii
JAXM.P.1 Audience ..........................................................xiii
JAXM.P.2 Abstract ............................................................xiii
Background ...........................................................................1
JAXM.1.1 Conceptual model .............................................1
JAXM.1.2 Scope ................................................................2
JAXM.1.3 Interoperability .................................................5
JAXM.1.4 SOAP Packaging Model ..................................6
JAXM.1.4.1 SOAP Message with Attachments ................7
JAXM.1.4.2 SOAP Message without Attachments ...........8
JAXM.1.5 JAXM, JMS & JavaMail ..................................9
Infrastructure .........................................................................11
JAXM.2.1 JAXM Client ....................................................11
JAXM.2.2 Error Messages .................................................12
JAXM.2.3 Messaging Profiles ...........................................13
JAXM.2.4 JAXM Deployment ..........................................14
JAXM.2.5 AsyncListener ..................................................14
JAXM.2.6 SyncListener .....................................................14
JAXM.2.7 Message Security .............................................15
Package Overview ................................................................17
JAXM.3.1 javax.xml.messaging Package ..........................17
JAXM.3.1.1 Endpoint & URLEndpoint ............................17
JAXM.3.1.2 ProviderConnection & Factory .....................18
v
vi
JAXM.3.1.3 ProviderMetaData & JAXMException .........19

JAXM.3.1.4 Sync. and async. activation objects ...............20
JAXM.3.2 javax.xml.soap Package ...................................21
JAXM.3.2.1 MessageFactory & SOAPMessage objects ...22
JAXM.3.2.2 SOAPPart & AttachmentPart ........................23
JAXM.3.2.3 MimeHeader(s) objects .................................25
JAXM.3.2.4 SOAP Element ..............................................26
JAXM.3.2.5 SOAPEnvelope & SOAPBody objects .....27
JAXM.3.2.6 SOAPHeader & SoapHeaderElement ...........28
JAXM.3.2.7 SOAPConnection ..........................................29
JAXM.3.2.8 SOAPException object .................................30
JAXM.3.2.9 Node & Text objects .....................................30
JAXM.3.2.10 Name, Detail & DetailEntry .......................31
JAXM.3.3 A simple Message Producer example ..............31
JAXM.3.4 A simple Message Consumer example ............36
Package javax.xml.messaging ..............................................39
AsyncListener ....................................................................40
Endpoint .............................................................................41
JAXMException ................................................................43
JAXMServlet .....................................................................45
ProviderConnection ...........................................................49
ProviderConnectionFactory ...............................................52
ProviderMetaData ..............................................................53
SyncListener ......................................................................55
URLEndpoint .....................................................................56
Package javax.xml.soap ........................................................59
AttachmentPart ..................................................................61
Detail ..................................................................................68
DetailEntry .........................................................................69
MessageFactory .................................................................70
MimeHeader ......................................................................73
MimeHeaders .....................................................................75
Name ..................................................................................79
Node ...................................................................................81
SOAPBody .........................................................................83
SOAPBodyElement ...........................................................86
SOAPConnection ...............................................................87
SOAPConstants .................................................................89
SOAPElement ....................................................................90

vii
SOAPEnvelope ..................................................................96
SOAPException .................................................................99
SOAPFault .........................................................................103
SOAPHeader ......................................................................105
SOAPHeaderElement ........................................................108
SOAPMessage ...................................................................110
SOAPPart ...........................................................................116
Text ....................................................................................122
References .............................................................................123
viii

Status
JAXM.S.1 Status of This Document
This specification is being developed following the JavaTM Community Process

(JCP2.0). Comments from experts, participants, and the broader developer commu-
nity will be reviewed and incorporated into this specification.
This document is the JAXM Specification, version 0.93. The main goal of this
draft is to enable the developer community to review and comment on the work of
the JSR067 Expert Group (EG).
This document has been designated as Public Review Draft 2.
JAXM.S.2 Acknowledgements
The following individuals and their respective companies - in no particular order -

are acknowledged for their contribution to the JSR067 Expert Group.
gdaniels@macromedia.com
simeons@allaire.com
peter.eberlein@sapmarkets.com
meera_bavadekar@hp.com
BJones@Bluestone.com
jags.ramnarayan@bea.com
pal.takacsi@bea.com
jcrump@exceloncorp.com
jjdubray@exceloncorp.com
Jean.Choi@sybase.com
himagiri@sybase.com
ix
x
Markus.Breilmann@tamgroup.com
francis.ho@webMethods.com
pyendluri@webmethods.com
ksankar@cisco.com
david.clay@oracle.com
neal.wyse@oracle.com
srh@us.ibm.com
chappell@sonicsoftware.com
cevans@progress.com
james_strachan@yahoo.co.uk
nazrul.islam@commerceone.com
richard.denoix@commerceone.com
seumas.soltysik@iona.com
JAXM.S.3 Terminology
The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT,

SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they
appear in this document, are to be interpreted as described in RFC 2119 as quoted
here:
MUST: This word, or the terms “REQUIRED” or “SHALL”, mean

that the definition is an absolute requirement of the specification.
MUST NOT: This phrase, or the phrase “SHALL NOT”, mean that
the definition is an absolute prohibition of the specification.
SHOULD: This word, or the adjective “RECOMMENDED”, mean

that there may exist valid reasons in particular circumstances to
ignore a particular item, but the full implications must be
understood and carefully weighed before choosing a different
course.
SHOULD NOT: This phrase, or the phrase “NOT

RECOMMENDED”, mean that there may exist valid reasons in
particular circumstances when the particular behavior is acceptable

xi
or even useful, but the full implications should be understood and

the case carefully weighed before implementing any behavior
described with this label.
MAY: This word, or the adjective “OPTIONAL”, mean that an item

is truly optional. One vendor may choose to include the item
because a particular marketplace requires it or because the vendor
feels that it enhances the product while another vendor may omit
the same item. An implementation which does not include a
particular option MUST be prepared to interoperate with another
implementation which does include the option, though perhaps
with reduced functionality. In the same vein an implementation
which does include a particular option MUST be prepared to
interoperate with another implementation which does not include
the option (except, of course, for the feature the option provides.)
xii

Preface
JAXM.P.1 Audience
This document is intended for developers using the Java programming language, e-
commerce architects, and application developers focused on the development of
business-to-business messaging applications. Many of the concepts mentioned in
this document are being discussed by participants within the ebXML (http://
www.ebxml.org) community and the W3C XML Protocol working group.
JAXM.P.2 Abstract
The JavaTM API for XML Messaging (JAXM v0.93) enables developers to write
business applications that support emerging industry messaging standards based on
the SOAP1.1 and SOAP with Attachments specifications. Because the XML mes-
saging standards are being developed outside of the JavaTM Community Process and
are evolving at different rates (driven by a diverse set of business and technical
requirements), the JAXM 0.93 specification does not mandate the use of any spe-
cific XML messaging standard. The term standard is being used here to denote a
specific usage of SOAP messaging. Within the context of this document, the term
Profile is used to refer to a specific protocol based on SOAP1.1 (with Attachments).
JAXM compatible implementations must support SOAP1.1 [See “SOAP” on

page 123] and SOAP with Attachments [See “SOAP Messages with Attachments”
on page 123]. They may additionally support one or more SOAP message Profiles
[See “Messaging Profiles” on page 13]. This specification makes no assumption
about the number of such Profiles but assumes that they must be named in a con-
sistent and standard way.
xiii
xiv

C H A P T E R JAXM.1
Background
JAXM.1.1 Conceptual model
The following figure presents a conceptual relationship between JAXM and other
architectural elements required in web-based, business-to-business messaging.
Organization ‘B’
Organization ‘A’
SOAP JAXM Service API

Messaging
Client
JAXM Provider
SOAP Provider
SMTP/
HTTP HTTP POP
IMAP
SOAP Message SOAP Message
Figure 1. B2B Messaging Conceptual Model
1
2 BACKGROUND
JAXM is intended to be a lightweight messaging API for the development of

XML-based business messaging applications. These applications appear prima-
rily, though not exclusively, at the edge of organizations. The term edge is being
used loosely to denote the set of applications that, collectively, deal with the pro-
duction and consumption of standard business messages. The requirement for
processing such messages is being fueled by the increasing need of organizations,
irrespective of their size, to exchange business documents electronically. An
application designed to consume specific business documents in an agreed-upon
manner, and in response, produce appropriate business documents, is informally
referred to as a business service. Such services, when deployed in a Web Con-
tainer are typically called Web Services. The formal specification of such services
is outside the scope of this document.
Figure 1. makes a logical distinction between the implementation of the

JAXM API and a provider based on the JAXM API (“JAXM provider”). The latter
is responsible for the actual transmission and reception of SOAP messages. An
application that is written to the JAXM API is referred to as a “JAXM Client”.
JAXM.1.2 Scope
Message exchange scenarios based on JAXM may be synchronous or asynchronous

in nature, but they are always document-centric. The exchange of XML documents
between business partners is assumed to occur in a choreographed manner. The use-
cases fall into five major categories (illustrated in Figure 2. through Figure 6.), and
all implementations of JAXM must support these interaction styles. Note that for
simplicity, the term sender is being used to refer collectively to a JAXM Client/pro-
vider pairing in a message production role. Similarly, the term receiver refers to a
Client/provider coupling in a message consumer role.

Scope 3
Figure 2. Asynchronous Inquiry
In the asynchronous inquiry scenario, the sender is assumed to send a message

without needing to wait for a response. The receiver is required to read and pro-
cess the request and generate an appropriate reply to the original request. Sending
the reply is a totally separate operation, and the time interval between a request
and a reply may be measured in days. JAXM implementations must therefore be
able to support long-lived transactions.
Figure 3. Asynchronous Update with Acknowledgement
Figure 3. depicts a scenario in which the reception of an acknowledgement

message denotes the successful completion of an earlier request. An application
4 BACKGROUND
must correlate a response message to the request message (sent previously) to

which it refers. Note that JAXM does not specify how this is done.
Figure 4. Synchronous Update
Figure 4. reflects a synchronous scenario, in which the sender either cannot or

must not proceed until a response to the request being sent is received. A typical
response is an acknowledgement message, which implies the successful comple-
tion of the request that was sent.
Figure 5. Synchronous Inquiry
The scenario in Figure 5. is a simple variation on the previous case. The

sender waits for a reply message to the request that was sent. The distinction is

Interoperability 5
that in this case, the reply message is typically purely informational in nature, that
is, it does not necessarily relate to the request that was sent.
Figure 6. Fire and Forget
The case shown in Figure 6. implies that the sender is not expecting a
response to the request message being sent.
JAXM may facilitate the automation of only portions of an overall business

process. The applicability of JAXM to the larger business system is therefore a
function of an overall business process model that is specific to a particular group
of trading partners or vertical industries. This specification does not address the
ways in which business objects are expressed in XML.
JAXM.1.3 Interoperability
An important notion presented in the “B2B Messaging Conceptual Model” on

page 1 is that a JAXM-enabled Client must be capable of interoperating with a peer
business application irrespective of whether that application was implemented using
JAXM. One of the key ingredients enabling standards-based interoperability is the
widespread adoption of (1) a transport-neutral packaging model and (2) agreements
on message header structures, manifests, and so on.
Although JAXM is heavily biased towards using industry standards, the only
requirement placed on JAXM 0.93 providers is that they must support SOAP1.1
and SOAP with Attachments. In addition, JAXM providers may optionally choose
to support higher level industry messaging protocols built on top of the SOAP
standard. As stated earlier, a specific industry usage of SOAP is referred to here as
6 BACKGROUND
a Profile. A JAXM Profile, therefore, represents a given industry or standards

group’s particular use of SOAP.
JAXM providers must implement their transport bindings in accordance with

the SOAP 1.1 specification. JAXM providers must therefore support the HTTP
protocol but may also choose to implement other standard networking protocols,
such as FTP and SMTP(IMAP, POP). In all cases, however, JAXM assumes that
SOAP messages are being transported by the communications infrastructure.
JAXM providers may choose to support multiple, concurrent networking trans-
ports. JAXM clients (business applications) should be kept isolated from the spe-
cifics and idiosyncrasies of underlying communications infrastructures.
JAXM.1.4 SOAP Packaging Model
There are two packaging models for SOAP messages, one that includes attachments
and one that does not. JAXM provides a standard way of both producing and con-
suming SOAP messages with or without attachments.

SOAP Packaging Model 7
JAXM.1.4.1 SOAP Message with Attachments
Communication Protocol Envelope (HTTP,SMTP...)
SOAP1.1 + Attachments MIME Envelope
SOAP Part
SOAP-ENV:Envelope
SOAP-ENV:Header
SOAP-ENV:Body
Attachment Part
SOAP Attachment
(XML or non-XML)
Figure 7. SOAP1.1 with Attachments
Figure 7. depicts the conceptual model of a JAXM message that includes one
or more attachments. This message is aligned with the SOAP1.1 and SOAP with
Attachments specifications, which all JAXM implementations must support.
A JAXM client may choose whether to create and/or consume SOAP attach-
ments based on application-specific requirements. For instance, an acknowledge-
ment does not require an attachment, whereas content that is not in XML format
does require an attachment. The attachment part of a message can contain any
kind of content, from image files to plain text.
8 BACKGROUND
Whether a message sent by a JAXM client contains an attachment part is up to

the application developer; however, as a message receiver, a JAXM client must
recognize the presence of one or more attachments and process them. This pro-
cessing is done in an application-specific way.
A message that contains one or more attachments must have a MIME enve-
lope, which contains the SOAP part of a message and also the attachment part.
JAXM uses the JavaBeansTM Activation Framework (JAF) to support a flexible
way of handling SOAP attachments based on the MIME types. Refer to “Java-
Beanstm Activation Framework Version 1.0a” [see page 123] .
JAXM.1.4.2 SOAP Message without Attachments
Communication Protocol Envelope (HTTP,SMTP...)
SOAP1.1 Message Package

SOAP-ENV:Envelope
SOAP-ENV:Header
SOAP-ENV:Body
Figure 8. SOAP1.1 Packaging Model without Attachments
Figure 8. shows the packaging model for a message with no attachments. In

addition to not having an attachment part, it also has no MIME envelope. Without
attachments, the MIME Multipart/Related outer wrapper is redundant, and a
JAXM implementation must not produce one.

JAXM, JMS & JavaMail 9
JAXM.1.5 JAXM, JMS & JavaMail
The JavaTM2 Platforms currently provide APIs for three distinct messaging infra-
structures namely; Web Services (SOAP1.1 based messaging), Message Oriented
Middleware (MOM), and Mail. Although these infrastructures share similarities at
the conceptual level, in reality they are sufficiently different that Java developers
have required and have gravitated towards APIs optimized for each infrastructure.
The underlying similarities between messaging infrastructures have, over

time, resulted in hybrid use-cases. For example, there are cases where mail mes-
sages are transported over MOM infrastructures as opposed to conventional e-
mail backbones. These variations and cross-infrastructure use-cases are typically
not visible to individual developers and rarely influence architectural choices
made by them. By way of example, a JMS developer typically requires a MOM
infrastructure at both ends of a particular application. The end-to-end applications
developed, are typically conceived of as MOM applications and not as (say) Mail
applications. The fact that a given MOM infrastructure may be transporting the
messages over an e-mail backbone, has no bearing on the application model devel-
opers choose to adopt.
Similarly, JAXM is an abstraction on an emerging Web-centric messaging

infrastructure. In essence JAXM is promoting a programming model for an infra-
structure that fits somewhere between e-mail and MOM. The key notion is that a
JAXM application may be written such that it either offers a SOAP-based Web
service, or is a client of a SOAP service, or both. A JAXM application is therefore
quite different from a JMS application, which in turn is distinct from a JavaMail
application. Each API is equally valid and relevant with respect to, and in the con-
text of, their associated infrastructures. Beyond some superficial similarities
between these APIs, they differ primarily in the communication concepts repre-
sented by the semantics of their message headers. SOAP 1.1 is silent on the con-
tents of the message header though JAXM profiles (e.g. for ebXML MS)
introduce the concept of 'separate' SOAP infrastructures.
Application developers are likely to choose JAXM in cases where they wish to
communicate over SOAP infrastructures. The fact that SOAP has specified more
than one transport binding (and indeed has not precluded bindings for MOM
infrastructures) does not undermine the notion that the conceptual model for
JAXM developers is one in which the application endpoints are in fact SOAP end-
points. Having said this, a given JAXM Provider may choose to transport SOAP
10 BACKGROUND
messages over a MOM infrastructure. This is an implementation detail and the

application has no visibility into the infrastructure details nor does this reality
transform a JAXM application into a MOM application.
In summary, JAXM is not intended to be a ‘grand unification’ API, and its’

role and relationship to a SOAP infrastructure is equivalent to the relationship that
JMS has with MOM infrastructures. JAXM, JMS, and JavaMail are focused on
meeting the needs of their respective constituencies by utilizing the distinct char-
acteristics of SOAP, MOM and Mail infrastructures respectively.

Infrastructure
The term infrastructure is being used to refer to the implementation-specific func-

tionality required to support a JAXM implementation.
JAXM.2.1 JAXM Client
The term client as used here is essentially synonymous with the term application,
that is, a collection of application-level functionality that is typically deployed either
in a J2EE Web Container or J2EE EJB Container. In addition, a standalone J2SE
application may implement only the client view of the JAXM API. Such an applica-
tion is considered to be a special-case, since for whatever reason, it has no need to
utilize the services of a provider. This application is assumed to be a client of a
point-to-point synchronous messaging service offering only a request-response style
of interaction. An implementation of the JAXM API must support both one-way and
request-response style messaging.
In general, JAXM clients will be consumers of services offered by providers.
The capabilities of providers may vary widely, and their specific capabilities, for
example, in the area of Quality of Service, fall outside the scope of this document.
In principle, JAXM providers are considered to be part of the communications
infrastructure as opposed to being application specific. Message routing or reli-
able messaging are examples of the functionality that a JAXM provider may
choose to implement.
JAXM clients (implementing a service) must be capable of consuming
SOAP1.1 (with attachments) messages. In addition, when a JAXM client is
deployed in a J2EE Web Container, the SOAP1.1 protocol must be bound to
HTTP. However, the way in which JAXM clients communicate with JAXM pro-
viders is considered to be a private implementation detail. A JAXM client is not
11
12 INFRASTRUCTURE
required to be co-located with its provider, nor is it required to be in a different

virtual machine.
The relationship between JAXM clients is fundamentally a peer-to-peer one,
that is, from a programming model perspective, a JAXM client may choose to play
a client role or a server role. In addition, depending on a specific context or mes-
saging choreography, a JAXM client is free to switch roles. By way of example, a
JAXM application may send one or more purchase orders to a specific purchase
order consolidation service and may choose to wait for receipt acknowledgments
from that service. In the event that acknowledgements fail to arrive, the client may
choose either to re-send the purchase orders or, alternatively, to request acknowl-
edgements explicitly.
The JAXM specification exposes both a client view and a service view to
developers implementing JAXM applications. A developer implementing a JAXM
service and deploying in a J2EE container, may choose to implement a one-way
messaging service or a request-response service. The implementation of a one-
way asynchronous messaging service requires utilizing the services of a JAXM
Provider. However, the implementation of a point-to-point request-response mes-
saging service can be accomplished without using a Provider. JAXM applications,
deployed in J2EE containers, and implementing to the client view of the specifica-
tion have the option of implementing either a one-way or a request-response style
client. The choice is dependent on the type of service the client intends to interact
with.
JAXM.2.2 Error Messages
JAXM implementations must adopt a best effort strategy for ensuring the validity of
messages produced and sent to peer entities. JAXM providers, on receiving a mal-
formed message, are responsible for producing an appropriate error message and
sending it to the offending peer entity. The structure and addressing of inter-provider
error messages is Profile-specific. JAXM does not make a distinction between error
messages and any other Profile-specific message. Given that Providers are “Profile-
aware”, they may choose to map an error condition onto a Profile-specific error mes-
sage. Such messages would be delivered to a client in the same manner as any other
message. It is the responsibility of the JAXM client to consume error messages and
take application-specific corrective action.

Messaging Profiles 13
JAXM.2.3 Messaging Profiles
JAXM implementations must support the SOAP1.1 and SOAP Messages with
Attachments specifications. However, these specifications provide a very basic
packaging model and offer no specific addressing scheme or message structure for
the routing of messages between peer entities.
By way of example, a specific Profile may stipulate a specific usage of a
SOAP header. JAXM does not specify what specific XML content must be placed
in the SOAP header, body or attachments. Most enterprise-grade usages of SOAP
messaging will typically specify critical information regarding the sender, recipi-
ent, message ID, and correlation information. The latter is needed to relate
response messages to previous requests.
JAXM implementations may choose to support a number of industry standard
messaging Profiles. Profiles are identified by a name that uniquely identifies a par-
ticular industry/standards body’s usage of SOAP messaging. A JAXM client must
use the URI of the schema associated with a given Profile as the Profile name. For
Example the Profile for ebXML TR&P 1.0 could be identified by the following
URI:
http://www.ebxml.org/project_teams/transport/messageHeader.xsd
Developers are required to specify, either at run-time or at deployment time,

critical system-level information necessary to correctly route, deliver and correlate
messages. The way in which this information is mapped on to a given message
depends on the Profile being used. JAXM makes no assumptions about where this
information, if present, is stored within a message. An explicit contract must
therefore exist between a JAXM client and its Provider. The Profile String is used
to establish this contract at runtime. In order for JAXM applications to be able to
exchange business messages with peer entities, they must have an agreement to
use the same Profile. The way in which such agreements can be established is out-
side the scope of this document.
By way of example, an ebXML MS V1.0 Profile clearly specifies how a
SOAP header should be populated with necessary addressing and message identi-
fication information. A JAXM Application, when using such a Profile, is responsi-
ble for constructing a SOAP header as per the specifications associated with this
Profile. All providers supporting the same Profile (identified by a Profile name)
will therefore have a common understanding of the message structure and mes-
sage semantics. Note that a JAXM client may specify a Profile name when it cre-
ates a MessageFactory object. Message objects produced by such a
MessageFactory object will be specific to the named Profile. In addition, JAXM
14 INFRASTRUCTURE
implementations may choose to pre-populate a Message object with critical infor-

mation, such as the sender and recipient, in a Profile-specific manner.
If an application chooses not to specify a standard Profile, the JAXM
Provider must default to using an application-specific (that is, private) Pro-
file. In such cases, developers cannot be assured of any level of interopera-
bility based on public standards. It is conceivable that a given provider may
support multiple application-specific Profiles.
JAXM.2.4 JAXM Deployment
JAXM Clients may be deployed in Servlet 2.2 and/or J2EETM1.3 containers. It is

anticipated that future versions of the J2EE specification will specify JAXM-spe-
cific deployment information.
Standalone JAXM clients implementing a request-response style of messag-
ing are considered to be J2SE applications. No new deployment requirements will
be introduced for such applications.
JAXM.2.5 AsyncListener
JAXM promotes a standard way of delivering messages asynchronously to JAXM

clients, namely through a message listener interface. In the case of EJB containers,
the AsyncListener interface may be implemented using J2EE Message Driven
Beans (MDB). In the case of Servlet containers, JAXM clients may extend the
JAXMServlet interface and implement the onMessage method.
As mentioned previously, the Provider-to-client contract is based on the
SOAP1.1 (w/attachments) specifications. In other words, irrespective of where a
JAXM client is deployed, a SOAP message enveloping scheme must be used. Fur-
thermore, there is a clear assumption that when a JAXM client is deployed in a
Servlet container, the asynchronous activation model is built on SOAP1.1 (with
attachments) bound to HTTP.
JAXM.2.6 SyncListener
The SyncListener interface is intended to enable the development of request-

response style JAXM services. JAXM services implementing this interface typically
do not require a Provider and the SOAP messages must be bound to HTTP.

Message Security 15
JAXM.2.7 Message Security
JAXM introduces no new security requirements. Messages are assumed to have both
a transitory as well as a persistent confidentiality requirement. Support of security
features and capabilities assuring confidentiality while messages are in transit are an
implementation detail of the JAXM Provider. Although HTTP is the transport of
choice, support for protocols such as SSL may be appropriate and adequate. In the
case of SMTP infrastructures, JAXM providers may choose to use PGP and or S/
MIME.
JAXM provides no specific interfaces to digital signatures that span an entire
message. The assumption is that developers will have access to “user” level por-
tions of a message—where “user” level is defined as the application-specific parts
of a message. Note that the signing or encrypting of the SOAP header in a manner
that would prevent the message from being interpreted and therefore correctly
routed will raise a JAXM exception. A developer may require some application-
specific (and therefore potentially nonstandard) encryption algorithms and/or
security functions to be applied to predefined portions of a message. In such cir-
cumstances, developers must select an appropriate Profile known to the JAXM
provider.
Developers may choose to use digital signature technologies to sign applica-
tion-level XML fragments as they see fit. As mentioned earlier, the application of
specific signing technology must not interfere with the routing of messages by the
JAXM infrastructure.
The authentication of JAXM clients to JAXM providers is considered to be an
implementation detail and beyond the scope of this specification.
16 INFRASTRUCTURE

Package Overview
The following sections provide an overview of the JAXM packages. In addition,

JAXM code samples have been included. Note that the examples are not exhaustive
and should not be considered a normative part of this specification. The intent is to
provide an overview of the packages, the details of which are provided in subse-
quent sections of this document.
JAXM.3.1 javax.xml.messaging Package
The messaging package provides a higher level abstraction than the SOAP package
offers on its own. JAXM clients intending to support asynchronous one-way mes-
saging must do so by using an implementation of the messaging package. The pack-
age includes connection, listener, and endpoint objects.
JAXM.3.1.1 Endpoint & URLEndpoint
In most messaging applications, mes-

sages are typically addressed such that
the recipient and originator of the mes-
sage are conveyed as part of the mes-
sage itself. The notion of self-addressed
messages is fundamental to true mes-
saging since messages can be routed in a manner that is independent of the under-
lying communication infrastructure and network topology. In this sense, the
notion of SOAP messaging is somewhat of a misnomer. The SOAP1.1 specifica-
tions allow for messages to contain the necessary addressing information but do
not define a standard way for this information to be represented within a message.
17
18 PACKAGE OVERVIEW
JAXM therefore relies on Profiles, that is, industry standard usages of SOAP for
interoperable addressing conventions. Given that JAXM supports both one-way
and request-response forms of messaging, the Endpoint object has been modeled
such that it must be specified explicitly on the call method of the SOAPCon-
nection class. By contrast, the send method of the ProviderConnection
class does not allow for the specification of an Endpoint object since there is an
assumption that one-way messaging is inherently asynchronous thus requiring self
dressed (that is, Profiled) messages.
The URLEndpoint object is a

direct subclass of an End-
point class and is intended to
support a special but common
use-case. JAXM clients wishing
to contact a SOAP-based service
in a point-to-point, request-
response (that is, synchronous) manner may choose to do so without utilizing the
services of a JAXM Provider. A URLEndpoint object contains a URL which
would be used in conjunction with the call method to send a message to a SOAP
service and block while waiting for a response from the service.
JAXM.3.1.2 ProviderConnection & Factory
The ProviderConnection and

associated Factory objects must be
used when a JAXM application
requires one-way messaging seman-
tics.
The ProviderConnectionFactory object is an administered object
created by the container (a Servlet or Enterprise JavaBeansTM container) on which
the application has been deployed.
The connections created by the factory will be to a particular messaging pro-
vider. Factory objects are looked up using a logical name in a naming service such
as Java Naming and Directory Interface TM (JNDI) technology.
JAXM clients that choose to use the services of a messaging provider must
first establish a connection to the Provider. In order to do this, the application must
look up the ProviderConnectionFactory object using a pre-configured
logical name. The returned factory object can subsequently be used to create a
specific connection to the messaging provider.
javax.xml.messaging Package 19
The information necessary to set up a ProviderConnectionFactory

is specified at deployment time.
Once a JAXM client has

established a connec-
tion to its messaging
provider, it must then
create profile-specific
MessageFactory
objects. These objects
can subsequently be
used to create SOAPMessage objects. Note that SOAP messages must be “pop-
ulated” in a profile and application-specific manner. The transmission of profiled
SOAP messages is then achieved using the send method of the ProviderCon-
nection class.
JAXM.3.1.3 ProviderMetaData & JAXMException
Provider-specific information can be

obtained using an instance of a Provi-
derMetaData object created using the
getMetaData method of the Pro-
viderConnection object.
A JAXMException
object is a subclass of
SOAPException
and may contain a
String denoting the
reason for the exception
and/or an embedded
Throwable object.
20 PACKAGE OVERVIEW
JAXM.3.1.4 Sync. and async. activation objects
A JAXM service must implement either the AsyncListener or the Syn-

cListener marker interface. The choice of which to implement is application
specific. The AsyncListener interface is intended for application developers
wishing to implement a one-way messaging service. Similarly, SyncListener
is intended to be used by developers wishing to implement a request-response ser-
vice. Irrespective of the type of service being implemented, the onMessage
method of the respective Listener objects must be called by container specific
code hosting the service as opposed to application specific code.
The JAXMServlet class is a utility class, and there is no requirement
that it be implemented or extended. However, a JAXM Service implementation,
deployed in a Servlet container, will need to implement similar functionality in
order to support the required behavior for the two types of Listener interfaces.
Developers who choose to simply extend JAXMServlet must avoid overriding
the doPost method. If they choose to do so, they must faithfully implement the
JAXM Client contract.

javax.xml.soap Package 21
JAXM.3.2 javax.xml.soap Package
The SOAP Package provides the primary abstraction for SOAP Messages
with MIME attachments. Attachments may be entire XML documents, XML frag-
ments, or any other content with a valid MIME type. In addition, this package pro-
vides a simple client side view of a request-response style of interaction with a
SOAP service.
22 PACKAGE OVERVIEW
JAXM.3.2.1 MessageFactory & SOAPMessage objects
The MessageFactory class is used to create SOAPMessage objects. A

JAXM client, implementing request-response style messaging, may create a new
instance of the MessageFactory object using the newInstance method.
Alternatively, where one-way asynchronous messaging is required, the create-
MessageFactory method of the ProviderConnection object must be used.
The SOAPMessage class is the root class for all SOAP messages. Such
messages must contain a SOAPPart and may contain one or more Attach-

mentPart objects. The “on-the-wire” encoding of a SOAP message is governed

by whether the SOAPMessage includes AttachmentPart objects. In the lat-
ter case the SOAPMessage is encoded as a MIME message. An Attachment-
Part object is not required to be in XML format however the SOAPPart must be
in XML format.
JAXM.3.2.2 SOAPPart & AttachmentPart
The SOAPPart object is a MIME part containing the SOAPEnvelope

object. The SOAPEnvelope object must contain a SOAPBody object and may
contain a SOAP-Header object.
24 PACKAGE OVERVIEW
A SOAPMessage object may contain zero or more AttachmentPart

objects. Each AttachmentPart object in turn contains application-specific
content and corresponding MIME headers. The MIME headers consist of name/
value pairs that are used to identify and describe the content. For MIME content-
types of “text/plain”, “text/html” and “text/xml” , the DataContentHandler
object performs the necessary conversions to and from the Java types correspond-
ing to the MIME types. Other MIME types can be supported by passing an

InputStream object (that contains the content data) on the setContent

method of the AttachmentPart object. Similarly, the contents and header
from an AttachmentPart object can be retrieved using the getContent
method. Depending on the AttachmentPart objects present, the returned
Object can either be a typed Java object corresponding to the MIME type or an
InputStream object that contains the content as bytes. The clearContent
method is a helper method intended to facilitate the removal of all the content
from an AttachmentPart object while leaving the header information.
JAXM.3.2.3 MimeHeader(s) objects
The MIMEHeaders class

is a container for Mime-
Header objects and
serves as an abstraction
for the MIME headers that
must be present if an
AttachmentPart
object exists in a SOAP-
Message.
The MimeHeader object is the

abstraction for a name/value pair
of a MIME header. A Mime-
Headers object may contain
one or more MimeHeader
objects.
26 PACKAGE OVERVIEW
JAXM.3.2.4 SOAP Element
The SOAPElement object is the base class for all of the classes that model
the SOAP objects defined by the SOAP1.1 specification. The SOAPElement
object may be used to model the following:
• contents in a SOAPBody object,

• contents in a SOAPHeader object,
• content that can follow the SOAPBody object within a SOAPEnvelope
object,
• whatever may follow the detail element in a SOAPFault.

JAXM.3.2.5 SOAPEnvelope & SOAPBody objects
The SOAPEnvelope is a container object for the SOAPHeader and

SOAPBody portions of a SOAPPart object. The SOAPEnvelope object must
contain a SOAPBody object.
The SOAPEnve-
lope and SOAP-
Body objects both
extend the SOAPEle-
ment object. The
SOAPBody object
models the contents of
the SOAP body ele-
ment in a SOAP mes-
sage. A SOAP body
element contains XML data that may determine how application-specific content
must be processed.
28 PACKAGE OVERVIEW
SOAPBody objects contain SOAP-

BodyElement objects that model
the content of the SOAP body. An
example of a SOAPBodyElement is
the SOAPFault object.
JAXM.3.2.6 SOAPHeader & SoapHeaderElement
A SOAPHeader
object is an abstrac-
tion of the SOAP
header element. A
SOAPHeader
object can be created
using the getEnve-
lope method of the SOAPPart object. SOAPHeader objects can have only
SOAPHeaderElement objects as their immediate children. The addHead-
erElement method creates a new HeaderElement object and adds it to the
SOAPHeader object.

SOAPHeader and
SOAPHeaderEle-
ment objects both
extend the SOAPEle-
ment object. A SOAP-
HeaderElement
object models the contents
of the SOAP header of a
SOAP envelope.
JAXM.3.2.7 SOAPConnection
The SOAPConnection object represents a simple client-side view of a

request-response style SOAP messaging service. A JAXM client may choose to
establish a synchronous point-to-point connection to a SOAP service using the
newInstance static method of the SOAPConnection object. Subsequently,
a SOAPMessage may be sent to a remote party (identified by an Endpoint)
using the call method on the SOAPConnection object. Note that the call
method will block until a SOAPMessage object is received.
A JAXM application may choose to use the call method to implement the
client side of a simple point-to-point synchronous one-way message exchange
scenario. In such a case, it is the application’s responsibility to ignore the SOAP-
Message returned on the call object. It is assumed that the one-way service
will not return a response message on the same SOAPConnection as the one
on which the original request was received. However, the one-way service must
acknowledge the request and hence unblock the client.
30 PACKAGE OVERVIEW
JAXM.3.2.8 SOAPException object
The SOAPException
object extends
java.lang.Excep-
tion and is used to sig-
nal SOAP level
exceptions.
JAXMException fur-
ther extends SOAPEx-
ception.
JAXM.3.2.9 Node & Text objects
The Node object models a

node (element) of a DOM
abstraction of an XML docu-
ment.
The Text object extends Node and represents a

node whose value is text. A Text object may
model either text that is content or text that is a
comment.

A simple Message Producer example 31
JAXM.3.2.10 Name, Detail & DetailEntry
The Name object models an XML name. This

interface provides methods for getting the
local names, namespace-qualified names, the
prefix associated with the namespace for the
name, and the URI of the namespace.
Name objects are created using the SOAP-
Envelope.createName method.
The Detail object is a

container for DetailEn-
try objects. A Detail
object is part of a SOAP-
Fault object and may be
retrieved using the getDe-
tail method of the SOAP-
Fault object.
The DetailEntry object extends SOAPElement and

models the contents of a Detail object. A DetailEntry
object, conveys application-specific information about errors
related to the Body element.
JAXM.3.3 A simple Message Producer example
/*
* $Id: SendingServlet.java,v 1.5 2001/08/04 01:58:19 mode Exp $
* $Revision: 1.5 $
* $Date: 2001/08/04 01:58:19 $
*
* Copyright 2000-2001 by Sun Microsystems, Inc.,
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All rights reserved.
32 PACKAGE OVERVIEW
*
* This software is the confidential and proprietary information
* of Sun Microsystems, Inc. ("Confidential Information"). You
* shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Sun.
*/
package simple.sender;
import java.net.*;
import java.io.*;
import java.util.*;
import javax.servlet.http.*;
import javax.servlet.*;
import javax.xml.messaging.*;
import javax.xml.soap.*;
import javax.activation.*;
import javax.naming.*;
import org.apache.log4j.*;
/**
* Sample servlet that is used for sending the message.
*
* @author Rajiv Mordani (rajiv.mordani@sun.com)
* @author Anil Vijendran (anil@sun.com)
*/
public class SendingServlet extends HttpServlet {
static Category
logger = Category.getInstance("Samples/Simple");
String to = "http://127.0.0.1:8080/simple/receiver";
String data = "http://127.0.0.1:8080/simple/index.html";
ServletContext servletContext;
// Connection to send messages.

private SOAPConnection con;
public void init(ServletConfig servletConfig) throws

ServletException
{
super.init( servletConfig );
servletContext = servletConfig.getServletContext();
try {
con = SOAPConnection.newInstance();
} catch(Exception e) {
logger.error("Unable to open a SOAPConnection", e);
}
InputStream in
= servletContext.getResourceAsStream(
"/WEB-INF/address.properties");
if (in != null) {
Properties props = new Properties();
try {
props.load(in);
String to = props.getProperty("to");
String data = props.getProperty("data");
if (to != null)
this.to = to;
if (data != null)
this.data = data;
} catch (IOException ex) {
// Ignore
}
}
}
public void doGet(HttpServletRequest req,

HttpServletResponse resp)
throws ServletException
{
try {
// Create a message factory.
MessageFactory mf = MessageFactory.newInstance();
// Create a message from the message factory.

SOAPMessage msg = mf.createMessage();
34 PACKAGE OVERVIEW
// Message creation takes care of creating the

// SOAPPart - a required part of the message as
// per the SOAP 1.1 specification.
SOAPPart sp = msg.getSOAPPart();
// Retrieve the envelope from the soap part to start

// building the soap message.
SOAPEnvelope envelope = sp.getEnvelope(true);
// Create a soap header from the envelope.

SOAPHeader hdr = envelope.getHeader();
// Create a soap body from the envelope.

SOAPBody bdy = envelope.getBody();
// Add a soap body element to the soap body

SOAPBodyElement gltp = bdy.addBodyElement(
envelope.createName(
"GetLastTradePrice",
"ztrade",
"http://wombat.ztrade.com"));
gltp.addChildElement(envelope.createName("symbol",
"ztrade",
"http://wombat.ztrade.com")).addTextNode("SUNW");
// Want to set an attachment from the following url.

//Get context
URL url = new URL(data);
AttachmentPart ap =
msg.createAttachmentPart(new DataHandler(url));
ap.setContentType("text/html");
// Add the attachment part to the message.

msg.addAttachmentPart(ap);
// Create an endpoint for the recipient of the message.

URLEndpoint urlEndpoint = new URLEndpoint(to);
System.err.println("<html>");

System.err.println("Sending message to URL: "

+urlEndpoint.getURL());
System.err.println(
"Sent message is logged in \"sent.msg\"");
FileOutputStream sentFile = new

FileOutputStream("sent.msg");
msg.writeTo(sentFile);
sentFile.close();
// Send the message to the provider using the connection.

SOAPMessage reply = con.call(msg, urlEndpoint);
if (reply != null) {
FileOutputStream replyFile = new
FileOutputStream("reply.msg");
reply.writeTo(replyFile);
replyFile.close();
System.err.println("Reply logged in \"reply.msg\"");
} else
System.err.println("No reply");
String retval =
"<html><H4>Sent Message (check \"sent.msg\" and \"reply.msg\""+
" files for the sent and received messages)</H4></html>";
OutputStream os = resp.getOutputStream();
os.write(retval.getBytes());
os.flush();
os.close();
} catch(Throwable e) {
logger.error("Error in constructing or sending message "
+e.getMessage());
}
}
}
36 PACKAGE OVERVIEW
JAXM.3.4 A simple Message Consumer example
/*
* $Id: ReceivingServlet.java,v 1.2 2001/08/02 09:24:19 akv Exp $
* $Revision: 1.2 $
* $Date: 2001/08/02 09:24:19 $
*
* Copyright 2000-2001 by Sun Microsystems, Inc.,
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All rights reserved.
*
* This software is the confidential and proprietary information
* of Sun Microsystems, Inc. ("Confidential Information"). You
* shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Sun.
*/
package simple.receiver;
import javax.xml.messaging.*;
import javax.xml.soap.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.xml.transform.*;
import javax.naming.*;
import org.apache.log4j.*;
/**
* Sample servlet that receives messages.
*
* @author Rajiv Mordani (mode@eng.sun.com)
* @author Anil Vijendran (anil@sun.com)
*/
public class ReceivingServlet extends JAXMServlet {
static Category
logger = Category.getInstance("Samples/Simple");
public void init(ServletConfig servletConfig) throws

ServletException

A simple Message Consumer example 37
{
super.init(servletConfig);
// Not much there to do here.
}
/*
This is the application code for handling the message..
Once the message is received the application can retrieve
the soap part, the attachment parts if there are any, or any
other information from the message.
*/
public SOAPMessage onMessage(SOAPMessage message) {

System.out.println("On message called in receiving servlet");
SOAPMessage msg = null;
try {
System.out.println("Here's the message: ");
message.writeTo(System.out);
msg = msgFactory.createMessage();
SOAPEnvelope envelope =
msg.getSOAPPart().getEnvelope(true);
SOAPBody body = envelope.getBody();
body.addBodyElement(envelope.createName(
"GetLastTradePriceResponse",
"ztrade", "http://wombat.ztrade.com"))
.addChildElement("Price")
.addTextNode("95.12");
} catch(Exception e) {
logger.error(
"Error in processing or replying to a message", e);
}
return msg;
}
}
38 PACKAGE OVERVIEW

Package javax.xml.messaging
Class Summary
Interfaces
AsyncListener40 A marker interface for components (for example, servlets) that are intended to be con-
sumers of JAXM messages.
ProviderConnection49 A client’s active connection to its messaging provider.
ProviderConnectionFac A factory for creating connections to a particular messaging provider.
tory52
ProviderMetaData53 Information about the messaging provider to which a client has a connection.
SyncListener55 A marker interface for components (for example, servlets) that are intended to be con-
sumers of JAXM messages.
Classes
Endpoint41 An opaque representation of an application endpoint.
JAXMServlet45 The superclass for components that live in a servlet container that receives JAXM mes-
sages.
URLEndpoint56 A special case of the Endpoint class used for simple applications that want to com-
municate directly with another SOAP-based application instead of going through a
provider.
Exceptions
JAXMException43 An exception that signals that a JAXM exception has occurred.
39
AsyncListener javax.xml.messaging
onMessage(SOAPMessage)
javax.xml.messaging
AsyncListener
Declaration
public interface AsyncListener
Description
A marker interface for components (for example, servlets) that are intended to be consumers of JAXM mes-
sages. Components that implement this interface are intended just for message receives.
See Also: JAXMServlet45
Member Summary
Methods
public void onMessage(SOAPMessage)40
Passes the given SOAPMessage object to this AsyncListener object.
Methods
public void onMessage(SOAPMessage110 message)

Passes the given SOAPMessage object to this AsyncListener object. This method is invoked behind
the scenes, typically by the container (servlet or EJB container) after the messaging provider delivers the
message to the container. It is expected that EJB Containers will deliver JAXM messages to EJB compo-
nents using message driven Beans that implement the javax.xml.messaging.AsyncListener
interface.
Parameters:
message - the SOAPMessage object to be passed to this AsyncListener object
40
javax.xml.messaging Endpoint
javax.xml.messaging
Endpoint
Declaration
public class Endpoint

java.lang.Object
|
+--javax.xml.messaging.Endpoint
Direct Known Subclasses: URLEndpoint56
Description
An opaque representation of an application endpoint. Typically, an Endpoint object represents a business
entity, but it may represent a party of any sort. Conceptually, an Endpoint object is the mapping of a logical
name (example, a URI) to a physical location, such as a URL.
For messaging using a provider that supports profiles, an application does not need to specify an endpoint when
it sends a message because destination information will be contained in the profile-specific header. However, for
point-to-point plain SOAP messaging, an application must supply an Endpoint object to the SOAPConnec-
tion method call to indicate the intended destination for the message. The subclass URLEndpoint56 can
be used when an application wants to send a message directly to a remote party without using a messaging pro-
vider.
The default identification for an Endpoint object is a URI. This defines what JAXM messaging providers
need to support at minimum for identification of destinations. A messaging provider needs to be configured
using a deployment-specific mechanism with mappings from an endpoint to the physical details of that end-
point.
Endpoint objects can be created using the constructor, or they can be looked up in a naming service. The lat-
ter is more flexible because logical identifiers or even other naming schemes (such as DUNS numbers) can be
bound and rebound to specific URIs.
Member Summary
Fields
protected id42
A string that identifies the party that this Endpoint object represents; a URI is the
default.
Constructors
public Endpoint(String)42
Constructs an Endpoint object using the given string identifier.
Methods
public String toString()42
Retrieves a string representation of this Endpoint object.
41
Endpoint javax.xml.messaging
id
Inherited Member Summary

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Fields
id
protected java.lang.String id
A string that identifies the party that this Endpoint object represents; a URI is the default.
Constructors
Endpoint(String)
public Endpoint(java.lang.String uri)

Constructs an Endpoint object using the given string identifier.
Parameters:
uri - a string that identifies the party that this Endpoint object represents
Methods
toString()
public java.lang.String toString()

Retrieves a string representation of this Endpoint object. This string is likely to be provider-specific, and
programmers are discouraged from parsing and programmatically interpreting the contents of this string.
Overrides: java.lang.Object.toString() in class java.lang.Object
Returns: a String with a provider-specific representation of this Endpoint object
42
javax.xml.messaging JAXMException
toString()
javax.xml.messaging
JAXMException
Declaration
public class JAXMException extends SOAPException99
java.lang.Object
|
+--java.lang.Throwable
|
+--java.lang.Exception
|
+--javax.xml.soap.SOAPException99
|
+--javax.xml.messaging.JAXMException
All Implemented Interfaces: java.io.Serializable
Description
An exception that signals that a JAXM exception has occurred. A JAXMException object may contain a
String that gives the reason for the exception, an embedded Throwable object, or both. This class provides
methods for retrieving reason messages and for retrieving the embedded Throwable object.
Typical reasons for throwing a JAXMException object are problems such as, not being able to send a mes-
sage, and not being able to get a connection with the provider. Reasons for embedding a Throwable object
include problems such as an input/output errors or a parsing problem, such as an error parsing a header.
Member Summary
Constructors
public JAXMException()44
Constructs a JAXMException object with no reason or embedded Throwable
object.
public JAXMException(String)44
Constructs a JAXMException object with the given String as the reason for the
exception being thrown.
public JAXMException(String, Throwable)44
Constructs a JAXMException object with the given String as the reason for the
exception being thrown and the given Throwable object as an embedded exception.
public JAXMException(Throwable)44
Constructs a JAXMException object initialized with the given Throwable object.

43
JAXMException javax.xml.messaging
JAXMException()

Methods inherited from interface SOAPException99

getCause()101, getMessage()101, initCause(Throwable)101
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, printStackTrace, printStackTrace, printStack-
Trace, toString
Constructors
JAXMException()
public JAXMException()
Constructs a JAXMException object with no reason or embedded Throwable object.
JAXMException(String)
public JAXMException(java.lang.String reason)

Constructs a JAXMException object with the given String as the reason for the exception being
thrown.
Parameters:
reason - a String giving a description of what caused this exception
JAXMException(String, Throwable)
public JAXMException(java.lang.String reason, java.lang.Throwable cause)

Constructs a JAXMException object with the given String as the reason for the exception being
thrown and the given Throwable object as an embedded exception.
Parameters:
reason - a String giving a description of what caused this exception
cause - a Throwable object that is to be embedded in this JAXMException object
JAXMException(Throwable)
public JAXMException(java.lang.Throwable cause)

Constructs a JAXMException object initialized with the given Throwable object.
Parameters:
cause - a Throwable object that is to be embedded in this JAXMException object
44
javax.xml.messaging JAXMServlet
JAXMException(Throwable)
javax.xml.messaging
JAXMServlet
Declaration
public abstract class JAXMServlet extends javax.servlet.http.HttpServlet

java.lang.Object
|
+--javax.servlet.GenericServlet
|
+--javax.servlet.http.HttpServlet
|
+--javax.xml.messaging.JAXMServlet
All Implemented Interfaces: java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig
Description
The superclass for components that live in a servlet container that receives JAXM messages. A JAXMServlet
object is notified of a message’s arrival using the HTTP-SOAP binding.
The JAXMServlet class is a support/utility class and is provided purely as a convenience. It is not a manda-
tory component, and there is no requirement that it be implemented or extended.
Note that when a component that receives messages extends JAXMServlet, it also needs to implement either
a SyncListener or an AsyncListener depending on whether the component is written for request-
response style interaction or just asynchronous receives.
Member Summary
Fields
protected msgFactory46
The MessageFactory object that will be used internally to create the SOAPMes-
sage object to be passed to the method onMessage.
Constructors
public JAXMServlet()47
Methods
public void doPost(HttpServletRequest, HttpServletResponse)47
Internalizes the given HttpServletRequest object and writes the reply to the
given HttpServletResponse object.
protected static Mime- getHeaders(HttpServletRequest)47
Headers Returns a MimeHeaders object that contains the headers in the given Http-
ServletRequest object.
public void init(ServletConfig)47
Initializes this JAXMServlet object using the given ServletConfig object and
initializing the msgFactory field with a default MessageFactory object.
protected static void putHeaders(MimeHeaders, HttpServletResponse)48
Sets the given HttpServletResponse object with the headers in the given
MimeHeaders object.
45
JAXMServlet javax.xml.messaging
msgFactory
Member Summary
public void setMessageFactory(MessageFactory)48
Sets this JAXMServlet object’s msgFactory field with the given Message-
Factory object.

Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletCon-
text, getServletInfo, getServletName, init, log, log
Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doOptions, doPut, doTrace, getLastModified, service, service

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait,
wait
Fields
msgFactory
protected MessageFactory70 msgFactory

The MessageFactory object that will be used internally to create the SOAPMessage object to be
passed to the method onMessage. This new message will contain the data from the message that was
posted to the servlet. Using the MessageFactory object that is the value for this field to create the new
message ensures that the correct profile is used.
46
javax.xml.messaging JAXMServlet
JAXMServlet()
Constructors
JAXMServlet()
public JAXMServlet()
Methods
doPost(HttpServletRequest, HttpServletResponse)
public void doPost(javax.servlet.http.HttpServletRequest req,

javax.servlet.http.HttpServletResponse resp)
throws ServletException, IOException
Internalizes the given HttpServletRequest object and writes the reply to the given HttpServlet-
Response object.
Note that the value for the msgFactory field will be used to internalize the message. This ensures that the
message factory for the correct profile is used.
Overrides: javax.servlet.http.HttpServlet.doPost(javax.servlet.http.HttpServletRequest,
javax.servlet.http.HttpServletResponse) in class javax.servlet.http.HttpServlet
Parameters:
req - the HttpServletRequest object containing the message that was sent to the servlet
resp - the HttpServletResponse object to which the response to the message will be written
Throws:
ServletException - if there is a servlet error
IOException - if there is an input or output error
getHeaders(HttpServletRequest)
protected static MimeHeaders75 getHeaders(javax.servlet.http.HttpServletRequest req)

Returns a MimeHeaders object that contains the headers in the given HttpServletRequest object.
Parameters:
req - the HttpServletRequest object that a messaging provider sent to the servlet
Returns: a new MimeHeaders object containing the headers in the message sent to the servlet
init(ServletConfig)
public void init(javax.servlet.ServletConfig servletConfig)

throws ServletException
Initializes this JAXMServlet object using the given ServletConfig object and initializing the msg-
Factory field with a default MessageFactory object.
47
JAXMServlet javax.xml.messaging
putHeaders(MimeHeaders, HttpServletResponse)
Overrides: javax.servlet.GenericServlet.init(javax.servlet.ServletConfig) in class

javax.servlet.GenericServlet
Parameters:
servletConfig - the ServletConfig object to be used in initializing this JAXMServlet
object
Throws:
ServletException
putHeaders(MimeHeaders, HttpServletResponse)
protected static void putHeaders(MimeHeaders75 headers,

javax.servlet.http.HttpServletResponse res)
Sets the given HttpServletResponse object with the headers in the given MimeHeaders object.
Parameters:
headers - the MimeHeaders object containing the the headers in the message sent to the servlet
res - the HttpServletResponse object to which the headers are to be written
See Also: getHeaders(HttpServletRequest)47
setMessageFactory(MessageFactory)
public void setMessageFactory(MessageFactory70 msgFactory)

Sets this JAXMServlet object’s msgFactory field with the given MessageFactory object. A
MessageFactory object for a particular profile needs to be set before a message is received in order for
the message to be successfully internalized.
Parameters:
msgFactory - the MessageFactory object that will be used to create the SOAPMessage object
that will be used to internalize the message that was posted to the servlet
48
javax.xml.messaging ProviderConnection
setMessageFactory(MessageFactory)
javax.xml.messaging
ProviderConnection
Declaration
public interface ProviderConnection
Description
A client’s active connection to its messaging provider.
A ProviderConnection object is created using a ProviderConnectionFactory object, which is
configured so that the connections it creates will be to a particular messaging provider. To create a connection, a
client first needs to obtain an instance of the ProviderConnectionFactory class that creates connections
to the desired messaging provider. The client then calls the createConnection method on it to get a
ProviderConnection object that connects the client with its messaging provider.
The information necessary to set up a ProviderConnectionFactory that creates connections to a partic-
ular messaging provider is provided at deployment time. Typically an instance of ProviderConnection-
Factory will be bound to a logical name in a naming service. Later the client can do a lookup on the logical
name to retrieve an instance of the ProviderConnectionFactory class that produces connections to its
messaging provider.
The following code fragment is an example of a client doing a lookup of a ProviderConnectionFactory
object and then using it to create a connection. The first two lines in this example use the JavaTM Naming and
Directory Interface (JNDI) to create a context, which is then used to do the lookup. The argument provided to
the lookup method is the logical name that was previously associated with the desired messaging provider.
The lookup method returns a Java Object, which needs to be cast to a ProviderConnectionFactory
object before it can be used to create a connection. In the following code fragment, the resulting Provider-
Connection object is a connection to the messaging provider that is associated with the logical name
“ProviderXYZ”.
Context ctx = new InitialContext();
ProviderConnectionFactory pcf = (ProviderConnectionFactory)ctx.lookup(“ProviderXYZ”);
ProviderConnection con = pcf.createConnection();
After the client has obtained a connection to its messaging provider, it can use that connection to create one or
more MessageFactory objects, which can then be used to create SOAPMessage objects. Messages are
delivered to an endpoint using the ProviderConnection method send.
The messaging provider maintains a list of Endpoint objects, which is established at deployment time as part
of configuring the messaging provider. When a client uses a messaging provider to send messages, it can send
messages only to those parties represented by Endpoint objects in its messaging provider’s list. This is true
because the messaging provider maps the URI for each Endpoint object to a URL.
Note that it is possible for a client to send a message without using a messaging provider. In this case, the client
uses a SOAPConnection object and sends the message directly to its destination using a URL. See
SOAPConnection87 and URLEndpoint56 for more information.
Typically, because clients have one messaging provider, they will do all their messaging with a single
ProviderConnection object. It is possible, however, for a sophisticated application to use multiple con-
nections.
49
ProviderConnection javax.xml.messaging
close()
Generally, a container is configured with a Listener component at deployment time using an implementation-
specific mechanism. A client running in such a container will use a listener object to receive messages, which
means that the client can receive messages asynchronously. In this scenario, the ProviderConnection
method send is used to send a message.
By contrast, a client that is running as a standalone application, and therefore has no Listener object, is unable to
send and receive messages asynchronously. If a client wants a response to a message, it must send the message
using the ProviderConnection method call. This method will send the message and block until it gets a
response, which it then returns to the client that sent the original message. In this synchronous messaging sce-
nario, the client cannot send another message until after the response is returned.
Due to the authentication and communication setup done when a ProviderConnection object is created, it
is a relatively heavy-weight object. Therefore, a client should close its connection as soon as it is done using it.
JAXM objects created using one ProviderConnection object cannot be used with a different
ProviderConnection object.
Member Summary
Methods
public void close()50
Closes this ProviderConnection object, freeing its resources and making it
immediately available for garbage collection.
public MessageFactory createMessageFactory(String)51
Creates a MessageFactory object that will produce SOAPMessage objects for
the given profile.
public ProviderMeta- getMetaData()51
Data Retrieves the ProviderMetaData object that contains information about the mes-
saging provider to which this ProviderConnection object is connected.
public void send(SOAPMessage)51
Sends the given SOAPMessage object and returns immediately after handing the
message over to the messaging provider.
Methods
close()
public void close()

throws JAXMException
Closes this ProviderConnection object, freeing its resources and making it immediately available for
garbage collection. Since a provider typically allocates significant resources outside the JVM on behalf of a
connection, clients should close connections when they are not needed. Relying on garbage collection to
eventually reclaim these resources may not be timely enough.
Throws:
JAXMException43 - if a JAXM error occurs while closing the connection.
50
javax.xml.messaging ProviderConnection
createMessageFactory(String)
createMessageFactory(String)
public MessageFactory70 createMessageFactory(java.lang.String profile)

Creates a MessageFactory object that will produce SOAPMessage objects for the given profile. The
MessageFactory object that is returned can create instances of SOAPMessage subclasses as appropri-
ate for the given profile.
Parameters:
profile - a string that represents a particular JAXM profile in use. An example of a JAXM profile is:
“ebxml”.
Returns: a new MessageFactory object that will create SOAPMessage objects for the given profile
Throws:
JAXMException43 - if the JAXM infrastructure encounters an error, for example, if the endpoint
that is being used is not compatible with the specified profile
getMetaData()
public ProviderMetaData53 getMetaData()

Retrieves the ProviderMetaData object that contains information about the messaging provider to
which this ProviderConnection object is connected.
Returns: the ProviderMetaData object with information about the messaging provider
Throws:
JAXMException43
See Also: ProviderMetaData53
send(SOAPMessage)
public void send(SOAPMessage110 message)

Sends the given SOAPMessage object and returns immediately after handing the message over to the mes-
saging provider. No assumptions can be made regarding the ultimate success or failure of message delivery
at the time this method returns.
Parameters:
message - the SOAPMessage object that is to be sent asynchronously
Throws:
JAXMException43 - if a JAXM transmission error occurs
51
ProviderConnectionFactory javax.xml.messaging
createConnection()
javax.xml.messaging
ProviderConnectionFactory
Declaration
public interface ProviderConnectionFactory
Description
A factory for creating connections to a particular messaging provider. A ProviderConnectionFactory
object is an administered object that is created by the container (a servlet or Enterprise JavaBeansTM container)
in which an application runs.
A ProviderConnectionFactory object is configured in an implementation- specific way, and the con-
nections it creates will be to a particular messaging provider. A ProviderConnectionFactory object is
registered with a naming service, such as one based on Java Naming and Directory InterfaceTM (JNDI) technol-
ogy. This registration associates the ProviderConnectionFactory object with a logical name. When an
application wants to establish a connection with the provider associated with that ProviderConnection-
Factory object, it does a lookup, providing the logical name. The application can then use the Provider-
ConnectionFactory object that is returned to create a connection to the messaging provider.
Member Summary
Methods
public ProviderCon- createConnection()52
nection Creates a ProviderConnection object to the messaging provider that is the pro-
vider associated with this ProviderConnectionFactory object.
Methods
createConnection()
public ProviderConnection49 createConnection()

Creates a ProviderConnection object to the messaging provider that is the provider associated with
this ProviderConnectionFactory object.
Returns: a ProviderConnection object that represents a connection to the provider associated with
this ProviderConnectionFactory object
Throws:
JAXMException43 - if there is an error in creating the connection
52
javax.xml.messaging ProviderMetaData
createConnection()
javax.xml.messaging
ProviderMetaData
Declaration
public interface ProviderMetaData
Description
Information about the messaging provider to which a client has a connection.
After obtaining a connection to its messaging provider, a client can get information about that provider. The fol-
lowing code fragment demonstrates how the ProviderConnection object con can be used to retrieve its
ProviderMetaData object and then to get the name and version number of the messaging provider.
ProviderMetaData pmd = con.getMetaData();
String name = pmd.getProviderName();
int majorVersion = pmd.getProviderMajorVersion();
int minorVersion = pmd.getProviderMinorVersion();
Member Summary
Methods
public int getMajorVersion()54
Retrieves an int indicating the major version number of the messaging provider to
which the ProviderConnection object described by this ProviderMeta-
Data object is connected.
public int getMinorVersion()54
Retrieves an int indicating the minor version number of the messaging provider to
which the ProviderConnection object described by this ProviderMeta-
public String getName()54
Retrieves a String containing the name of the messaging provider to which the
ProviderConnection object described by this ProviderMetaData object is
connected.
public String[] getSupportedProfiles()54
Retrieves a list of the messaging profiles that are supported by the messaging provider
to which the ProviderConnection object described by this ProviderMeta-
53
ProviderMetaData javax.xml.messaging
getMajorVersion()
Methods
getMajorVersion()
public int getMajorVersion()

Retrieves an int indicating the major version number of the messaging provider to which the
ProviderConnection object described by this ProviderMetaData object is connected.
Returns: the messaging provider’s major version number as an int
getMinorVersion()
public int getMinorVersion()

Retrieves an int indicating the minor version number of the messaging provider to which the
Returns: the messaging provider’s minor version number as an int
getName()
public java.lang.String getName()

Retrieves a String containing the name of the messaging provider to which the Provider-
Connection object described by this ProviderMetaData object is connected. This string is provider
implementation-dependent. It can either describe a particular instance of the provider or just give the name
of the provider.
Returns: the messaging provider’s name as a String
getSupportedProfiles()
public java.lang.String[] getSupportedProfiles()

Retrieves a list of the messaging profiles that are supported by the messaging provider to which the
Returns: a String array in which each element is a messaging profile supported by the messaging
provider
54
javax.xml.messaging SyncListener
javax.xml.messaging
SyncListener
Declaration
public interface SyncListener
Description
A marker interface for components (for example, servlets) that are intended to be consumers of JAXM mes-
sages. Components that implement this interface are intended for request-response style interaction.
See Also: JAXMServlet45
Member Summary
Methods
public SOAPMessage onMessage(SOAPMessage)55
Passes the given SOAPMessage object to this SyncListener object and returns
the response.
Methods
public SOAPMessage110 onMessage(SOAPMessage110 message)

Passes the given SOAPMessage object to this SyncListener object and returns the response. This
method is invoked behind the scenes, typically by the container (servlet or EJB container) after the messag-
ing provider delivers the message to the container. It is expected that EJB Containers will deliver JAXM
messages to EJB components using message driven Beans that implement the
javax.xml.messaging.SyncListener interface.
Parameters:
message - the SOAPMessage object to be passed to this SyncListener object
Returns: the response. If this is null, then the original message is treated as a “oneway” message.
55
URLEndpoint javax.xml.messaging
javax.xml.messaging
URLEndpoint
Declaration
public class URLEndpoint extends Endpoint41
java.lang.Object
|
+--javax.xml.messaging.Endpoint41
|
+--javax.xml.messaging.URLEndpoint
Description
A special case of the Endpoint class used for simple applications that want to communicate directly with
another SOAP-based application instead of going through a provider.
A URLEndpoint object contains a URL, which is used to make connections to the remote party. A standalone
client can pass a URLEndpoint object to the SOAPConnection method call to send a message synchro-
nously.
Since: 0.93
Member Summary
Constructors
public URLEndpoint(String)57
Constructs a new URLEndpoint object using the given URL.
Methods
public String getURL()57
Gets the URL associated with this URLEndpoint object.

Fields inherited from class Endpoint41
id42
Methods inherited from class Endpoint41

toString()42

56
javax.xml.messaging URLEndpoint
URLEndpoint(String)
Constructors
URLEndpoint(String)
public URLEndpoint(java.lang.String url)

Constructs a new URLEndpoint object using the given URL.
Parameters:
url - a String giving the URL to use in constructing the new URLEndpoint object
Methods
getURL()
public java.lang.String getURL()

Gets the URL associated with this URLEndpoint object.
Returns: a String giving the URL associated with this URLEndpoint object
57
URLEndpoint javax.xml.messaging
getURL()
58
Package javax.xml.soap
Class Summary
Interfaces
Detail68 A container for DetailEntry objects.
DetailEntry69 The content for a Detail object, giving details for a SOAPFault object.
Name79 A representation of an XML name.
Node81 A representation of a node (element) in a DOM representation of an XML document
that provides some tree manipulation methods.
SOAPBody83 An object that represents the contents of the SOAP body element in a SOAP message.
SOAPBodyElement86 A SOAPBodyElement object represents the contents in a SOAPBody object.
SOAPConstants89 This interface defines a number of constants pertaining to the SOAP 1.1 protocol.
SOAPElement90 An object representing the contents in a SOAPBody object, the contents in a SOAP-
Header object, the content that can follow the SOAPBody object in a SOAPEnve-
lope object, or what can follow the detail element in a SOAPFault object.
SOAPEnvelope96 The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
SOAPFault103 An object that contains error and/or status information within a SOAP message.
SOAPHeader105 A SOAPHeader object represents the contents of the SOAP header element.
SOAPHeaderElement108 An object representing the contents in the SOAP header part of the SOAP envelope.
Text122 A representation of a node whose value is text.
Classes
AttachmentPart61 A single attachment to a SOAPMessage object.
MessageFactory70 A factory for creating SOAPMessage objects.
MimeHeader73 An object that stores a MIME header name and its value.
MimeHeaders75 A container for MimeHeader objects, which represent the MIME headers present in
a MIME part of a message.
59
Class Summary
SOAPConnection87 A connection that a client can use for sending messages directly to a remote party (rep-
resented by a URL, for instance) without using a messaging provider.
SOAPMessage110 The root class for all SOAP messages.
SOAPPart116 The container for the SOAP-specific portion of a SOAPMessage object.
Exceptions
SOAPException99 An exception that signals that a SOAP exception has occurred.
60
javax.xml.soap
AttachmentPart
Declaration
public abstract class AttachmentPart

java.lang.Object
|
+--javax.xml.soap.AttachmentPart
Description
A single attachment to a SOAPMessage object. A SOAPMessage object may contain zero, one, or many
AttachmentPart objects. Each AttachmentPart object consists of two parts, application-specific con-
tent and associated MIME headers. The MIME header consists of name/value pairs that could be used identify
and describe the content.
An AttachmentPart object must conform to certain standards.
1. It must conform to MIME [RFC2045] standards (http://www.ietf.org/rfc/rfc2045.txt)
2. It MUST contain content
3. The header portion MUST include the following header:
• Content-Type
This header identifies the type of data in the content of an AttachmentPart object and MUST conform
to [RFC2045]. The following is an example of a Content-Type header:
Content-Type: application/xml
The following line of code, in which ap is an AttachmentPart object, sets the header in the exam-
ple.
ap.setMimeHeader(“Content-Type”, “application/xml”);
There are no restrictions on the content portion of an AttachmentPart object. The content may be any-
thing from a simple plain text object to a complex XML document or image file.
An AttachmentPart object is created with the method SOAPMessage.createAttachmentPart.
After setting its MIME headers, the AttachmentPart object is added to the message that created it with the
method SOAPMessage.addAttachmentPart.
The following code fragment, in which m is a SOAPMessage object and contentStringl is a String,
creates an instance of AttachmentPart, sets the AttachmentPart object with some content and header
information, and adds the AttachmentPart object to the SOAPMessage object.
AttachmentPart ap1 = m.createAttachmentPart();
ap1.setContent(contentString1, “text/plain”);
m.addAttachmentPart(ap1);
For “text/plain”, “text/html” and “text/xml” MIME content-types, the DataContentHandler object does
the conversions to and from the Java types corresponding to the MIME types. For other MIME types, you can
pass an InputStream object that contains the content data.
The following code fragment creates and adds a second AttachmentPart instance to the same message.
jpegData is a binary byte buffer representing the jpeg file.
61
AttachmentPart ap2 = m.createAttachmentPart();

byte[] jpegData = ...;
ap2.setContent(new ByteArrayInputStream(jpegData), “image/jpeg”);
m.addAttachmentPart(ap2);
To retrieve the contents and header from an AttachmentPart object, the getContent method can be
used. Depending on the DataContentHandler objects present, the returned Object can either be a typed
Java object corresponding to the MIME type or an InputStream object that contains the content as bytes.
The method clearContent removes all the content from an AttachmentPart object but does not affect
its header information.
ap1.clearContent();
Member Summary
Constructors
public AttachmentPart()63
Methods
public abstract void addMimeHeader(String, String)63
Adds a MIME header with the specified name and value to this AttachmentPart
object.
public abstract void clearContent()64
Clears out the content of this AttachmentPart object.
public abstract Itera- getAllMimeHeaders()64
tor Retrieves all the headers for this AttachmentPart object as an iterator over the
MimeHeader objects.
public abstract Object getContent()64
Gets the content of this AttachmentPart object as a Java object.
public String getContentId()64
Gets the value of the MIME header whose name is “Content-Id”.
public String getContentLocation()64
Gets the value of the MIME header “Content-Location”.
public String getContentType()65
Gets the value of the MIME header “Content-Type”.
public abstract DataH- getDataHandler()65
andler Gets the DataHandler object for this AttachmentPart object.
public abstract Itera- getMatchingMimeHeaders(String[])65
tor Retrieves all MimeHeader objects that match a name in the given array.
public abstract getMimeHeader(String)65
String[] Gets all the values of the header identified by the given String.
public abstract Itera- getNonMatchingMimeHeaders(String[])65
tor Retrieves all MimeHeader objects whose name does not match a name in the given
array.
public abstract int getSize()66
Returns the number of bytes in this AttachmentPart object.
public abstract void removeAllMimeHeaders()66
Removes all the MIME header entries.
public abstract void removeMimeHeader(String)66
Removes all MIME headers that match the given name.
public abstract void setContent(Object, String)66
Sets the content of this attachment part to that of the given Object and sets the value
of the Content-Type header to the given type.
public void setContentId(String)66
Sets the MIME header “Content-Id” with the given value.
62
Member Summary
public void setContentLocation(String)67
Sets the MIME header “Content-Location” with the given value.
public void setContentType(String)67
Sets the MIME header “Content-Type” with the given value.
public abstract void setDataHandler(DataHandler)67
Sets the given DataHandler object as the data handler for this Attachment-
Part object.
public abstract void setMimeHeader(String, String)67
Changes the first header entry that matches the given name to the given value, adding
a new header if no existing header matches.

wait
Constructors
AttachmentPart()
public AttachmentPart()
Methods
addMimeHeader(String, String)
public abstract void addMimeHeader(java.lang.String name, java.lang.String value)

Adds a MIME header with the specified name and value to this AttachmentPart object.
Note that RFC822 headers can contain only US-ASCII characters.
Parameters:
name - a String giving the name of the header to be added
value - a String giving the value of the header to be added
Throws:
IllegalArgumentException - if there was a problem with the specified mime header name or
value
63
clearContent()
public abstract void clearContent()

Clears out the content of this AttachmentPart object. The MIME header portion is left untouched.
getAllMimeHeaders()
public abstract java.util.Iterator getAllMimeHeaders()

Retrieves all the headers for this AttachmentPart object as an iterator over the MimeHeader objects.
Returns: an Iterator object with all of the Mime headers for this AttachmentPart object
getContent()
public abstract java.lang.Object getContent()

throws SOAPException
Gets the content of this AttachmentPart object as a Java object. The type of the returned Java object
depends on (1) the DataContentHandler object that is used to interpret the bytes and (2) the Con-
tent-Type given in the header. A JAXM-compliant provider must, as a minimum, return
java.lang.String corresponding to any content stream with a Content-Type value of text/
plain and a javax.xml.transform.StreamSource corresponding to a content stream with a
Content-Type value of text/xml. For those content types that an installed DataHandler object
does not understand, the DataHandler object is required to return a java.io.InputStream object
with the raw bytes.
Returns: a Java object with the content of this AttachmentPart object
Throws:
SOAPException99 - if there is no content set into this AttachmentPart object or if there was a
data transformation error
getContentId()
public java.lang.String getContentId()

Gets the value of the MIME header whose name is “Content-Id”.
Returns: a String giving the value of the “Content-Id” header or null if there is none
See Also: setContentId(String)66
getContentLocation()
public java.lang.String getContentLocation()

Gets the value of the MIME header “Content-Location”.
Returns: a String giving the value of the “Content-Location” header or null if there is none
64
getContentType()
public java.lang.String getContentType()

Gets the value of the MIME header “Content-Type”.
Returns: a String giving the value of the “Content-Type” header or null if there is none
getDataHandler()
public abstract javax.activation.DataHandler getDataHandler()

Gets the DataHandler object for this AttachmentPart object.
Returns: the DataHandler object associated with this AttachmentPart object
Throws:
a - SOAPException if there is no data in this AttachmentPart object
SOAPException99
getMatchingMimeHeaders(String[])
public abstract java.util.Iterator getMatchingMimeHeaders(java.lang.String[] names)

Retrieves all MimeHeader objects that match a name in the given array.
Parameters:
names - a String array with the name(s) of the MIME headers to be returned
Returns: all of the MIME headers that match one of the names in the given array as an Iterator object
getMimeHeader(String)
public abstract java.lang.String[] getMimeHeader(java.lang.String name)

Gets all the values of the header identified by the given String.
Parameters:
name - the name of the header; example: “Content-Type”
Returns: a String array giving the value for the specified header
See Also: setMimeHeader(String, String)67
getNonMatchingMimeHeaders(String[])
public abstract java.util.Iterator getNonMatchingMimeHeaders(java.lang.String[] names)

Retrieves all MimeHeader objects whose name does not match a name in the given array.
Parameters:
names - a String array with the name(s) of the MIME headers not to be returned
Returns: all of the MIME headers in this AttachmentPart object except those that match one of the
names in the given array. The nonmatching MIME headers are returned as an Iterator object.
65
getSize()
public abstract int getSize()

Returns the number of bytes in this AttachmentPart object.
Returns: the size of this AttachmentPart object in bytes or -1 if the size cannot be determined
removeAllMimeHeaders()
public abstract void removeAllMimeHeaders()

Removes all the MIME header entries.
removeMimeHeader(String)
public abstract void removeMimeHeader(java.lang.String header)

Removes all MIME headers that match the given name.
Parameters:
header - the string name of the MIME header/s to be removed
setContent(Object, String)
public abstract void setContent(java.lang.Object object, java.lang.String contentType)

Sets the content of this attachment part to that of the given Object and sets the value of the Content-
Type header to the given type. The type of the Object should correspond to the value given for the Con-
tent-Type. This depends on the particular set of DataContentHandler objects in use.
Parameters:
object - the Java object that makes up the content for this attachment part
contentType - the MIME string that specifies the type of the content
Throws:
IllegalArgumentException - if the contentType does not match the type of the content object,
or if there was no DataContentHandler object for this content object
See Also: getContent()64
setContentId(String)
public void setContentId(java.lang.String contentId)

Sets the MIME header “Content-Id” with the given value.
Parameters:
contentId - a String giving the value of the “Content-Id” header
Throws:
IllegalArgumentException - if there was a problem with the specified contentId value
See Also: getContentId()64
66
setContentLocation(String)
public void setContentLocation(java.lang.String contentLocation)

Sets the MIME header “Content-Location” with the given value.
Parameters:
contentLocation - a String giving the value of the “Content-Location” header
Throws:
IllegalArgumentException - if there was a problem with the specified content location
setContentType(String)
public void setContentType(java.lang.String contentType)

Sets the MIME header “Content-Type” with the given value.
Parameters:
contentType - a String giving the value of the “Content-Type” header
Throws:
IllegalArgumentException - if there was a problem with the specified content type
setDataHandler(DataHandler)
public abstract void setDataHandler(javax.activation.DataHandler dataHandler)

Sets the given DataHandler object as the data handler for this AttachmentPart object. Typically, on
an incoming message, the data handler is automatically set. When a message is being created and populated
with content, the setDataHandler method can be used to get data from various data sources into the
message.
Parameters:
the - DataHandler object to be set
Throws:
IllegalArgumentException - if there was a problem with the specified DataHandler object
setMimeHeader(String, String)
public abstract void setMimeHeader(java.lang.String name, java.lang.String value)

Changes the first header entry that matches the given name to the given value, adding a new header if no
existing header matches. This method also removes all matching headers but the first.
Note that RFC822 headers can only contain US-ASCII characters.
Parameters:
name - a String giving the name of the header for which to search
value - a String giving the value to be set for the header whose name matches the given name
Throws:
value
67
javax.xml.soap
Detail
Declaration
public interface Detail
Description
A container for DetailEntry objects. DetailEntry objects give detailed error information that is applica-
tion-specific and related to the Body element.
A Detail object is part of a SOAPFault object. It can be retrieved using the method SOAPFault.get-
Detail.
Member Summary
Methods
public DetailEntry addDetailEntry(DetailEntry)68
Adds the given DetailEntry object to this Detail object.
public Iterator getDetailEntries()68
Gets a list of the detail entries in this Detail object.
Methods
addDetailEntry(DetailEntry)
public DetailEntry69 addDetailEntry(DetailEntry69 entry)

Adds the given DetailEntry object to this Detail object.
Parameters:
entry - a DetailEntry object with detailed application-specific error information relating to the
Body element
getDetailEntries()
public java.util.Iterator getDetailEntries()

Gets a list of the detail entries in this Detail object.
Returns: an Iterator object over the DetailEntry objects in this Detail object
68
javax.xml.soap
DetailEntry
Declaration
public interface DetailEntry extends SOAPElement90
All Superinterfaces: Node81, SOAPElement90
Description
The content for a Detail object, giving details for a SOAPFault object. A DetailEntry object, which
carries information about errors related to the Body element, is application-specific.

Methods inherited from interface Node81
detachNode()81, getParentElement()82, getValue()82, recycleNode()82, setParentEle-
ment(SOAPElement)82
Methods inherited from interface SOAPElement90

addAttribute(Name, String)91, addChildElement(String, String, String)92, addChildEle-
ment(String, String, String)92, addChildElement(String, String, String)92,
addChildElement(String, String, String)92, addNamespaceDeclaration(String, String)93,
addTextNode(String)93, getAllAttributes()93, getAttributeValue(Name)93, getChildEle-
ments(Name)94, getChildElements(Name)94, getElementName()94, getEncodingStyle()94,
getNamespacePrefixes()94, getNamespaceURI(String)94, removeAttribute(Name)95, remove-
NamespaceDeclaration(String)95, setEncodingStyle(String)95
69
javax.xml.soap
MessageFactory
Declaration
public abstract class MessageFactory

java.lang.Object
|
+--javax.xml.soap.MessageFactory
Description
A factory for creating SOAPMessage objects.
A JAXM client performs the following steps to create a message.
• Creates a MessageFactory object from a ProviderConnection object (con in the following line
of code).
MessageFactory mf = con.createMessageFactory();
• Calls the method createMessage on the MessageFactory object.

SOAPMessage m = mf.createMessage();
It is also possible to create a MessageFactory object using the method newInstance, as shown in the fol-
lowing line of code.
MessageFactory mf = MessageFactory.newInstance();
This method is useful for clients that do not have a messaging provider and thus will not have a Provider-
Connection object from which to create a MessageFactory object.
Member Summary
Constructors
public MessageFactory()71
Methods
public abstract SOAP- createMessage()71
Message Creates a new SOAPMessage object with all the “standard” message header infor-
mation.
public abstract SOAP- createMessage(MimeHeaders, InputStream)71
Message Internalizes the contents of the given InputStream object into a new SOAPMes-
sage object and returns the SOAPMessage object.
public static Message- newInstance()72
Factory Creates a new MessageFactory object that is an instance of the default implemen-
tation.
70

wait
Constructors
MessageFactory()
public MessageFactory()
Methods
createMessage()
public abstract SOAPMessage110 createMessage()

Creates a new SOAPMessage object with all the “standard” message header information. Profile-specific
message factories can chose to pre-populate the SOAPMessage with profile-specific headers. This SOAP-
Message object can be sent “as is” when a message containing only a SOAP part is sufficient. Otherwise,
the SOAPMessage object needs to create one or more AttachmentPart objects and add them to itself
to form the payload of the message.
Returns: a new SOAPMessage object with standard header information
Throws:
SOAPException99 - if a JAXM error occurs
createMessage(MimeHeaders, InputStream)
public abstract SOAPMessage110 createMessage(MimeHeaders75 headers,

java.io.InputStream in)
throws IOException, SOAPException
Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns
the SOAPMessage object.
Parameters:
in - the InputStream object that contains the data for a message
headers - the transport-specific headers passed to the message in a transport-independent fashion for
creation of the message
Returns: a new SOAPMessage object containing the data from the given InputStream object
71
Throws:
IOException - if there is a problem in reading data from the input stream
SOAPException99 - if the message is invalid
newInstance()
public static MessageFactory70 newInstance()

Creates a new MessageFactory object that is an instance of the default implementation.
Throws:
SOAPException99
72
javax.xml.soap
MimeHeader
Declaration
public class MimeHeader

java.lang.Object
|
+--javax.xml.soap.MimeHeader
Description
An object that stores a MIME header name and its value. One or more MimeHeader objects may be contained
in a MimeHeaders object.
See Also: MimeHeaders75
Member Summary
Constructors
public MimeHeader(String, String)74
Constructs a MimeHeader object initialized with the given name and value.
Methods
public String getName()74
Returns the name of this MimeHeader object.
public String getValue()74
Returns the value of this MimeHeader object.

wait
73
Constructors
MimeHeader(String, String)
public MimeHeader(java.lang.String name, java.lang.String value)

Constructs a MimeHeader object initialized with the given name and value.
Parameters:
name - a String giving the name of the header
value - a String giving the value of the header
Methods
getName()
public java.lang.String getName()

Returns the name of this MimeHeader object.
Returns: the name of the header as a String
getValue()
public java.lang.String getValue()

Returns the value of this MimeHeader object.
Returns: the value of the header as a String
74
javax.xml.soap
MimeHeaders
Declaration
public class MimeHeaders

java.lang.Object
|
+--javax.xml.soap.MimeHeaders
Description
A container for MimeHeader objects, which represent the MIME headers present in a MIME part of a mes-
sage.
This class is used primarily when an application wants to retrieve specific attachments based on certain MIME
headers and values (see SOAPMessage.getAttachments). This class will most likely be used by imple-
mentations of AttachmentPart and other MIME dependent parts of the JAXM API.
Member Summary
Constructors
public MimeHeaders()76
Constructs a default MimeHeaders object initialized with an empty Vector
object.
Methods
public void addHeader(String, String)76
Adds a MimeHeader object with the specified name and value to this Mime-
Headers object’s list of headers.
public Iterator getAllHeaders()76
Returns all the headers in this MimeHeaders object.
public String[] getHeader(String)76
Returns all of the values for the specified header as an array of String objects.
public Iterator getMatchingHeaders(String[])77
Returns all the MimeHeader objects whose name matches a name in the given array
of names.
public Iterator getNonMatchingHeaders(String[])77
Returns all of the MimeHeader objects whose name does not match a name in the
given array of names.
public void removeAllHeaders()77
Removes all the header entries from this MimeHeaders object.
public void removeHeader(String)77
Remove all MimeHeader objects whose name matches the the given name.
public void setHeader(String, String)77
Replaces the current value of the first header entry whose name matches the given
name with the given value, adding a new header if no existing header name matches.
75

wait
Constructors
MimeHeaders()
public MimeHeaders()
Constructs a default MimeHeaders object initialized with an empty Vector object.
Methods
addHeader(String, String)
public void addHeader(java.lang.String name, java.lang.String value)

Adds a MimeHeader object with the specified name and value to this MimeHeaders object’s list of
headers.
Parameters:
name - a String with the name of the header to be added
value - a String with the value of the header to be added
Throws:
IllegalArgumentException - if there was a problem in the mime header name or value being
added
getAllHeaders()
public java.util.Iterator getAllHeaders()

Returns all the headers in this MimeHeaders object.
Returns: an Iterator object over this MimeHeaders object’s list of MimeHeader objects
getHeader(String)
public java.lang.String[] getHeader(java.lang.String name)

Returns all of the values for the specified header as an array of String objects.
76
Parameters:
name - the name of the header for which values will be returned
Returns: a String array with all of the values for the specified header
getMatchingHeaders(String[])
public java.util.Iterator getMatchingHeaders(java.lang.String[] names)

Returns all the MimeHeader objects whose name matches a name in the given array of names.
Parameters:
names - an array of String objects with the names for which to search
Returns: an Iterator object over the MimeHeader objects whose name matches one of the names in
the given list
getNonMatchingHeaders(String[])
public java.util.Iterator getNonMatchingHeaders(java.lang.String[] names)

Returns all of the MimeHeader objects whose name does not match a name in the given array of names.
Parameters:
names - an array of String objects with the names for which to search
Returns: an Iterator object over the MimeHeader objects whose name does not match one of the
names in the given list
removeAllHeaders()
public void removeAllHeaders()

Removes all the header entries from this MimeHeaders object.
removeHeader(String)
public void removeHeader(java.lang.String name)

Remove all MimeHeader objects whose name matches the the given name.
Parameters:
name - a String with the name of the header for which to search
setHeader(String, String)
public void setHeader(java.lang.String name, java.lang.String value)

Replaces the current value of the first header entry whose name matches the given name with the given
value, adding a new header if no existing header name matches. This method also removes all matching
headers after the first one.
77
Parameters:
name - a String with the name of the header for which to search
value - a String with the value that will replace the current value of the specified header
Throws:
IllegalArgumentException - if there was a problem in the mime header name or the value
being set
78
javax.xml.soap
Name
Declaration
public interface Name
Description
A representation of an XML name. This interface provides methods for getting the local and namespace-quali-
fied names and also for getting the prefix associated with the namespace for the name. It is also possible to get
the URI of the namespace.
The following is an example of a namespace declaration in an element.
WOMBAT:GetLastTradePrice xmlns:jaxm=“http://www.wombat.org/trader”
(“xmlns” stands for XML “namespace”.) The following shows what the methods in the Name interface will
return.
• getQualifiedName will return “prefix:LocalName” = “WOMBAT:GetLastTradePrice”
• getURI will return “http://www.wombat.org/trader”
• getLocalName will return “GetLastTracePrice”
• getPrefix will return “WOMBAT”
XML namespaces are used to disambiguate SOAP identifiers from application-specific identifiers.
Name objects are created using SOAPEnvelope.createName.
Member Summary
Methods
public String getLocalName()80
Gets the local name part of the XML name that this Name object represents.
public String getPrefix()80
Returns the prefix associated with the namespace for the XML name that this Name
object represents.
public String getQualifiedName()80
Gets the namespace-qualified name of the XML name that this Name object repre-
sents.
public String getURI()80
Returns the URI of the namespace for the XML name that this Name object repre-
sents.
79
Methods
getLocalName()
public java.lang.String getLocalName()

Gets the local name part of the XML name that this Name object represents.
Returns: a string giving the local name
getPrefix()
public java.lang.String getPrefix()

Returns the prefix associated with the namespace for the XML name that this Name object represents.
Returns: the prefix as a string
getQualifiedName()
public java.lang.String getQualifiedName()

Gets the namespace-qualified name of the XML name that this Name object represents.
Returns: the namespace-qualified name as a string
getURI()
public java.lang.String getURI()

Returns the URI of the namespace for the XML name that this Name object represents.
Returns: the URI as a string
80
javax.xml.soap
Node
Declaration
public interface Node
All Known Subinterfaces: DetailEntry69, SOAPBody83, SOAPBodyElement86,

SOAPElement90, SOAPEnvelope96, SOAPFault103, SOAPHeader105,
SOAPHeaderElement108, Text122
Description
A representation of a node (element) in a DOM representation of an XML document that provides some tree
manipulation methods. This interface provides methods for getting the value of a node, for getting and setting
the parent of a node, and for removing a node.
Member Summary
Methods
public void detachNode()81
Removes this Node object from the tree.
public SOAPElement getParentElement()82
Returns the parent element of this Node object.
public String getValue()82
Returns the the value of the immediate child of this Node object if a child exists and
its value is text.
public void recycleNode()82
Notifies the implementation that this Node object is no longer being used by the
application and that the implementation is free to reuse this object for nodes that may
be created later.
public void setParentElement(SOAPElement)82
Sets the parent of this Node object to the given SOAPElement object.
Methods
detachNode()
public void detachNode()

Removes this Node object from the tree. Once removed, this node can be garbage collected if there are no
application references to it.
81
getParentElement()
public SOAPElement90 getParentElement()

Returns the parent element of this Node object. This method can throw an UnsupportedOperation-
Exception if the tree is not kept in memory.
Returns: the SOAPElement object that is the parent of this Node object or null if this Node object is
root
Throws:
UnsupportedOperationException - if the whole tree is not kept in memory
See Also: setParentElement(SOAPElement)82
getValue()
public java.lang.String getValue()

Returns the the value of the immediate child of this Node object if a child exists and its value is text.
Returns: a String with the text of the immediate child of this Node object if (1) there is a child and (2)
the child is a Text object; null otherwise
recycleNode()
public void recycleNode()

Notifies the implementation that this Node object is no longer being used by the application and that the
implementation is free to reuse this object for nodes that may be created later.
Calling the method recycleNode implies that the method detachNode has been called previously.
setParentElement(SOAPElement)
public void setParentElement(SOAPElement90 parent)

Sets the parent of this Node object to the given SOAPElement object.
Parameters:
parent - the SOAPElement object to be set as the parent of this Node object
Throws:
SOAPException99 - if there is a problem in setting the parent to the given element
See Also: getParentElement()82
82
javax.xml.soap
SOAPBody
Declaration
public interface SOAPBody extends SOAPElement90
Description
An object that represents the contents of the SOAP body element in a SOAP message. A SOAP body element
consists of XML data that affects the way the application-specific content is processed.
A SOAPBody object contains SOAPBodyElement objects, which have the content for the SOAP body. A
SOAPFault object, which carries status and/or error information, is an example of a SOAPBodyElement
object.
See Also: SOAPFault103
Member Summary
Methods
public SOAPBodyEle- addBodyElement(Name)84
ment Creates a new SOAPBodyElement object with the specified name and adds it to this
SOAPBody object.
public SOAPFault addFault()84
Creates a new SOAPFault object and adds it to this SOAPBody object.
public SOAPFault getFault()84
Returns the SOAPFault object in this SOAPBody object.
public boolean hasFault()84
Indicates whether a SOAPFault object exists in this SOAPFault object.

ment(SOAPElement)82
83

Methods
addBodyElement(Name)
public SOAPBodyElement86 addBodyElement(Name79 name)

Creates a new SOAPBodyElement object with the specified name and adds it to this SOAPBody object.
Parameters:
name - a Name object with the name for the new SOAPBodyElement object
Returns: the new SOAPBodyElement object
Throws:
SOAPException99 - if a SOAP error occurs
addFault()
public SOAPFault103 addFault()

Creates a new SOAPFault object and adds it to this SOAPBody object.
Returns: the new SOAPFault object
Throws:
SOAPException99 - if there is a SOAP error
getFault()
public SOAPFault103 getFault()

Returns the SOAPFault object in this SOAPBody object.
Returns: the SOAPFault object in this SOAPBody object
hasFault()
public boolean hasFault()

Indicates whether a SOAPFault object exists in this SOAPFault object.
84
Returns: true if a SOAPFault object exists in this SOAPBody object; false otherwise
85
javax.xml.soap
SOAPBodyElement
Declaration
public interface SOAPBodyElement extends SOAPElement90
All Known Subinterfaces: SOAPFault103
Description
A SOAPBodyElement object represents the contents in a SOAPBody object. The SOAPFault interface is a
SOAPBodyElement object that has been defined.
A new SOAPBodyElement object can be created and added to a SOAPBody object with the SOAPBody
method addBodyElement. In the following line of code, sb is a SOAPBody object, and myName is a Name
object.
SOAPBodyElement sbe = sb.addBodyElement(myName);

ment(SOAPElement)82

86
javax.xml.soap
SOAPConnection
Declaration
public abstract class SOAPConnection

java.lang.Object
|
+--javax.xml.soap.SOAPConnection
Description
A connection that a client can use for sending messages directly to a remote party (represented by a URL, for
instance) without using a messaging provider. A standalone client uses a SOAPConnection object rather than
a ProviderConnection object.
A client can obtain a SOAPConnection object simply by calling the static method SOAPMessage.new-
Instance.
A SOAPConnection object can be used to send messages directly to a URL following the request/response
paradigm. That is, messages are sent using the method call, which sends the message and then waits until it
gets a reply.
Member Summary
Constructors
public SOAPConnection()88
Methods
public abstract SOAP- call(SOAPMessage, Endpoint)88
Message Sends the given message to the specified endpoint and blocks until it has returned the
response.
public abstract void close()88
Closes this SOAPConntection object.
public static SOAPCon- newInstance()88
nection Creates a new SOAPConnection object.

wait
87
Constructors
SOAPConnection()
public SOAPConnection()
Methods
call(SOAPMessage, Endpoint)
public abstract SOAPMessage110 call(SOAPMessage110 request, Endpoint41 endpoint)

Sends the given message to the specified endpoint and blocks until it has returned the response.
Parameters:
request - the SOAPMessage object to be sent
endpoint - a URLEndpoint object giving the URL to which the message should be sent
Returns: the SOAPMessage object that is the response to the message that was sent
Throws:
SOAPException99 - is there is a SOAP error
close()
public abstract void close()

Closes this SOAPConntection object.
Throws:
SOAPException99
newInstance()
public static SOAPConnection87 newInstance()

Creates a new SOAPConnection object.
Returns: a new instance of a SOAPConnection object
Throws:
SOAPException99
88
javax.xml.soap
SOAPConstants
Declaration
public interface SOAPConstants
Description
This interface defines a number of constants pertaining to the SOAP 1.1 protocol.
Member Summary
Fields
public static final URI_NS_SOAP_ENCODING89
The namespace identifier for the SOAP encoding (see section 5 of the SOAP 1.1 spec-
ification).
public static final URI_NS_SOAP_ENVELOPE89
The namespace identifier for the SOAP envelope.
public static final URI_SOAP_ACTOR_NEXT89
The URI identifying the first application processing a SOAP request as the intended
actor for a SOAP header entry (see section 4.2.2 of the SOAP 1.1 specification).
Fields
URI_NS_SOAP_ENCODING
public static final java.lang.String URI_NS_SOAP_ENCODING

The namespace identifier for the SOAP encoding (see section 5 of the SOAP 1.1 specification).
URI_NS_SOAP_ENVELOPE
public static final java.lang.String URI_NS_SOAP_ENVELOPE

The namespace identifier for the SOAP envelope.
URI_SOAP_ACTOR_NEXT
public static final java.lang.String URI_SOAP_ACTOR_NEXT

The URI identifying the first application processing a SOAP request as the intended actor for a SOAP
header entry (see section 4.2.2 of the SOAP 1.1 specification).
89
javax.xml.soap
SOAPElement
Declaration
public interface SOAPElement extends Node81
All Superinterfaces: Node81
All Known Subinterfaces: DetailEntry69, SOAPBody83, SOAPBodyElement86,

SOAPEnvelope96, SOAPFault103, SOAPHeader105, SOAPHeaderElement108
Description
An object representing the contents in a SOAPBody object, the contents in a SOAPHeader object, the content
that can follow the SOAPBody object in a SOAPEnvelope object, or what can follow the detail element in a
SOAPFault object. It is the base class for all of the classes that represent the SOAP objects as defined in the
SOAP specification.
Member Summary
Methods
public SOAPElement addAttribute(Name, String)91
Adds an attribute with the specified name and value to this SOAPElement object.
public SOAPElement addChildElement(Name)91
Creates a new SOAPElement object initialized with the given Name object and adds
the new element to this SOAPElement object.
public SOAPElement addChildElement(String)92
Creates a new SOAPElement object initialized with the given String object and
adds the new element to this SOAPElement object.
public SOAPElement addChildElement(String, String)92
Creates a new SOAPElement object initialized with the specified local name and
prefix and adds the new element to this SOAPElement object.
public SOAPElement addChildElement(String, String, String)92
Creates a new SOAPElement object initialized with the specified local name, prefix,
and URI and adds the new element to this SOAPElement object.
public SOAPElement addNamespaceDeclaration(String, String)93
Adds a namespace declaration with the specified prefix and URI to this SOAPEle-
ment object.
public SOAPElement addTextNode(String)93
Creates a new Text object initialized with the text and adds it to this SOAPElement
object.
public Iterator getAllAttributes()93
Returns an iterator over all of the attribute names in this SOAPElement object.
public String getAttributeValue(Name)93
Returns the value of the attribute with the specified name.
public Iterator getChildElements()94
Returns an iterator over all the immediate content of this element.
public Iterator getChildElements(Name)94
Returns an iterator over all the child elements with the specified name.
90
Member Summary
public Name getElementName()94
Returns the name of this SOAPElement object.
public String getEncodingStyle()94
Returns the encoding style for this SOAPElement object.
public Iterator getNamespacePrefixes()94
Returns an iterator of namespace prefixes.
public String getNamespaceURI(String)94
Returns the URI of the namespace that has the given prefix.
public boolean removeAttribute(Name)95
Removes the attribute with the specified name.
public boolean removeNamespaceDeclaration(String)95
Removes the namespace declaration corresponding to the given prefix.
public void setEncodingStyle(String)95
Sets the encoding style for this SOAPElement object to one specified.

ment(SOAPElement)82
Methods
addAttribute(Name, String)
public SOAPElement90 addAttribute(Name79 name, java.lang.String value)

Adds an attribute with the specified name and value to this SOAPElement object.
Parameters:
name - a Name object with the name of the attribute
value - a String giving the value of the attribute
Returns: the SOAPElement object into which the attribute was inserted
Throws:
SOAPException99 - if there is an error in creating the Attribute
addChildElement(Name)
public SOAPElement90 addChildElement(Name79 name)

Creates a new SOAPElement object initialized with the given Name object and adds the new element to
this SOAPElement object.
91
Parameters:
name - a Name object with the XML name for the new element
Returns: the new SOAPElement object that was created
Throws:
SOAPException99 - if there is an error in creating the SOAPElement object
addChildElement(String)
public SOAPElement90 addChildElement(java.lang.String localName)

Creates a new SOAPElement object initialized with the given String object and adds the new element
to this SOAPElement object.
Parameters:
localName - a String giving the local name for the element
Throws:
addChildElement(String, String)
public SOAPElement90 addChildElement(java.lang.String localName, java.lang.String prefix)

Creates a new SOAPElement object initialized with the specified local name and prefix and adds the new
element to this SOAPElement object.
Parameters:
localName - a String giving the local name for the new element
prefix - a String giving the namespace prefix for the new element
Throws:
addChildElement(String, String, String)
public SOAPElement90 addChildElement(java.lang.String localName, java.lang.String prefix,

java.lang.String uri)
Creates a new SOAPElement object initialized with the specified local name, prefix, and URI and adds
the new element to this SOAPElement object.
Parameters:
localName - a String giving the local name for the new element
prefix - a String giving the namespace prefix for the new element
uri - a String giving the URI of the namespace to which the new element belongs
92

Throws:
addNamespaceDeclaration(String, String)
public SOAPElement90 addNamespaceDeclaration(java.lang.String prefix, java.lang.String uri)

Adds a namespace declaration with the specified prefix and URI to this SOAPElement object.
Parameters:
prefix - a String giving the prefix of the namespace
uri - a String giving the uri of the namespace
Returns: the SOAPElement object into which this namespace declaration was inserted.
Throws:
SOAPException99 - if there is an error in creating the namespace
addTextNode(String)
public SOAPElement90 addTextNode(java.lang.String text)

Creates a new Text object initialized with the text and adds it to this SOAPElement object.
Parameters:
text - a String with the textual content to be added
Returns: the SOAPElement object into which the new Text object was inserted
Throws:
SOAPException99 - if there is an error in creating the new Text object
getAllAttributes()
public java.util.Iterator getAllAttributes()

Returns an iterator over all of the attribute names in this SOAPElement object. The iterator can be used to
get the attribute names, which can then be passed to the method getAttributeValue to retrieve the
value of each attribute.
Returns: an iterator over the names of the attributes
getAttributeValue(Name)
public java.lang.String getAttributeValue(Name79 name)

Returns the value of the attribute with the specified name.
Parameters:
name - a Name object with the name of the attribute
Returns: a String giving the value of the specified attribute
93
getChildElements()
public java.util.Iterator getChildElements()

Returns an iterator over all the immediate content of this element. This includes Text objects as well as
SOAPElement objects.
Returns: an iterator with the content of this SOAPElement object
getChildElements(Name)
public java.util.Iterator getChildElements(Name79 name)

Returns an iterator over all the child elements with the specified name.
Parameters:
name - a Name object with the name of the child elements to be returned
Returns: an Iterator object over all the elements in this SOAPElement object with the specified
name
getElementName()
public Name79 getElementName()

Returns the name of this SOAPElement object.
Returns: a Name object with the name of this SOAPElement object
getEncodingStyle()
public java.lang.String getEncodingStyle()

Returns the encoding style for this SOAPElement object.
Returns: a String giving the encoding style
See Also: setEncodingStyle(String)95
getNamespacePrefixes()
public java.util.Iterator getNamespacePrefixes()

Returns an iterator of namespace prefixes. The iterator can be used to get the namespace prefixes, which
can then be passed to the method getNamespaceURI to retrieve the URI of each namespace.
Returns: an iterator over the namespace prefixes in this SOAPElement object
getNamespaceURI(String)
public java.lang.String getNamespaceURI(java.lang.String prefix)

Returns the URI of the namespace that has the given prefix.
94
Parameters:
prefix - a String giving the prefix of the namespace for which to search
Returns: a String with the uri of the namespace that has the given prefix
removeAttribute(Name)
public boolean removeAttribute(Name79 name)

Removes the attribute with the specified name.
Parameters:
name - the Name object with the name of the attribute to be removed
Returns: true if the attribute was removed successfully; false if it was not
removeNamespaceDeclaration(String)
public boolean removeNamespaceDeclaration(java.lang.String prefix)

Removes the namespace declaration corresponding to the given prefix.
Parameters:
prefix - a String giving the prefix for which to search
Returns: true if the namespace declaration was removed successfully; false if it was not
setEncodingStyle(String)
public void setEncodingStyle(java.lang.String encodingStyle)

Sets the encoding style for this SOAPElement object to one specified.
Parameters:
encodingStyle - a String giving the encoding style
Throws:
IllegalArgumenException - if there was a problem in the encoding style being set.
SOAPException99
See Also: getEncodingStyle()94
95
javax.xml.soap
SOAPEnvelope
Declaration
public interface SOAPEnvelope extends SOAPElement90
Description
The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
A client can access the SOAP Header and SOAP Body of a SOAPEnvelope object by calling the methods
SOAPEnvelope.getHeader and SOAPEnvelope.getBody. The following lines of code, in which se
is a SOAPEnvelope object, retrieve the SOAP header and SOAP body.
SOAPHeader sh = se.getHeader();
SOAPBody sb = se.getBody();
To create a SOAPHeader object, a client can use the method SOAPPart.getEnvelope(true). The fol-
lowing code fragment, in which m is a SOAPMessage object, gets a SOAPPart object and uses it to create a
new SOAPHeader object. Note that the method getEnvelope returns a SOAPEnvelope object, but when
the method is passed the argument true, it also creates a SOAPHeader object and adds it to the SOAPEnve-
lope object.
SOAPPart sp = m.getSOAPPart();
SOAPEnvelope se = sp.getEnvelope(true);
Ihe SOAPBody object is a mandatory part of the SOAPEnvelope object and is created by the infrastructure.
Member Summary
Methods
public Name createName(String)97
Creates a new Name object initialized with the given local name.
public Name createName(String, String)97
Creates a new Name object initialized with the given local name and prefix.
public Name createName(String, String, String)98
Creates a new Name object initialized with the given local name, prefix, and URI.
public SOAPBody getBody()98
Returns the SOAPBody object associated with this SOAPEnvelope object.
public SOAPHeader getHeader()98
Returns the SOAPHeaderobject, if one has been set, for this SOAPEnvelope
object.
96

ment(SOAPElement)82

Methods
createName(String)
public Name79 createName(java.lang.String localName)

Creates a new Name object initialized with the given local name.
This factory method creates names for use in the SOAP/XML document.
Parameters:
localName - a String giving the local name
Returns: a Name object initialized with the given local name
Throws:
createName(String, String)
public Name79 createName(java.lang.String localName, java.lang.String prefix)

Creates a new Name object initialized with the given local name and prefix.
Parameters:
Returns: a Name object initialized with the given local name and prefix
Throws:
97
createName(String, String, String)
public Name79 createName(java.lang.String localName, java.lang.String prefix, java.lang.String uri)

Creates a new Name object initialized with the given local name, prefix, and URI.
Parameters:
uri - a String giving the URI of the namespace
Returns: a Name object initialized with the given local name and prefix
Throws:
getBody()
public SOAPBody83 getBody()

Returns the SOAPBody object associated with this SOAPEnvelope object.
Returns: the SOABody object for this SOAPEnvelope object
Throws:
SOAPException99
getHeader()
public SOAPHeader105 getHeader()

Returns the SOAPHeaderobject, if one has been set, for this SOAPEnvelope object.
Returns: the SOAPHeader object or null if there is none
Throws:
SOAPException99
98
javax.xml.soap
SOAPException
Declaration
public class SOAPException extends java.lang.Exception

java.lang.Object
|
+--java.lang.Throwable
|
+--java.lang.Exception
|
+--javax.xml.soap.SOAPException
All Implemented Interfaces: java.io.Serializable
Direct Known Subclasses: JAXMException43
Description
An exception that signals that a SOAP exception has occurred. A SOAPException object may contain a
String that gives the reason for the exception, an embedded Throwable object, or both. This class provides
methods for retrieving reason messages and for retrieving the embedded Throwable object.
Typical reasons for throwing a SOAPException object are problems such as difficulty setting a header, not
being able to send a message, and not being able to get a connection with the provider. Reasons for embedding
a Throwable object include problems such as input/output errors or a parsing problem, such as an error in
parsing a header.
Member Summary
Constructors
public SOAPException()100
Constructs a SOAPException object with no reason or embedded Throwable
object.
public SOAPException(String)100
Constructs a SOAPException object with the given String as the reason for the
exception being thrown.
public SOAPException(String, Throwable)100
Constructs a SOAPException object with the given String as the reason for the
exception being thrown and the given Throwable object as an embedded exception.
public SOAPException(Throwable)101
Constructs a SOAPException object initialized with the given Throwable object.
Methods
public Throwable getCause()101
Returns the Throwable object embedded in this SOAPException if there is one.
public String getMessage()101
Returns the detail message for this SOAPException object.
99
Member Summary
public synchronized initCause(Throwable)101
Throwable Initializes the cause field of this SOAPException object with the given Throw-
able object.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, printStackTrace, printStackTrace, printStack-
Trace, toString
Constructors
SOAPException()
public SOAPException()
Constructs a SOAPException object with no reason or embedded Throwable object.
SOAPException(String)
public SOAPException(java.lang.String reason)

Constructs a SOAPException object with the given String as the reason for the exception being
thrown.
Parameters:
reason - a description of what caused the exception
SOAPException(String, Throwable)
public SOAPException(java.lang.String reason, java.lang.Throwable cause)

Constructs a SOAPException object with the given String as the reason for the exception being
thrown and the given Throwable object as an embedded exception.
Parameters:
reason - a description of what caused the exception
cause - a Throwable object that is to be embedded in this SOAPException object
100
SOAPException(Throwable)
public SOAPException(java.lang.Throwable cause)

Constructs a SOAPException object initialized with the given Throwable object.
Methods
getCause()
public java.lang.Throwable getCause()

Returns the Throwable object embedded in this SOAPException if there is one. Otherwise, this
method returns null.
Returns: the embedded Throwable object or null if there is none
getMessage()
public java.lang.String getMessage()

Returns the detail message for this SOAPException object.
If there is an embedded Throwable object, and if the SOAPException object has no detail message of
its own, this method will return the detail message from the embedded Throwable object.
Overrides: java.lang.Throwable.getMessage() in class java.lang.Throwable
Returns: the error or warning message for this SOAPException or, if it has none, the message of the
embedded Throwable object, if there is one
initCause(Throwable)
public synchronized java.lang.Throwable initCause(java.lang.Throwable cause)

Initializes the cause field of this SOAPException object with the given Throwable object.
This method can be called at most once. It is generally called from within the constructor or immediately
after the constructor has returned a new SOAPException object. If this SOAPException object was
created with the constructor SOAPException(Throwable)101 or SOAPException(String,
Throwable)100 , meaning that its cause field already has a value, this method cannot be called even
once.
Parameters:
cause - the Throwable object that caused this SOAPException object to be thrown. The value of
this parameter is saved for later retrieval by the getCause()101 method. A null value is permitted
and indicates that the cause is nonexistent or unknown.
Returns: a reference to this SOAPException instance
Throws:
IllegalArgumentException - if cause is this Throwable object. (A Throwable object
cannot be its own cause.)
101
IllegalStateException - if this SOAPException object was created with

SOAPException(Throwable)101 or SOAPException(String, Throwable)100 , or
this method has already been called on this SOAPException object
102
javax.xml.soap
SOAPFault
Declaration
public interface SOAPFault extends SOAPBodyElement86
All Superinterfaces: Node81, SOAPBodyElement86, SOAPElement90
Description
An object that contains error and/or status information within a SOAP message. A SOAPFault object is used
as the value for a field in the SOAPBody interface.
Member Summary
Methods
public Detail getDetail()104
Returns the detail element for this SOAPFault object.
public String getFaultCode()104
Gets the fault code for this SOAPFault object.
public String getFaultString()104
Gets the fault string for this SOAPFault object.
public void setFaultCode(String)104
Sets this SOAPFault object with the given fault code.
public void setFaultString(String)104
Sets the fault string for this SOAPFault object to the given string.

ment(SOAPElement)82

103
Methods
getDetail()
public Detail68 getDetail()

Returns the detail element for this SOAPFault object.
A Detail object carries application-specific error information related to the SOAPBodyElement
objects.
Returns: a Detail object with application-specific error information
getFaultCode()
public java.lang.String getFaultCode()

Gets the fault code for this SOAPFault object.
Returns: a String with the fault code
See Also: setFaultCode(String)104
getFaultString()
public java.lang.String getFaultString()

Gets the fault string for this SOAPFault object.
Returns: a String giving an explanation of the fault
setFaultCode(String)
public void setFaultCode(java.lang.String faultCode)

Sets this SOAPFault object with the given fault code.
Fault codes are defined in the SOAP 1.1 specification.
Parameters:
faultCode - a String giving the fault code to be set
See Also: getFaultCode()104
setFaultString(String)
public void setFaultString(java.lang.String faultString)

Sets the fault string for this SOAPFault object to the given string.
Parameters:
faultString - a String giving an explanation of the fault
See Also: getFaultString()104
104
javax.xml.soap
SOAPHeader
Declaration
public interface SOAPHeader extends SOAPElement90
Description
A SOAPHeader object represents the contents of the SOAP header element. A SOAP header element consists
of XML data that affects the way the application-specific content is processed by the message handler. For
example, transaction semantics, authentication information, and so on, can be specified as the content of a
SOAPHeader object.
To create a SOAPHeader object, a client can use the method SOAPPart.getEnvelope(true). The fol-
lowing code fragment, in which m is a SOAPMessage object, gets a SOAPPart object and uses it to create a
new SOAPHeader object. Note that the method getEnvelope returns a SOAPEnvelope object, but when
the method is passed the argument true, it also creates a SOAPHeader object and adds it to the SOAPEnve-
lope object.
SOAPEnvelope se = sp.getEnvelope(true);
A SOAPHeader object can have only SOAPHeaderElement objects as its immediate children. The method
addHeaderElement creates a new HeaderElement object and adds it to the SOAPHeader object.
See Also: SOAPHeaderElement108
Member Summary
Methods
public SOAPHeaderEle- addHeaderElement(Name)106
ment Creates a new SOAPHeaderElement object initialized with the specified name and
adds it to this SOAPHeader object.
public Iterator examineHeaderElements(String)106
Returns a list of all the SOAPHeaderElement objects in this SOAPHeader object
that have the the specified actor.
public Iterator extractHeaderElements(String)107
Returns a list of all the SOAPHeaderElement objects in this SOAPHeader object
that have the the specified actor and detaches them from this SOAPHeader object.
105

ment(SOAPElement)82

Methods
addHeaderElement(Name)
public SOAPHeaderElement108 addHeaderElement(Name79 name)

Creates a new SOAPHeaderElement object initialized with the specified name and adds it to this
SOAPHeader object.
Parameters:
name - a Name object with the name of the new SOAPHeaderElement object
Returns: the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException99 - if a SOAP error occurs
examineHeaderElements(String)
public java.util.Iterator examineHeaderElements(java.lang.String actor)

Returns a list of all the SOAPHeaderElement objects in this SOAPHeader object that have the the
specified actor. An actor is a global attribute that indicates the intermediate parties to whom the message
should be sent. An actor receives the message and then sends it to the next actor. The default actor is the
ultimate intended recipient for the message, so if no actor attribute is included in a SOAPHeader object,
the message is sent to its ultimate destination.
Parameters:
actor - a String giving the URI of the actor for which to search
Returns: an Iterator object over all the SOAPHeaderElement objects that contain the specified
actor
See Also: extractHeaderElements(String)107
106
extractHeaderElements(String)
public java.util.Iterator extractHeaderElements(java.lang.String actor)

Returns a list of all the SOAPHeaderElement objects in this SOAPHeader object that have the the
specified actor and detaches them from this SOAPHeader object.
This method allows an actor to process only the parts of the SOAPHeader object that apply to it and to
remove them before passing the message on to the next actor.
Parameters:
actor - a String giving the URI of the actor for which to search
Returns: an Iterator object over all the SOAPHeaderElement objects that contain the specified
actor
See Also: examineHeaderElements(String)106
107
javax.xml.soap
SOAPHeaderElement
Declaration
public interface SOAPHeaderElement extends SOAPElement90
Description
An object representing the contents in the SOAP header part of the SOAP envelope. The immediate children of
a SOAPHeader object can be represented only as SOAPHeaderElement objects.
A SOAPHeaderElement object can have other SOAPElement objects as its children.
Member Summary
Methods
public String getActor()109
Returns the uri of the actor associated with this SOAPHeaderElement object.
public boolean getMustUnderstand()109
Returns the mustUnderstand attribute associated with this SOAPHeaderElement
object.
public void setActor(String)109
Sets the actor associated with this SOAPHeaderElement object to the specified
actor.
public void setMustUnderstand(boolean)109
Sets the mustUnderstand attribute for this SOAPHeaderElement object to be on or
off.

ment(SOAPElement)82

108
Methods
getActor()
public java.lang.String getActor()

Returns the uri of the actor associated with this SOAPHeaderElement object.
Returns: a String giving the URI of the actor
See Also: setActor(String)109
getMustUnderstand()
public boolean getMustUnderstand()

Returns the mustUnderstand attribute associated with this SOAPHeaderElement object.
Returns: true if the mustUnderstand attribute of this SOAPHeaderElement is turned on; false
otherwise
setActor(String)
public void setActor(java.lang.String actorURI)

Sets the actor associated with this SOAPHeaderElement object to the specified actor. The default value
of an actor is: SOAPConstants.URI_SOAP_ACTOR_NEXT
Parameters:
actorURI - a String giving the URI of the actor to set
Throws:
IllegalArgumentException - if there is a problem in setting the actor.
See Also: getActor()109
setMustUnderstand(boolean)
public void setMustUnderstand(boolean mustUnderstand)

Sets the mustUnderstand attribute for this SOAPHeaderElement object to be on or off.
If the mustUnderstand attribute is on, the actor who receives the SOAPHeaderElement must process it
correctly. This ensures, for example, that if the SOAPHeaderElement object modifies the message, that
the message is being modified correctly.
Parameters:
mustUnderstand - true to set the mustUnderstand attribute on; false to turn if off
Throws:
IlleglalArgumentException - if there is a problem in setting the mustunderstand attribute
See Also: getMustUnderstand()109
109
javax.xml.soap
SOAPMessage
Declaration
public abstract class SOAPMessage

java.lang.Object
|
+--javax.xml.soap.SOAPMessage
Description
The root class for all SOAP messages. As transmitted on the “wire”, a SOAP message is an XML document or
a MIME message whose first body part is an XML/SOAP document.
A SOAPMessage object consists of a SOAP part and optionally one or more attachment parts. The SOAP part
for a SOAPMessage object is a SOAPPart object, which contains information used for message routing and
identification. The SOAP part can be retrieved by calling the method SOAPMessage.getSOAPPart().
In addition to the mandatory SOAPPart object, a SOAPMessage object may contain zero or more
AttachmentPart objects, each of which contains application-specific data. The SOAPMessage interface
provides methods for creating AttachmentPart objects and also for adding them to a SOAPMessage
object. A party that has received a SOAPMessage object can examine its contents by retrieving individual
attachment parts.
Unlike the rest of a SOAP message, an attachment is not required to be in XML format and can therefore be
anything from simple text to an image file. Consequently, any message content that is not in XML format must
be in an AttachmentPart object.
A MessageFactory object creates new SOAPMessage objects.
Member Summary
Constructors
public SOAPMessage()112
Methods
public abstract void addAttachmentPart(AttachmentPart)112
Adds the given AttachmentPart object to this SOAPMessage object.
public abstract int countAttachments()112
Gets a count of the number of attachments in this message.
public abstract createAttachmentPart()112
AttachmentPart Creates a new empty AttachmentPart object.
public AttachmentPart createAttachmentPart(DataHandler)112
Creates an AttachmentPart object and populates it using the given Data-
Handler object.
public AttachmentPart createAttachmentPart(Object, String)113
Creates an AttachmentPart object and populates it with the specified data of the
specified content type.
public abstract Itera- getAttachments()113
tor Retrieves all the AttachmentPart objects that are part of this SOAPMessage
object.
110
Member Summary
public abstract Itera- getAttachments(MimeHeaders)113
tor Retrieves all the AttachmentPart objects that have header entries that match the
specified headers.
public abstract String getContentDescription()113
Retrieves a description of this SOAPMessage object’s content.
public abstract Mime- getMimeHeaders()113
Headers Returns all the transport-specific MIME headers for this SOAPMessage object in a
transport-independent fashion.
public abstract SOAP- getSOAPPart()114
Part Gets the SOAP part of this SOAPMessage object.
public abstract void removeAllAttachments()114
Removes all AttachmentPart objects that have been added to this SOAPMes-
sage object.
public abstract void saveChanges()114
Updates this SOAPMessage object with all the changes that have been made to it.
public abstract bool- saveRequired()114
ean Indicates whether this SOAPMessage object has had the method saveChanges
called on it.
public abstract void setContentDescription(String)114
Sets the description of this SOAPMessage object’s content with the given descrip-
tion.
public abstract void writeTo(OutputStream)115
Writes this SOAPMessage object to the given output stream.

wait
111
Constructors
SOAPMessage()
public SOAPMessage()
Methods
addAttachmentPart(AttachmentPart)
public abstract void addAttachmentPart(AttachmentPart61 AttachmentPart)

Adds the given AttachmentPart object to this SOAPMessage object. An AttachmentPart object
must be created before it can be added to a message.
Parameters:
AttachmentPart - an AttachmentPart object that is to become part of this SOAPMessage
object
Throws:
IllegalArgumentException, IllegalStateException
countAttachments()
public abstract int countAttachments()

Gets a count of the number of attachments in this message. This count does not include the SOAP part.
Returns: the number of AttachmentPart objects that are part of this SOAPMessage object
createAttachmentPart()
public abstract AttachmentPart61 createAttachmentPart()

Creates a new empty AttachmentPart object. Note that the method addAttachmentPart must be
called with this new AttachmentPart object as the parameter in order for it to become an attachment to
this SOAPMessage object.
Returns: a new AttachmentPart object that can be populated and added to this SOAPMessage
object
createAttachmentPart(DataHandler)
public AttachmentPart61 createAttachmentPart(javax.activation.DataHandler dataHandler)

Creates an AttachmentPart object and populates it using the given DataHandler object.
Returns: a new AttachmentPart object that contains data generated by the given DataHandler
object
112
Throws:
IllegalArgumentException - if there was a problem with the specified dataHandler
createAttachmentPart(Object, String)
public AttachmentPart61 createAttachmentPart(java.lang.Object content,

java.lang.String contentType)
Creates an AttachmentPart object and populates it with the specified data of the specified content type.
Returns: a new AttachmentPart object that contains the given data
Throws:
IllegalArgumentException - if the contentType does not match the type of the content object,
or if there was no DataContentHandler for the given content object
getAttachments()
public abstract java.util.Iterator getAttachments()

Retrieves all the AttachmentPart objects that are part of this SOAPMessage object.
Returns: an iterator over all the attachments in this message
getAttachments(MimeHeaders)
public abstract java.util.Iterator getAttachments(MimeHeaders75 headers)

Retrieves all the AttachmentPart objects that have header entries that match the specified headers.
Note that a returned attachment could have headers in addition to those specified.
Parameters:
headers - a MimeHeaders object containing the MIME headers for which to search
Returns: an iterator over all attachments that have a header that matches one of the given headers
getContentDescription()
public abstract java.lang.String getContentDescription()

Retrieves a description of this SOAPMessage object’s content.
Returns: a String describing the content of this message or null if no description has been set
See Also: setContentDescription(String)114
getMimeHeaders()
public abstract MimeHeaders75 getMimeHeaders()

Returns all the transport-specific MIME headers for this SOAPMessage object in a transport-independent
fashion.
Returns: a MimeHeaders object containing the MimeHeader objects
113
getSOAPPart()
public abstract SOAPPart116 getSOAPPart()

Gets the SOAP part of this SOAPMessage object.
If a SOAPMessage object contains one or more attachments, the SOAP Part must be the first MIME body
part in the message.
Returns: the SOAPPart object for this SOAPMessage object
removeAllAttachments()
public abstract void removeAllAttachments()

Removes all AttachmentPart objects that have been added to this SOAPMessage object.
This method does not touch the SOAP part.
saveChanges()
public abstract void saveChanges()

Updates this SOAPMessage object with all the changes that have been made to it. This method is called
automatically when a message is sent or written to by the methods ProviderConnection.send,
SOAPConnection.call, or SOAPMessage.writeTo. However, if changes are made to a message
that was received or to one that has already been sent, the method saveChanges needs to be called
explicitly in order to save the changes. The method saveChanges also generates any changes that can be
read back (for example, a MessageId in profiles that support a message id). All MIME headers in a message
that is created for sending purposes are guaranteed to have valid values only after saveChanges has been
called.
In addition, this method marks the point at which the data from all constituent AttachmentPart objects
are pulled into the message.
Throws:
SOAPException99
saveRequired()
public abstract boolean saveRequired()

Indicates whether this SOAPMessage object has had the method saveChanges called on it.
Returns: true if saveChanges has been called on this message at least once; false otherwise.
setContentDescription(String)
public abstract void setContentDescription(java.lang.String description)

Sets the description of this SOAPMessage object’s content with the given description.
Parameters:
description - a String describing the content of this message
114
See Also: getContentDescription()113
writeTo(OutputStream)
public abstract void writeTo(java.io.OutputStream out)

throws SOAPException, IOException
Writes this SOAPMessage object to the given output stream. The externalization format is as defined by
the SOAP 1.1 with Attachments specification.
If there are no attachments, just an XML stream is written out. For those messages that have attachments,
writeTo writes a MIME-encoded byte stream.
Parameters:
out - the OutputStream object to which this SOAPMessage object will be written
Throws:
IOException - if an I/O error occurs
SOAPException99 - if there was a problem in externalizing this SOAP message
115
javax.xml.soap
SOAPPart
Declaration
public abstract class SOAPPart

java.lang.Object
|
+--javax.xml.soap.SOAPPart
Description
The container for the SOAP-specific portion of a SOAPMessage object. The SOAPPart object is a MIME
part containing the SOAPEnvelope object, which in turn contains the SOAPBody object and the SOAP-
Header object if there is one.
A client can access the SOAP Envelope of a SOAPMessage object by calling the method
SOAPMessage.getSOAPPart. The following line of code, in which m is a SOAPMessage object, retrieves
the SOAP part of a message.
sp.getEnvelope can then be used to retrieve the SOAP Envelope itself.
Member Summary
Constructors
public SOAPPart()117
Methods
public abstract void addMimeHeader(String, String)117
Creates a MIMEHeader object with the specified name and value and adds it to this
SOAPPart object.
public abstract Itera- getAllMimeHeaders()118
tor Retrieves all the headers for this SOAPPart object as an iterator over the Mime-
Header objects.
public abstract Source getContent()118
Returns the content of the SOAPEnvelope as a JAXP Source object.
public String getContentId()118
Retrieves the value of the MIME header whose name is Content-Id.
public String getContentLocation()118
Retrieves the value of the MIME header whose name is Content-Location.
public abstract SOAP- getEnvelope()118
Envelope Gets the SOAP envelope associated with this SOAPPart object.
public abstract SOAP- getEnvelope(boolean)119
Envelope Gets the SOAPEnvelope object associated with this SOAPPart object and creates
a new SOAPHeader object and sets it on this SOAPEnvelope object if the argu-
ment passed to this method is true.
public abstract Itera- getMatchingMimeHeaders(String[])119
tor Retrieves all MimeHeader objects that match a name in the given array.
public abstract getMimeHeader(String)119
String[] Gets all the values of the MimeHeader object in this SOAPPart object that is iden-
tified by the given String.
116
Member Summary
public abstract Itera- getNonMatchingMimeHeaders(String[])119
tor Retrieves all MimeHeader objects whose name does not match a name in the given
array.
public abstract void removeAllMimeHeaders()120
Removes all the MimeHeader objects for this SOAPEnvelope object.
public abstract void removeMimeHeader(String)120
Removex all MIME headers that match the given name.
public abstract void setContent(Source)120
Sets the content of the SOAPEnvelope object with the data from the given Source
object.
public void setContentId(String)120
Sets the value of the MIME header named Content-Id to the given String.
public void setContentLocation(String)120
Sets the value of the MIME header Content-Location to the given String.
public abstract void setMimeHeader(String, String)121
Changes the first header entry that matches the given header name so that its value is
the given value, adding a new header if no existing header is a match.

wait
Constructors
SOAPPart()
public SOAPPart()
Methods
addMimeHeader(String, String)
public abstract void addMimeHeader(java.lang.String name, java.lang.String value)

Creates a MIMEHeader object with the specified name and value and adds it to this SOAPPart object.
Parameters:
name - a String giving the header name
value - a String giving the value to be set
117
Throws:
value
getAllMimeHeaders()
public abstract java.util.Iterator getAllMimeHeaders()

Retrieves all the headers for this SOAPPart object as an iterator over the MimeHeader objects.
Returns: an Iterator object with all of the Mime headers for this SOAPPart object
getContent()
public abstract javax.xml.transform.Source getContent()

Returns the content of the SOAPEnvelope as a JAXP Source object.
Returns: the content as a javax.xml.transform.Source object
Throws:
SOAPException99 - if the implementation cannot convert to the specified Source
See Also: setContent(Source)120
getContentId()
public java.lang.String getContentId()

Retrieves the value of the MIME header whose name is Content-Id.
Returns: a String giving the value of the MIME header named Content-Id
See Also: setContentId(String)120
getContentLocation()
public java.lang.String getContentLocation()

Retrieves the value of the MIME header whose name is Content-Location.
Returns: a String giving the value of the MIME header whose name is Content-Location
See Also: setContentLocation(String)120
getEnvelope()
public abstract SOAPEnvelope96 getEnvelope()

Gets the SOAP envelope associated with this SOAPPart object. Once the SOAP envelope is obtained, the
contents of the envelope, that is, the SOAPHeader, SOAPFault or SOAPBody can be examined.
Returns: the SOAPEnvelope object for this SOAPPart object
118
getEnvelope(boolean)
public abstract SOAPEnvelope96 getEnvelope(boolean createHeader)

Gets the SOAPEnvelope object associated with this SOAPPart object and creates a new SOAPHeader
object and sets it on this SOAPEnvelope object if the argument passed to this method is true.
The second argument should be true only when a SOAPMessage object is being constructed. When a
client is receiving a message, it uses the getEnvelope method to retrieve the envelope. Once the SOAP-
Envelope object is obtained, the contents of the envelope, that is, the SOAPHeader, SOAPFault, or
SOAPBody, can be examined.
Parameters:
boolean - createHeader true to indicate that a new SOAPHeader object should be created and set
on this SOAPEnvelope object; false if no header should be created
Throws:
SOAPException99 - if a SOAPHeader object has already been created and set on this
SOAPEnvelope object
getMatchingMimeHeaders(String[])
public abstract java.util.Iterator getMatchingMimeHeaders(java.lang.String[] names)

Retrieves all MimeHeader objects that match a name in the given array.
Parameters:
names - a String array with the name(s) of the MIME headers to be returned
Returns: all of the MIME headers that match one of the names in the given array as an Iterator object
getMimeHeader(String)
public abstract java.lang.String[] getMimeHeader(java.lang.String name)

Gets all the values of the MimeHeader object in this SOAPPart object that is identified by the given
String.
Parameters:
name - the name of the header; example: “Content-Type”
Returns: a String giving the value for the specified header
See Also: setMimeHeader(String, String)121
getNonMatchingMimeHeaders(String[])
public abstract java.util.Iterator getNonMatchingMimeHeaders(java.lang.String[] names)

Retrieves all MimeHeader objects whose name does not match a name in the given array.
Parameters:
names - a String array with the name(s) of the MIME headers not to be returned
119
Returns: all of the MIME headers in this SOAPPart object except those that match one of the names in
the given array. The nonmatching MIME headers are returned as an Iterator object.
removeAllMimeHeaders()
public abstract void removeAllMimeHeaders()

Removes all the MimeHeader objects for this SOAPEnvelope object.
removeMimeHeader(String)
public abstract void removeMimeHeader(java.lang.String header)

Removex all MIME headers that match the given name.
Parameters:
header - a String giving the name of the MIME header(s) to be removed.
setContent(Source)
public abstract void setContent(javax.xml.transform.Source source)

Sets the content of the SOAPEnvelope object with the data from the given Source object.
Parameters:
the - javax.xml.transform.Source object with the data to be set
Throws:
SOAPException99 - if there is a problem in setting the source.
See Also: getContent()118
setContentId(String)
public void setContentId(java.lang.String contentId)

Sets the value of the MIME header named Content-Id to the given String.
Parameters:
contentId - a String giving the value of the MIME header Content-Id
Throws:
IllegallArgumentException - if there is a problem in setting the content id
See Also: getContentId()118
setContentLocation(String)
public void setContentLocation(java.lang.String contentLocation)

Sets the value of the MIME header Content-Location to the given String.
Parameters:
contentLocation - a String giving the value of the MIME header Content-Location
120
Throws:
IlleglalArgumentException - if there is a problem in setting the content location.
See Also: getContentLocation()118
setMimeHeader(String, String)
public abstract void setMimeHeader(java.lang.String name, java.lang.String value)

Changes the first header entry that matches the given header name so that its value is the given value, add-
ing a new header if no existing header is a match.
Parameters:
name - a String giving the header name for which to search
value - a String giving the value to be substituted for the current value
Throws:
value
See Also: getMimeHeader(String)119
121
javax.xml.soap
Text
Declaration
public interface Text extends Node81
All Superinterfaces: Node81
Description
A representation of a node whose value is text. A Text object may represent text that is content or text that is a
comment.
Member Summary
Methods
public boolean isComment()122
Retrieves whether this Text object represents a comment.

ment(SOAPElement)82
Methods
isComment()
public boolean isComment()

Retrieves whether this Text object represents a comment.
Returns: true if this Text object is a comment; false otherwise
122
References
• ebXML Transport, Routing & Packaging V1.0 - Message Service Specifica-

tion
■
http://www.ebxml.org/specs/ebMS.pdf
• XML Messaging Requirements specification
■
http://search.ietf.org/internet-drafts/draft-ietf-trade-iotp2-req-00.txt
• MIME-based Secure EDI
■
http://search.ietf.org/internet-drafts/draft-ietf-ediint-as1-13.txt
• SOAP
■
http://www.w3.org/TR/SOAP
• SOAP Messages with Attachments
■
http://www.w3.org/TR/SOAP-attachments
• JavaBeansTM Activation Framework Version 1.0a
■
http://java.sun.com/products/javabeans/glasgow/jaf.html
• Java API for XML Processing - Version 1.1 Final Release
■
http://java.sun.com/xml/xml_jaxp.html
123
124 REFERENCES

Jaxm 0 - 9 - 3 PRD Spec

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Jaxm 0 - 9 - 3 PRD Spec

Uploaded by

Copyright:

Available Formats

Java API for XML Messaging

Please send technical comments to: jaxm-expertgroup@eng.sun.com

Public Review Draft 2– August 2001

Nicholas Kassem <Nick.Kassem@sun.com>

Copyright 1999-2001 Sun Microsystems, Inc.

THIS SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.

Public Review Draft 2

RESTRICTED RIGHTS LEGEND.

Public Review Draft 2

JavaTM API for XML Messaging ...........................................i

JAXM.3.1.3 ProviderMetaData & JAXMException .........19

Public Review Draft 2

Public Review Draft 2

JAXM.S.1 Status of This Document

This specification is being developed following the JavaTM Community Process

This document has been designated as Public Review Draft 2.

The following individuals and their respective companies - in no particular order -

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT,

MUST: This word, or the terms “REQUIRED” or “SHALL”, mean

SHOULD: This word, or the adjective “RECOMMENDED”, mean

SHOULD NOT: This phrase, or the phrase “NOT

Public Review Draft 2

or even useful, but the full implications should be understood and

MAY: This word, or the adjective “OPTIONAL”, mean that an item

Public Review Draft 2

JAXM compatible implementations must support SOAP1.1 [See “SOAP” on

Public Review Draft 2

JAXM.1.1 Conceptual model

SOAP JAXM Service API

SOAP Message SOAP Message

Figure 1. B2B Messaging Conceptual Model

JAXM is intended to be a lightweight messaging API for the development of

Figure 1. makes a logical distinction between the implementation of the

Message exchange scenarios based on JAXM may be synchronous or asynchronous

Public Review Draft 2

Figure 2. Asynchronous Inquiry

In the asynchronous inquiry scenario, the sender is assumed to send a message

Figure 3. Asynchronous Update with Acknowledgement

Figure 3. depicts a scenario in which the reception of an acknowledgement

must correlate a response message to the request message (sent previously) to

Figure 4. Synchronous Update

Figure 4. reflects a synchronous scenario, in which the sender either cannot or

Figure 5. Synchronous Inquiry

The scenario in Figure 5. is a simple variation on the previous case. The

Public Review Draft 2

Figure 6. Fire and Forget

JAXM may facilitate the automation of only portions of an overall business

An important notion presented in the “B2B Messaging Conceptual Model” on

a Profile. A JAXM Profile, therefore, represents a given industry or standards

JAXM providers must implement their transport bindings in accordance with

JAXM.1.4 SOAP Packaging Model

Public Review Draft 2

JAXM.1.4.1 SOAP Message with Attachments

Communication Protocol Envelope (HTTP,SMTP...)

SOAP1.1 + Attachments MIME Envelope

Figure 7. SOAP1.1 with Attachments

Whether a message sent by a JAXM client contains an attachment part is up to

JAXM.1.4.2 SOAP Message without Attachments

Communication Protocol Envelope (HTTP,SMTP...)

SOAP1.1 Message Package

Figure 8. SOAP1.1 Packaging Model without Attachments

Figure 8. shows the packaging model for a message with no attachments. In

Public Review Draft 2