Introduction to web services and XML - JavaTech: An Introduction to Scientific and Technical Computing with Java - page 575

defines a calculate() method. Obviously the calculate() method requires
the name, age, sex, and smoker or non-smoker status to perform its work. In real-
ity, when the remote method is called, the data flows from an RMI client to an
RMI server “over the wire” in a binary format. Let's imagine, however, that we
can read that data as plain text. A message from client to server might contain
something like this:
LifeExpectancy.calculate ( " Jackson " , " Turner " ,49,2,false)
But what do those parameters really mean? To interpret this data requires knowing
how it is used. In practice, there should be some documentation that defines how
to use the LifeExpectancy interface, but let's imagine for the moment that the
documentation is missing. In this example, the person's first and last names have
been deliberately chosen to be ambiguous about which name is the first name
and which is the last. If we know a little about the server, we can guess that 49 is
probably the age in years, and the 2 must be an indicator of the sex - perhaps 1 for
male, 2 for female. The final Boolean parameter is surely the smoker/non-smoker
status, but is it a Boolean value for “smoker” or “non-smoker”?
To clarify what the data means, let's now look at an RMI interface for the
server that uses this data:
public interface LifeExpectancy extends Remote {
public int calculate (
String first - name, String last - name,
int age, int sex, boolean smoker
) throws RemoteException;
}
With this additional information, we can see that the person's name must be
“Jackson Turner” instead of “Turner Jackson” and that the false Boolean value
for the smoker parameter means that he or she is not a smoker. We still don't
know how to decode the sex parameter. Ideally the documentation associated
with this server would explain that the age is in years, the sex is an integer with
1 meaning female and 2 meaning male (because, alphabetically, female comes
before male), and that the returned value would be the expected number of years
left to live. The meanings of the first - name and last - name parameters and
the Boolean smoker are pretty clear from context but that does not mean that
the documentation should be omitted.
The point is that an examination of the data alone without any prior knowledge
of how the server uses that data is insufficient information to know what the data
really means. An XML formulation of the same data might look like this:
< LifeExpectancyParameters >
< Name >
< FirstName > Jackson < /FirstName >