I was intrigued by the REST support in JAX-WS. REST style could be very useful in certain situations,
not to mention the fact that there are already many REST-style services out there.

While I don’t want to get into SOAP vs. REST debate here I still want to quickly mention one
very important REST advantage, which is security.

Since each service call operation in REST is an HTTP GET URL, it makes it easy to use
traditional Web authorization schemes, including Apache mod_authnz or J2EE declarative security defined in web.xml.
Contrast that with SOAP, which requires looking inside the message to figure out what security policy should be applied.
Another side of it is auditing and monitoring. With REST I can easily see all the details of the requests to my web service
operations just by looking at the Web server’s access log and/or using one of the numerous log analysis tools.
SOAP does not give me this information automatically; different application servers and ESB products may provide these capabilities, but there is no guarantee (since it is not part of any specification).

In any event, REST has its place and so it’s nice to see that JAX-WS authors recognized it.

Unfortunately, upon closer examination, it turned out that REST support in JAX-WS is pretty shallow.
REST is really a second class citizen compared to SOAP. Here’s why I came to this conclusion:

• Automatic WSDL generation (when using annotations in service implementation class) is not supported.
  I was expecting to see the support of HTTP GET binding defined in WSDL 1.1, but it is not there.
  In general, the spec does not mandate any WSDL to Java or Java to WSDL binding support for REST.

• Object serialization/deserialization is not supported either. This is not unexpected since mapping of a complex object graph to name/value pair GET string may be non-trivial. But I don’t see a problem of doing it for simple flat objects that don’t have nesting.

• Consequently, in order to use REST, one has to rely on dispatcher API on the client and so the query string has to be created manually. Same is happening on the server where developers have to use WebServiceContext and parse the query string manually.

In short, using REST requires some low-level programming; its support is clearly limited compared to SOAP.

What I would like to see is the ability to implement a RESTful service by simply adding
@BindingType(value=HTTPBinding.HTTP_BINDING)
annotation without having to make any other changes relative to a regular SOAP service (or client).
Clearly, we’re not there yet.

Tags: Web services, SOAP, REST

Lately I’ve been playing with
JAX-WS reference implementation (version EA3).
JAX-WS is the next version of JAX-RPC (i.e., JAX-WS is renamed JAX-RPC 2.0) and it
comes with many interesting features, including annotations, HTTP binding, MTOM,
asynchronous client operation, direct access to XML stream (finally!) and others.

In this entry I will focus on
annotations. Annotations allow developers to configure binding,
handler chains, set names of portType, service and other WSDL parameters.
This makes it possible to use “Java to WSDL” approach as the primary way for
developing Web services (for the server side).
Previously with JAX-RPC I was leery of this approach since it was
not possible to “fine tune” generated WSDL file.

Annotations greatly simplify Web services development process. For the server side,
JAX-WS only generates a wrapper class for the parameters of the service operation.
If “bare” (“unwrapped”) mode is used, then no code is generated and so this step can be
skipped completely (in other words, all annotations will be handled at run time).
This makes it easy to do all development from IDE, for example in my case I
deploy to Tomcat and I use Eclipse with Sysdeo plugin,
and so I was able to
change the code in my Web service class without
having to restart the server.

Changing annotations themselves does require bouncing the server, but still there is
no code generation involved and so there is no build file to run.

Note that code generation is still required for the client side unless dynamic API is used.

Finally, here is an example of a simple Web service that takes Person object
and returns concatenated full name.

import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

@WebService(
    // Name maps to PortType in WSDL. Default is the name 
    // of the class which is not very intuitive
    name = "PersonService",
    // by default, the namespace is derived from the Java package 
    // name which is not always desirable
    targetNamespace = "http://myarch.com/personservice",
    /* I use the "Endpoint" suffix as it is better convey the 
     * meaning of this parameter in WSDL and also since this 
     * will be the name of the "factory" class generated for the 
     * client side. The default is the name of the class + "Service"
     */
    serviceName="PersonServiceEndpoint"
)

/*        
 * Note that document/literal/wrapped is the default, but using  
 * "bare" as opposed to "wrapped" allows to avoid code generation.          
 */
@SOAPBinding(
    parameterStyle=SOAPBinding.ParameterStyle.BARE)
        
public class PersonServiceImpl {
    
    public java.lang.String produceFullName( Person person) {

        return person.getFirstName()+" "+person.getLastName();
    }
}

Tags: Web services, JAX-WS, JAX-RPC

I think that it‘s time for us to start learning from the successes of public Web
services, such as Google maps, Ebay and Amazon. Let‘s face it, today enterprise
SOA
implementations are still in infancy. Most organizations are just testing waters,
developing prototypes and implementing pilot projects.

At the same time, Google maps, Ebay and Amazon Web services have been
tremendously successful. I know that Google maps example has already been
overused by the “Web 2.0” hype, but it is indeed pretty amazing. I subscribe to Google
maps mania blog and there are several new “mashup” applications being
announced every day. So how do these service providers manage to keep their
diverse array of clients happy?

I think that the most important distinction of a successful Web service provider
is that it goes above and beyond just publishing
WSDL
and schema files. These service providers take time to develop detailed samples,
documentation and clients libraries. For example, Ebay provides client
libraries for Windows, Java, Perl and so on. Google maps is obviously
JavaScript. Google search is exposed using WSLD/SOAP but there are also client
libraries for Java and .NET that hide complexities of WSDL. Amazon provides
entire Associate
Engine application written in Perl to interface with its Web services.

This goes against the common view that
WSDL
/Schema of a service provides complete service definition. This view also
suggests that all that a service provider needs to do is to announce its
WSDL
to the world (or to a community of customers/partners) and the world will
immediately adopt the service. This approach shifts the responsibility of
implementing the code to access a service (client library or
SDK
) to the clients. And for a complex
WSDL
(or multiple
WSDLs), this may mean a lot of effort (especially if we take testing into account).
We all know how tricky it is to develop an elegant
API
. Code generators typically don‘t do a very good job, or they are too inflexible.
Just look at code generators supplied with today‘s
JAX
-RPC implementations that all insist on generating Java objects from schema.
Besides, letting the clients develop the code does not allow service provider to
implement validations on the client side, as I pointed out in my previous
entry.

I think that successful
SOA
implementations will rely on the clients libraries developed by service
providers. These libraries will utilize features of the target language and
incorporate some client-side logic. They will also ensure interoperability.
These libraries could also take into account capabilities of the client‘s
underlying application server or platform. For example, a client library can
utilize WS-ReliableMessaging if the client’s application server supports it.

As a result, the role of
WSDL
will diminish greatly.
WSDL
has many problems, including its hard-to-comprehend name-based links, verbosity
and incompleteness (for example, it does not explain if any of WS-* specs, such
as WS-Security, must be used in order to be able to access a service). Client
libraries can fix these problems and shield users of a service from having to
deal with low-level details of
WSDL
and WS-* specs.

Tags: WSDL, Web services

Contracts are important for Web services. Design by contract (DBC) is nothing
new, but, unfortunately, formal precondition and postcondition specifications
have never become mainstream, at least not in the way they were presented by
Bertrand Mayer in Object
Oriented Software Construction.

However, with the advent of Web services, I think it‘s time to re-introduce
DBC
to the mainstream. Here‘s why:

• From a client‘s prospective, testing and debugging a Web services call is much
  costlier than a local method call. For example, service providers may restrict
  the number of calls per day in test environment, so trial and error may not be
  an option. So it is important for a client to be able to understand exactly
  what is required from the clients (precondition) and what is returned by the
  service (postcondition).
• Web services can be exposed to a very wide range of clients that use different
  technologies. So it is important for service providers to be able to
  unambiguously define the contract with the clients to simplify error and
  exception processing by potentially separating (externalizing) validation logic
  from the service‘s business logic.

Preconditions and postconditions for Web services must support the following
capabilities:

• Validation of input and output parameters. This is partly addressed by the
  Schema, but that are many types of validations that can‘t be expressed using
  Schema, such as cross-field or cross-parameter validations (e.g., “endDate >
  beginDate“). Postconditions should also be able to validate the outputs
  relative to the inputs, e.g., “resultFlightDate>=requestedDate“.
• Preconditions and postconditions should be able to validate the state of the
  service. Classical Meyer‘s example is a stack class with “remove“ operation
  where the precondition states the stack must not be empty. In Web services world,
  oftentimes there is a need to specify dependencies (so they would be clear to
  the clients) between calls to different operations, e.g., operation “b“ can only
  be called after operation “a“ was called.
  BPEL
  can do some of it but only on a very limited scale. And
  BPEL
  is not really a validation tool.
• Precondition and postcondition checks can run on the server or on the client. In
  test environment it might be beneficial to run them on the client for faster
  development.

So what is the solution? I‘m hoping that at some point
DBC
will find its way into one of the numerous WS specifications. For example, there
are some “traces” of
DBC
in the newly announced WS-Semantics.
Although at this point WS-* specifications proliferate at such speed that I
doubt that anyone can keep up with them (except, of course, vendors and standard
organizations who keep churning them out) so it may do more harm than good.

So the easiest solution for the time being could be for service providers to
actually develop client libraries that implement preconditions (and may be even
postconditions). This will allow the clients to deal with APIs (and perhaps the
source code) expressed in the language that they understand instead of having to
deal with bare-bone
WSDL
which has to be translated into the target language anyway. These libraries can
even include “stubbed” versions of the services that can run entirely on the
client for testing purposes. Yes, it‘s more work for service providers, but,
realistically, how many different languages/platforms are we talking here? In
enterprise it probably boils down to various flavors of
J2EE
and .NET. There are also Python,
PHP
, Ruby and JavaScript for
AJAX
clients. For a commercial service provider, the cost of developing these fairly
simple client libraries will be returned many times over by the added
convenience for the clients. For an example, just look at pygoogle
and other Python wrappers for popular Web services. Granted, this approach does
not fully address my second requirement for state validation (although it can be
done using a smart client library), but I think it‘s a good start nevertheless.

Tags: Web services, Design by contract, Web services design

SOAP gets mentioned every time people talk about Web services. SOAP is almost always considered an integral part of any “serious” Web services implementation, especially if there is also a desire to use WSDL.

But it does not have to be. WSDL 1.1 has HTTP binding support and this support will be beefed up in
WSDL 2.0. Granted, the support for WSLD HTTP binding is not very good right now, for example JAX-RPC does not mandate it at all (SOAP binging and SOAP with Attachment are the only two requirements). Assuming the support for HTTP binding will improve or if using WSDL is not even a requirement (after all, a service can be described using “plain English”, as long as developers can understand this description), how should one decide whether to use SOAP?

To me, it all comes down to metadata. The main purpose of SOAP (in case of document-style services) is to provide a place where to put message metadata. This place is SOAP header. WS-Security digital signature, WS-Addressing headers or application-specific metadata all belong there. Today, many (if not most) Web services implementations don’t use SOAP headers and so for these implementations SOAP is just overhead and added complexity (just try get direct access to the InputStream of the message payload in any JAX-RPC-compliant
implementaiton). Without anything in the header, SOAP does not have any advantage over good old XML over HTTP “post” (assuming that there is a schema for this XML).

One can argue that SOAP engines also provide XML mapping to the host language primitives, i.e., mapping to/from objects. I personally think that XML mapping capabilities must be de-coupled from SOAP processing. A good XML mapping framework should work with any XML source (in fact, this is exactly where JAX-WS, which is the next version of JAX-RPC is going). A developer must have a choice of receiving “raw” XML from SOAP engine or converting this XML into objects using a framework of his/her choice (e.g., what if I want to use Castor instead of JAXB), I really don’t understand why SOAP engine should make this choice for me.

Just to confirm my point that SOAP is not a requirement for a successful Web service implementation, here is the list of Internet heavyweights and their use of SOAP versus XML. Note that none of them (as far as I know) use WSDL HTTP binding, WSDL is only used when SOAP is used.

Of course, SOAP has some other benefits, such as solid tool support. SOAP also provides SOAP encoding (for RPC-style services), although the document style is quickly taking over. But is SOAP absolutely required to implement a “proper” Web service? I don’t think so.

I‘m currently using JWSPD to develop some prototypes and I thought it might be
useful to document a few things that are not immediately clear from the
documentation (at least, they were not to me).

Why use Sun’s
JWSDP (JAX-RPC Standard Implementation)?

• From my experience, it has better WSDL and document-style web services support
  than Axis. For example, you can read this
  article or my
  blog entry about the problems that Axis has with document/literal services (alhough
  these problems might be fixed in Axis2).
• It‘s a reference implementation which should have better JAX -RPC compliance.

On the downside, JWSDP is more difficult to use than Axis, you have to use “wscomplile“
and “wsdeploy“ tools and it takes some time to set it up.

First of all, you probably want to run JWSDP under the latest version of the
Jakarta/ Tomcat. JWSDP documentation says that it requires modified Tomcat 5.0
which you can download from Sun‘s website (or Sun‘s application server), but you
don‘t need it. From my experience, it works with jakarta-tomcat-5.5.9 just fine.
You just need to pull all JWSDP jars under “WEB-INF/lib”. Here is the list (I
may have some extras there, I did not try to figure out which ones are not
needed):

FastInfoset.jar
activation.jar
commons-beanutils.jar
commons-collections.jar
commons-digester.jar
commons-logging.jar
dom.jar
jaas.jar
jax-qname.jar
jaxb-api.jar
jaxb-impl.jar
jaxb-libs.jar
jaxb-xjc.jar
jaxp-api.jar
jaxrpc-api.jar
jaxrpc-impl.jar
jaxrpc-spi.jar
jsr173_api.jar
mail.jar
namespace.jar
saaj-api.jar
saaj-impl.jar
sjsxp.jar
xmlsec.jar
xsdlib.jar

You need to read this
article first to understand the difference between wrapped and unwrapped
mode.

I‘m assuming that you‘ll be generating Java classes from WSDL , not the other
way around.

• If you‘re implementing document/literal service with wrapper (JAX-RPC style):
  This is the default in JWSDP . From my experience, JWSDP uses this style even if
  operation name does not match the outer element name in the schema as prescribed
  by JAX -RPC.
• If you‘re implementing document/literal non-wrapper (WS-I style):

  You need to use “-f:wsi“ to switch to this mode. Note that in this case you must
  use model file (“-model“). Model file is used to pass the information to “wsdeploy“
  utility. “wsdeploy“ calls “wscompile“ under the covers, but you can‘t directly
  set “wscompile“ options on “wsdeploy“ command line. Model file is what‘s used to
  pass these options to “wsdeploy“. Also, don‘t forget to use “-f:wsi“ for the
  client‘s stub generation (“-gen:client”) option.

Finally, a sample build file is available here.

Tags: Web services, JAX-RPC, JWSDP, Sun