Chapter 1.

Introduction
In the history of software development, new approaches frequently bring discarded ideas back
into the mainstream of common practice. Each time an idea is revisited, prior successes and
failures become invaluable aides in improving the concept and making its implementation
better, or at least more usable. Now I'm not saying that we keep reinventing the wheel; rather,
we keep going back and improving the wheel. nd doing so can often be the catalyst for new
ideas and new technologies that were not possible with the old wheel.
!e've seen centrali"ed computing with mainframes and their associated terminals come back
disguised as application servers and thin clients. !e've seen the concept of #$%ode return in
the form of interpreted languages like &ava and 'isual (asic. )he universe of software
development seems to e*pand and contract like, well, the cosmic +niverse. If you wait around
long enough, you may ,ust be able to use the work you're doing today at some time in the
future.
)he point is, really, that a good idea is a good idea, regardless of whether it's a new idea.
)imeliness is what matters most. -o it goes for the world of distributed computing.
)he concept isn't new, but it gets revisited constantly. #ervasive infrastructure and
technologies like the Internet, web browsers, and their associated protocols have allowed us to
go back and advance the state of distributed computing. )he evolution's latest cra"e is web
services.
Web services are basically server functions that have published the interface mechanisms
needed to access their capabilities. )hey're being implemented in a wide variety of
technologies, but have a very important thing in common. they are providers of computational
services that can be accessed using a standardi"ed protocol. /or instance, you might find
a stock quote service that can return current stock market pricing and trading informationbased on a
company's stock symbol. )his is a very specific function, and that's the essence of
web services. )hey do not provide the breadth of capability found in application servers 0
they provide small, focused capabilities that are likely to prove useful when combined with
other services. 1ou can imagine an online trading application that makes use of web services
ranging from stock quotes to trade e*ecution to banking transactions. )he vision of web
services is that it will ultimately be possible to create comple* applications on the fly 0 or at
least, with minimal development time 0 by combining bits and pieces of data and services
that are distributed across the !eb. -un's slogan used to be 2)he network is the computer,2
and that vision is certainly coming to fruition.
1.1 RPC and Message-Oriented Distributed Systems
3istributed systems e*ist, for the most part, as loosely coupled entities that communicate with
each other to accomplish some task. 4ne of the most common models used in distributed
software is the remote procedure call 56#%7. 4ne reason for the popularity of 6#% systems is
that they closely resemble the function8method call synta* and semantics that we as
programmers are so familiar with. )echnologies like &ava 69I, 9icrosoft's %49, and
%46( all use this kind of model. 4f course, you have to ,ump through many hoops before
making the ever$familiar method call to a remote system, but even with all that it still feels
remarkably like making a local method call. 4ften, once the method call returns we don't carehow it
happened.: 9uch of the work in providing that abstraction to programmers at the #I
level is what makes up the ma,ority of the distributed systems implementations.
nother popular model for distributed computing is message passing. +nlike the 6#% model,
messaging does not emulate the synta* of programming language function calls. Instead,
structured data messages are passed between parties. )hese messages can serve to decouple
the nodes of the distributed system somewhat, and message$based systems often prove to be
more fle*ible than 6#%$based systems. ;owever, that fle*ibility can sometimes be ,ust
enough rope for programmers to hang themselves.
It seems that a reasonable, and powerful, compromise might be to combine these two models.
%an you imagine a system that provides for the familiarity and ease of use of 6#%$style
invocations, along with some of the fle*ibility of message$type systems< It seems to me that it
would require the definition of a data format that could describe itself, while at the same time
conforming to a standard set of rules governing that very description. ;mmm . . .
Chapter 2. The SOP Message
ll -4# messages are packaged in an =9> document called an envelope, which is
a structured container that holds one -4# message. )he metaphor is appropriate because
you stuff everything you need to perform an operation into an envelope and send it to
a recipient, who opens the envelope and reconstructs the original contents so that it can
perform the operation you requested. )he contents of the -4# envelope conform to
the -4# specification,: allowing the sender and the recipient to e*change messages in
a language$neutral way. for e*ample, the sender can be written in #ython and the recipient
can be written in &ava or %?. Neither side cares how the other side is implemented because
they agree on how to interpret the envelope. In this chapter we'll get inside the -4#
envelope.
2.1 The !TTP "inding
)he -4# specification requires a -4# implementation to support the transporting of
-4# =9> payloads using ;))#, so it's no coincidence that the e*isting -4#
implementations all support ;))#. 4f course, implementations are free to support any other
transports as well, even though the spec doesn't describe them. )here's nothing whatsoever
about the -4# payload that prohibits transporting messages over transports like -9)#,
/)#, &9-, or even proprietary schemes; in fact, alternative transports are frequently
discussed, and a few have been implemented. Nevertheless, since ;))# is the most prevalent
-4# transport to date, that's where we'll concentrate. 4nce you have a grasp of how -4#
binds to ;))#, you should be able to easily migrate your understanding to other transport
mechanisms.
-4# can certainly be used for request8response message e*changes like 6#%, as well as
inherently one$way e*changes like -9)#. )he ma,ority of &ava$based -4#
implementations to date have implemented 6#%$style messages, so that's where we'll spend
most of our time; ;))# is a natural for an 6#%$style e*change because it allows the request
and response to occur as integral parts of a single transaction. ;owever, one$way messaging
shouldn't be overlooked, and nothing about ;))# prevents such an e*change.
2.2 !TTP Re#uest
)he first -4# message we'll look at is an 6#% request. lthough it's rather simple, it
contains all of the elements required for a fully compliant -4# message using an ;))#
transport. )he =9> payload of the message is contained in an ;))# #4-) request. )ake a
quick look, but don't get too caught up in figuring out the details ,ust yet. )he following
message asks the server to return the current temperature in degrees %elsius at the server's
location.
POST /LocalWeather HTTP/1.0
Host: www.mindstrm.com
Content-Type: tet/ml! charset"#$t%-&#
Content-Len'th: ()&
SO*P*ction: #WeatherStation#
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
SO*P-,-.:encodin'Style"#http://schemas.mlsoap.or'/soap/encodin'/#0
+SO*P-,-.:1ody0
+m:2etC$rrentTemperat$re mlns:m"#WeatherStation#0
+m:scale0Celsi$s+/m:scale0
+/m:2etC$rrentTemperat$re0
+/SO*P-,-.:1ody0
+/SO*P-,-.:,n/elope0
)he -4# ;))# request uses the ;))# #4-) method. lthough a -4# payload could be
transported using some other method such as an ;))# @E), the ;))# binding defined in the
-4# specification requires the use of the #4-) method. )he #4-) also specifies the name
of the service being accessed. In the e*ample, we're sending the data to /LocalWeather at the
host specified later in the ;))# header. )his tells the server how to route the request within
its own processing space. /inally, our e*ample indicates that we're using ;))# 'ersion :.A,
although -4# doesn't require a particular version of ;))#.
)he Host: header field specifies the address of the server to which we're sending this request,
www.mindstrm.com. )he ne*t header field, Content-Type:, tells the server that we're sending
data using the tet/ml media type. ll -4# messages must be sent using tet/ml. )he
content type in the e*ample also specifies that the data is encoded using the +)/$B character
set. )he -4# standard doesn't require any particular encoding. Content-Len'th: tells the
server the character count of the #4-)ed -4# =9> payload data to follow.
-o far, all the headers have been standard ;))# headers that apply to any ;))# #4-)
messages. )he ne*t one, however, is -4# specific. )he SO*P*ction: header field is
required for all -4# request messages transported using ;))#.C It provides some
information to the ;))# server in the form of a +6I that indicates the intent of the message.
)his information is contained in an ;))# header field rather than in the message itself
because it doesn't require the system to process the =9> payload first. In turn, this means that
the server can determine if it does not have the information or resources necessary to process
the request without actually parsing the message. lthough this field can contain data in any
format or even be empty, the field itself must be present. )he header SO*P*ction:
#WeatherStation# could indicate that our request requires an active connection to the
weather station located on the roof of the building where the server resides. If the server
knows that the weather station has fallen off the building and was subsequently crushed by
a passing car, it can respond without bothering to process the -4# payload. )his may not be
a common scenario, but the point is that the server can use the +6I specified in the
SO*P*ction: field to gain some insight into the intent of the message, and act accordingly.
It's also important to know that the +6I need not take any particular form. It can be a +6>,
a name, a word, or even a number, as long as it has meaning to the server that receives
the message.
If the SO*P*ction: field contains an empty string 5##7, then the intent of the message is
actually being provided by the ;))# request +6I, which in the e*ample is /LocalWeather.
)he server may interpret this +6I to mean that it should access the weather station, or it might
have some other meaning. If the field contains no data at all, then the message contains no
information about the meaning or intent of the enclosed message. In that case, we'd e*pect the
server to go ahead and process the =9> payload.
2.$ !TTP Response
n 6#%$style request message usually results in a corresponding ;))# response. 4f course,
if the server can't get past the information in the ;))# headers, it can reply with an ;))#
error of some kind. (ut assuming that the headers are processed correctly, the system is
e*pected to respond with a -4# response. ;ere's the ;))# response to the 6#%$style
request from the previous e*ample.
HTTP/1.0 )00 O3
Content-Type: tet/ml! charset"#$t%-&#
Content-Len'th: (45
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
SO*P-,-.:encodin'Style"#http://schemas.mlsoap.or'/soap/encodin'/#0
+SO*P-,-.:1ody0
+m:2etC$rrentTemperat$re6esponse mlns:m"#WeatherStation#0
+m:temperat$re0)7.7+/m:temperat$re0
+/m:2etC$rrentTemperat$re6esponse0
+/SO*P-,-.:1ody0
+/SO*P-,-.:,n/elope0
)he response's ;))# header fields are, for the most part, similar to those of the request. )he
response code of CAA in the first line of the header indicates that the server was able to process
the -4# =9> payload. )he Content-Type: and Content-Len'th: fields have the same
meanings as they did in the request message. No other ;))# header fields are needed; the
correlation between the request and response is implied by the fact that the ;))# #4-) is
inherently a request8response mechanism.
1ou send the request and get the response as part of
a single transaction.
>et's change the original request message so that the scale reads as follows.
+m:scale0Calci$m+/m:scale0
1ou know that one, right< No, there is no %alcium scale for temperature; we've constructed
an erroneous request. -o we go ahead and send the -4# request to the server. ssuming the
weather station hasn't really fallen off the building, the server processes the request. s we
e*pected, our -4# processing code does not understand the %alcium temperature scale, and
generates the following error response.
HTTP/1.0 400 8nternal Ser/er ,rror
Content-Type: tet/ml! charset"#$t%-&#
Content-Len'th: 4)4
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
+SO*P-,-.:1ody0
+SO*P-,-.:9a$lt0
+%a$ltcode0SO*P-,-.:Client+/%a$ltcode0
+%a$ltstrin'0Client ,rror+/%a$ltstrin'0
+detail0
+m:weather%a$ltdetails mlns:m"#WeatherStation#0
+messa'e0-o s$ch temperat$re scale: Calci$m+/messa'e0
+errorcode01)(:+/errorcode0
+/m:weather%a$ltdetails0
+/detail0
+/SO*P-,-.:9a$lt0
+/SO*P-,-.:1ody0
+/SO*P-,-.:,n/elope0
)he ;))# error code of DAA with the e*planation 2Internal -erver Error2 shows that an error
occurred. &ust as before, the header includes the Content-Type: and Content-Len'th:
;))# header fields. )he -4# spec says that if the message is received and understood, the
response should be sent using a C** status code. !hen the server does not understand the
message, or if the message is improperly formatted, is missing information, or cannot be
processed for any other reason, the server must use ;))# code DAA 52Internal -erver Error27.
)hat ;))# header is followed by a -4# envelope, which includes its own fault code, fault
string, and a detailed description of the error.
protocol error is really a good way to package a -4# error. )ransport errors and -4#
errors really don't have anything to do with each other. fter all, the response includes a
proper -4# message that describes the error in detail. ;owever, in fairness to the
developers of the -4# spec, this error$handling procedure is in line with the way ;))#
delivers errors in retrieving, say, ;)9> documents. I could still argue both sides, but that's
the requirement and it certainly doesn't interfere with the -4# processing.
2.$.1 Summari%ing the !TTP "inding
)hat's ,ust about all we need to cover about the -4# ;))# binding. )he beauty of it, really,
is that ;))# is a well$established mechanism that works e*tremely well for transporting
=9>, and therefore it's a good way to transport -4# messages.
-ome of the details of the =9> in the previous e*amples might be obvious to you, even
though we haven't covered them yet. If you understand the =9>, great. 4therwise, fear not.
)he purpose of the discussion so far has been to show you what the ;))# binding for -4#
looks like. In the ne*t section we'll take a detailed look at the -4# envelope, which is the
=9> payload that contains the -4# requests and responses.
2.& The SOP 'n(e)ope
)he -4# envelope represents the entirety of the =9> for a -4# request or response.E )he
,n/elope is the highest$level =9> element in the message, and it must be present for the
message to be considered valid. -o in essence, the ,n/elope represents the =9> document
that contains the -4# message. )he ,n/elope can contain an optional Header element that,
if present, has to be the first subelement of the ,n/elope. )he ,n/elope must contain a 1ody
element.F If the ,n/elope contains a Header element, then the 1ody element has to come
right after the Header; otherwise the 1ody has to be the first subelement of the ,n/elope.
-4# envelope packaged and transported using ;))# is similar to a paper envelope sent
using the postal service. )he -4# envelope is the paper envelope; the -4# header 5if
present7 and the -4# body are the contents of the paper envelope; and the ;))# headers
are the physical address information on the outside of the paper envelope.
!ith a little imagination we can complete the analogy. )he return address on a paper
envelope has no direct counterpart in the -4# process; however, in both cases an
undeliverable message is returned to sender. )he only thing missing is the stamp. I guess this
is where the analogy may break down a little. -till, although you probably don't pay
specifically for sending an ;))# request to a server, you're probably paying for Internet
service. -o there's your postage stampG
2.&.1 *amespaces
+nderstanding =9> namespaces is important to understanding -4#. I'm not going to cover
all the details of =9> namespaces, as that would take a long time and wouldn't reflect
directly on the sub,ect matter of this book. Nonetheless, I'll give you a quick description of
=9> namespaces as they relate to -4#. (asically, namespaces are an =9> mechanism for
eliminating ambiguity between =9> elements and attributes. In other words, they help us to
understand the conte*t, or meaning, of the element. >et's look at part of an earlier e*ample.
+m:2etC$rrentTemperat$re mlns:m"#WeatherStation#0
+m:scale0Celsi$s+/m:scale0
+/m:2etC$rrentTemperat$re0
=9> allows us to create something similar to programming language variables to represent
namespaces. In the e*ample above we've created a namespace identifier named m by using the
namespace declaration mlns:m"#WeatherStation#. @enerally, the synta* of a namespace
declaration in a -4# message typically is.
mlns:id="some URI"
)he mlns keyword tells the =9> processor that we're defining a namespace. If the
definition includes a qualifier name, then we're also creating a namespace qualifier that can be
used to distinguish this namespace from other namespaces. If we don't specify a qualifier
name, then we're defining a default namespace. )he id is the identifier name we're declaring,
in this case, the letter m. )he last part is a +6I that provides the conte*t for the namespace.
lthough the +6I is frequently a +6>, it's important to reali"e that it's ,ust an identifier; the
recipient of a document won't try to download the content of the +6I 5which may not even
e*ist7. !e can use the letter m to qualify elements that are within the same scope as the
declaration itself.
Hualifying an =9> element means associating it with a specific namespace. In this e*ample,
we qualify the 2etC$rrentTemperat$re =9> element with the namespace WeatherStation
by declaring the element as m:2etC$rrentTemperat$re. )his means that
2etC$rrentTemperat$re is associated with the WeatherStation namespace, represented by
the identifier m.
Note that the namespace identifier m can be used to qualify the element in which it is declared.
(ut there's nothing special about using m in this element. !e aren't required to qualify the
2etC$rrentTemperat$re element with the namespace identifier m ,ust because that element
contains the namespace declaration as an attribute, but rather because we need to indicate
where 2etC$rrentTemperat$re is defined. #utting the declaration in this element creates the
scope for which the identifier m can be used. %learly, it's valid to use the identifier at the same
level as its declaration; that's what we did in the e*ample. -o the scope of the namespace is
bounded by the element that contains the declaration. )his means that the namespace I3 can
be used on the element that contains the declaration, any attributes of that element, and any
subelements and associated attributes of the containing element. )he namespace identifier is
not within the scope of the =9> elements that are higher up in the containment hierarchy. If
you go back and look at the original e*ample, this means that the namespace identifier m could
not be used for attributes of the 1ody element because m would be out of scope. )he scoping
rules are similar to those used in block$oriented programming languages like &ava, where the
namespaces are pushed onto a stack as you enter bracketed blocks of code, and the stack is
popped as you e*it the block. ;ere's a &ava code snippet that shows the same kind of scoping
for variables /ar1 and /ar).
int /ar1 " 10!
;
int /ar) " ) < /ar1! // this is O3 =eca$se /ar1 is in scope
>
/ar1 " /ar)! // this is in/alid =eca$se /ar) is o$t o% scope
Namespace qualification is often necessary to determine the intended meaning of the element
or attribute. %onsider the following e*ample.
+tr$c?monitor0
+scale0(@97*+/scale0
+wei'ht01)000+/wei'ht0
+scale0Celci$s+/scale0
+temperat$re0)4+/temperat$re0
+/tr$c?monitor0
)his =9> contains some data that may have been collected at a truck monitoring station. )he
first occurrence of the scale element specifies the scale used to weigh the truck. >ater on, we
have the same element name, scale, to describe the temperature scale used to measure the
outside temperature at the monitoring location. -o how are we to know the meaning of the
two scale elements< 1ou might feel that the overall structure is intuitive ,ust by looking at it,
but this may not always be the case.
%ertainly one way to avoid this problem would be to use more descriptive names, or =9>
structures that better represent the meaning of the elements. (ut you may not always be in
control of those things; you may be creating a composite document from =9> fragments that
come from many different sources. )he use of appropriate namespace qualifications can lend
a hand in resolving name conflicts and ambiguity. )he following document is the same as the
previous one, with the two scale elements properly qualified.
+tr$c?monitor mlns:ns1"#Tr$c?Scale# mlns:ns)"#Thermometer#0
+ns1:scale0(@97*+/ns1:scale0
+wei'ht01)000+/wei'ht0
+ns):scale0Celci$s+/ns):scale0
+temperat$re0)4+/temperat$re0
+/tr$c?monitor0
)he first occurrence of scale is now associated with the Tr$c?Scale namespace, while the
second occurrence of scale is associated with the Thermometer namespace. 3id you notice
that both of the namespace declarations are attributes of the same element< )hat's perfectly
valid, since namespace declarations are nothing more than attributes, and an =9> element
can have more than one attribute.
-4# defines two namespaces to be used by -4# messages. )he -4# ,n/elope is
qualified by the namespace http://schemas.mlsoap.or'/soap/en/elope. !e used this
namespace in earlier e*amples by declaring the SO*P-,-. namespace identifier and using it to
qualify the ,n/elope element. )he namespace identifier
http://schemas.mlsoap.or'/soap/encodin' is used to declare the encodin'Style
attribute, which we'll discuss more later. Note that the encodin'Style attribute is namespacequalified
using the SO*P-,-. identifier. ;ere's a quick look at it again.
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
SO*P,-.:
encodin'Style"#http://schemas.mlsoap.or'/soap/encodin'/#0
. . .
. . .
+/SO*P-,-.:,n/elope0
2.+ The 'n(e)ope ')ement
)he ,n/elope is the topmost element of the =9> document that represents the -4#
message. )he ,n/elope is the only =9> element at the top level; the rest of the -4#
message resides within the ,n/elope, encoded as subelements. -4# message must have
an ,n/elope element. )he ,n/elope can have namespace declarations, as shown in the
earlier e*amples, and needs to be qualified as shown earlier, using the
http://schemas.mlsoap.or'/soap/en/elope namespace. )hat's why the element name is
shown as SO*P-,-.:,n/elope. It is also common for the ,n/elope element to declare the
encodin'Style attribute, with the attribute namespace$qualified using the declared
namespace identifier SO*P-,-. as well.
ll subelements and attributes of the ,n/elope must themselves be namespace$qualified.
)hese elements and attributes are also qualified by SO*P-,-., ,ust as the ,n/elope is
qualified. /or the remainder of this chapter and the rest of the book, we'll use the SO*P-,-.
namespace identifier to mean the http://schemas.mlsoap.or'/soap/en/elope
namespace. )his should make for easier reading. Ieep in mind that it's the namespace itself
that matters, not the name used for the qualifier.
2., The !eader ')ement
)he -4# header is optional. If it is present, it must be named Header and be the first
subelement of the ,n/elope element. )he Header element is also namespace$qualified using
the SO*P-,-. identifier.
9ost commonly, the Header entries are used to encode elements used for transaction
processing, authentication, or other information related to the processing or routing of the
message. )his is useful because, as we'll see, the 1ody element is used for encoding the
information that represents an 6#% 5or other7 payload. )he Header is an e*tension
mechanism that allows any kind of information that lies outside the semantics of the message
in the 1ody, but is nevertheless useful or even necessary for processing the message properly.
Header elements should limit the use of attributes to those elements that are immediate
children of the Header element itself. )he spec says that this should be done, meaning that
although one can use them on elements deeper in the element hierarchy underneath the
Header element, the recipient is required to ignore the attributes on such elements.
;ere's an e*ample of a -4# header that contains an immediate child element named
$sername. !e don't apply any attributes to the $sername element, but we do namespacequalify
it. )he $sername element identifies the user who is making the request.
+SO*P-,-.:Header0
+ns1:$sername mlns:ns1"#Aa/aSoap1oo?#0
Aessica
+/ns1:$sername0
+/SO*P-,-.:Header0
2.- The actor ttribute
-4# message often passes through one or more intermediaries before being processed.
/or e*ample, a -4# pro*y service may stand between a client application and the target
-4# service. !e'll see an interesting e*ample of this in %hapter :A, where we'll develop a
-4# application service that pro*ies another service on behalf of the client application,
which actually specifies the ultimate service address. )herefore, the header may contain
information intended solely for the intermediary as well as information intended for the
ultimate destination. )he actor attribute identifies 5either implicitly or e*plicitly7 the
intended recipient of a Header element.
It's important to understand the requirements that -4# puts on an intermediary. Essentially,
it requires that any -4# Header elements intended for use by an intermediary are not passed
on to the ne*t -4# processor in the path. Header elements represent contracts between the
sender and receiver. ;owever, if the information contained in a Header element intended for
an intermediary is also needed by a downstream server, the intermediary can insert the
appropriate Header in the message to be sent downstream. In fact, the intermediary is free to
add any Header elements it deems necessary.
If an actor attribute doesn't appear on a Header element, it's assumed that the element is
intended for the ultimate recipient. In essence, this is equivalent to including the actor
attribute with its value being the +6I of the ultimate destination.
>et's e*tend the previous e*ample by adding an actor attribute. -ay that the message is being
sent to an intermediate application server located at http://www.mindstrm.com/AppServer. !e
want that application server to log the name of the user that made the request, and then pass
the request on to the final destination server. )o do so, we set the actor for the $sername
element to http://www.mindstrm.com/AppServer.
+SO*P-,-.:Header0
+ns1:$sername
mlns:ns1"#Aa/aSoap1oo?#
SO*P-,-.:actor"#http://www.mindstrm.com/*ppSer/er#0
Aessica
+/ns1:$sername0
+/SO*P-,-.:Header0
)he pro*y application server sees that the $sername element is intended for itself and not for
the final destination, and uses the data appropriately. It removes the $sername element from
the header before passing the message on to its ultimate destination. s you can see, the
actor attribute is namespace$qualified by the SO*P-,-. identifier. )hat's because the actor
attribute is defined by -4# and specified by the associated
http://schemas.mlsoap.or'/soap/en/elope namespace.
2.. The must/nderstand ttribute
-4# includes the concept of optional and mandatory header elements. )his doesn't mean
that the inclusion of the elements is mandatory 0 that is an application issue. Instead,
2mandatory2 means that the recipient is required to understand and make proper use of the
information supplied by a Header element. )his requirement allows us to accommodate
situations in which a recipient of a -4# message can't perform its ,ob unless it knows what
include the m$stBnderstand attribute with an assigned value of :.
)his may be necessary if the sending application is upgraded with a new version, for e*ample.
)hat new version may use some new information that has to be processed by the server in
order for the result to be useful. 4f course you'd e*pect that there would be a corresponding
upgrade to the server, but maybe that hasn't happened yet. (ecause of the version mismatch,
the older version of the server does not understand the new -4# header element that it
received from the upgraded client application. >et's say, for e*ample, that the $sername
header element must be understood by the recipient; if it is not, the message should be
re,ected. !e can include this requirement in the -4# message by assigning the
m$stBnderstand attribute the value of :. 5)he value A is essentially equivalent to not
supplying the attribute.7 >et's modify our previous e*ample to indicate that the recipient must
understand the $sername element.
+SO*P-,-.:Header0
+ns1:$sername
mlns:ns1"#Aa/aSoap1oo?#
SO*P-,-.:actor"#http://www.mindstrm.com/*ppSer/er#
SO*P-,-.:m$stBnderstand"#1#0
Aessica
+/ns1:$sername0
+/SO*P-,-.:Header0
If the recipient of this message does not understand the $sername element, it is required to
respond with a -4# fault. )he response might look something like this.
HTTP/1.0 400 8nternal Ser/er ,rror
Content-Type: tet/ml! charset"#$t%-&#
Content-Len'th: (@(
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
+SO*P-,-.:1ody0
+SO*P-,-.:9a$lt0
+%a$ltcode0SO*P-,-.:C$stBnderstand+/%a$ltcode0
+%a$ltstrin'0SO*P C$st Bnderstand ,rror+/%a$ltstrin'0
+%a$ltactor0http://www.mindstrm.com/*ppSer/er+/%a$ltactor0
+/SO*P-,-.:9a$lt0
+/SO*P-,-.:1ody0
+/SO*P-,-.:,n/elope0
)he fault response includes a %a$ltcode, a %a$ltstrin', and a %a$ltactor; the
%a$ltactor indicates where the fault took place. !e'll look more closely at faults later in this
chapter.
2.0 The encodingSty)e ttribute
)he encodin'Style attribute specifies the data encoding rules used to seriali"e and
deseriali"e data elements. It is important to understand that -4# does not specify any
default rules for data seriali"ation. -4# does, however, specify a simple data typing scheme
commonly supported by -4# implementations. )his is the sub,ect of the ne*t chapter, so we
won't get into the details of the encoding rules here. ;owever, it's important to understand
how to specify the encoding style to be used for seriali"ing and deseriali"ing the element data
in the -4# message.
)he encodin'Style attribute is namespace$qualified using the SO*P-,-. namespace
identifier. In the following e*ample we specify the encodin'Style attribute as part of the
,n/elope element; we'll see e*amples in later chapters that make this declaration in the 1ody
element instead. Either way works, as long as you recogni"e that the encodin'Style attribute
applies to the element in which it was declared as well as all of its subelements 5i.e., it's inscope7.
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
SO*P-,-.:encodin'Style"#http://schemas.mlsoap.or'/soap/encodin'/#0
. . .
. . .
+/SO*P-,-.:,n/elope0
1ou can supply more than one +6I in the declaration. In that case, the first +6I must be the
most specific, and the last must be the least specific. ;ere's an e*ample.
SO*P-,-.:encodin'Style"#http://www.mindstrm.com/ti'ht,ncodin'
http://www.mindstrm.com/loose,ncodin'#
In this case, the system looks for the encoding rules first using
http://www.mindstrm.com/tightEncoding.D If the rule can't be found using that +6I, the
system then tries http://www.mindstrm.com/looseEncoding. It's possible to turn off the
currently scoped encoding style by specifying an empty string for the +6I 5##7. )his
declaration applies to the current element and all of its subelements.
2.11 'n(e)ope 2ersioning
)he -4# spec doesn't define a numbering system for declaring which version of the -4#
envelope you're using. In -4# :.:, all envelopes must be associated with the
http://schemas.mlsoap.or'/soap/en/elope namespace,J which we've used in all of the
previous e*amples. )hat's it. No other versioning information is used for -4# envelopes at
this time. If a -4# message is associated with any other namespace, or if no namespace is
HTTP/1.0 400 8nternal Ser/er ,rror
Content-Type: tet/ml! charset"#$t%-&#
Content-Len'th: (11
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
+SO*P-,-.:1ody0
+SO*P-,-.:9a$lt0
+%a$ltcode0SO*P-,-.:.ersionCismatch+/%a$ltcode0
+%a$ltstrin'0SO*P ,n/elope .ersion Cismatch+/%a$ltstrin'0
+/SO*P-,-.:9a$lt0
+/SO*P-,-.:1ody0
+/SO*P-,-.:,n/elope0
2.11 The "ody ')ement
)he -4# 1ody element is mandatory in -4# :.:. If there is no -4# header, the 1ody
must be the first subelement of the ,n/elope; otherwise it must directly follow the -4#
Header element. )he 1ody element is also namespace$qualified using the SO*P-,-. identifier.
)he 1ody element contains the -4# request or response. )his is where you might find an
6#%$style message that contains the method name and its parameters, or a one$way message
and its relevant parts, or a fault and its details. -4# 1ody elements are not completely
defined by the -4# specification; we'll cover that sub,ect in great detail later. In fact, -4#
defines only one kind of 1ody. the -4# 9a$lt.
>et's take another look at one of the earlier e*amples of an envelope with a -4# 1ody
element. In this case the request is an 6#%. !e've namespace$qualified the 1ody element
using the same SO*P-,-. namespace identifier that we used for the other -4#$defined
elements and attributes.
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
SO*P,-.:
encodin'Style"#http://schemas.mlsoap.or'/soap/encodin'/#0
+SO*P-,-.:1ody0
+m:2etC$rrentTemperat$re mlns:m"#WeatherStation#0
+m:scale0Celsi$s+/m:scale0
+/m:2etC$rrentTemperat$re0
+/SO*P-,-.:1ody0
+/SO*P-,-.:,n/elope0
2.12 SOP 3au)ts
)he 9a$lt is the only 1ody element entry defined by -4#. It's used to carry error
information back to the originator of a -4# message. )he 9a$lt element must appear as an
immediate subelement of the 1ody element, and it can't appear more than once.
-4# defines four subelements of the 9a$lt element. Not all of these are required, and some
are appropriate only under certain conditions. )hese elements are described in the following
sections. 1ou'll probably recogni"e that we've seen all of these in previous e*amples, so you
may want to flip back and look at them again after you've read these descriptions.
2.12.1 The 4au)tcode ')ement
)he %a$ltcode element provides an indication of the fault that is recogni"able by a software
process, providing an opportunity for the system receiving the fault to act appropriately. )he
code is not necessarily useful to humans 0 that is the purpose of the %a$ltstrin' element
described in the ne*t section. )he %a$ltcode element is mandatory, and must appear as a
subelement of the 9a$lt element. -4# defines a number of fault codes for use in the
%a$ltcode element. )hese codes are associated with the
http://schemas.mlsoap.or'/soap/en/elope namespace. ;ere are brief descriptions of
the -4#$defined fault codes.
.ersionCismatch
Indicates that an invalid namespace was associated with the -4# ,n/elope.
C$stBnderstand
9eans that there was a -4# Header element that contained the m$stBnderstand
attribute with a value of :, and either the attribute was not understood or the semantics
associated with the attribute couldn't be followed.
Client
Indicates that there was some error in the formatting of the -4# message or that the
message did not contain the appropriate or necessary information. )he client should
assume that the message is not suitable to be sent again without making the
appropriate changes. !e saw an e*ample of this when we requested the local
temperature using an invalid temperature scale.
Ser/er
Indicates that the message could not be processed due to reasons not related to the
formatting or contents of the received message. )his can be interpreted to mean that
the message could be re$sent without modification possibly processed at some later
time. /or e*ample, the back$end database server needed to complete the requested
action may be currently offline, but may be back online later.
)hese fault codes are e*tensible; this means that they can be e*tended using a dot notation,
where the name following each dot serves to provide more specific detail. /or e*ample.
Ser/er.WeatherStation9ail$re
!hile this can still be considered a Ser/er error, it provides more information by indicating
that there was some problem with the weather station equipment needed to fulfill the request.
!e could e*tend this fault code even further, as follows.
Ser/er.WeatherStation9ail$re.SmashedToPieces
)his fault code lets us know that the weather station equipment is beyond repair, possibly
because it fell off the building and was subsequently crushed. 6emember, however, that these
Java and SOAP
CK
codes are meant to be processed by software. E*tended fault codes should be defined in
anticipation of possible situations or conditions, allowing the recipient of the fault to act
accordingly. 5I'm not sure that smashed equipment would qualify as an anticipated condition.7
2.12.2 The 4au)tstring ')ement
)his element is also mandatory, and must appear as a subelement of the 9a$lt element. Its
purpose is to provide a human$readable description of the fault; it's not designed to be
processed by the recipient the way the %a$ltcode element is. It is e*pected that the sender
will populate this element with a reasonable description that would make sense to the reader
within the conte*t of the original request.
2.12.$ The 4au)tactor ')ement
)his element is required only under certain conditions, and when present must be a
subelement of the 9a$lt element. It is the corollary to the actor header attribute described
earlier. It provides an indication of the system that was responsible for the fault. Earlier, we
talked about -4# intermediaries and used a pro*y application server as an e*ample. )here,
the pro*y generated the fault because it didn't understand what to do with the $sername
element. (ecause the application pro*y was not the intended ultimate recipient of the original
message, it was required to include the %a$ltactor element, identifying itself as the source
of the fault. )he value of this element is the +6I of the fault generator.
If the source of the fault is the ultimate destination of the message, the 9a$lt element is not
required to include a %a$ltactor element. ;owever, this element may be included even
under these circumstances.
2.12.& The detai) ')ement
)he detail element provides information related to faults that occur due to errors associated
with the 1ody element of the request message. If the contents 5or lack of contents7 of the 1ody
preclude the proper processing of the message, then the detail element must appear as a
subelement of the 9a$lt. 4n the other hand, if the fault is not related to the 1ody element of
the message, the detail element must not be included; -4# specifies that the absence of a
detail element indicates that the fault is unrelated to the processing of the 1ody element.
In particular, the detail element cannot be used to further describe faults related to -4#
Header elements. In the earlier e*ample, the pro*y application server was not able to further
describe the fault using a detail element because the problem was unrelated to the contents
of the 1ody.
2.12.+ nother 3au)t '5amp)e
;ere's another complete e*ample of a -4# fault.
Java and SOAP
CB
HTTP/1.0 400 8nternal Ser/er ,rror
Content-Type: tet/ml! charset"#$t%-&#
Content-Len'th: 454
+SO*P-,-.:,n/elope
mlns:SO*P-,-."#http://schemas.mlsoap.or'/soap/en/elope/#
+SO*P-,-.:1ody0
+SO*P-,-.:9a$lt0
+%a$ltcode0SO*P-,-.:Client+/%a$ltcode0
+%a$ltstrin'0Client ,rror+/%a$ltstrin'0
+%a$ltactor0http://www.mindstrm.com/LocalWeather+/%a$ltactor0
+detail0
+m:weather%a$ltdetails mlns:m"#WeatherStation#0
+messa'e0-o s$ch temperat$re scale: Calci$m+/messa'e0
+errorcode01)(:+/errorcode0
+/m:weather%a$ltdetails0
+/detail0
+/SO*P-,-.:9a$lt0
+/SO*P-,-.:1ody0
+/SO*P-,-.:,n/elope0
)his is really the same response we used earlier in the chapter. )he only difference is that this
time we included the %a$ltactor element to identify the source of the fault. -o this e*ample
includes an instance of every -4# fault code, as well as a detail element describing the
fault a little further.
t this point, we're finished looking at the -4# message itself. 4ur ne*t step is to look at
the encodings that are used in messages.