Why is Java Web Services so Hard?

This is an excerpt from my book: SOA Using Java Web Services.

If you are a Java developer building enterprise applications today, chances are you are looking at how to best use the Web Services standards built into Java EE 5 to create systems using Service-Oriented Architecture (SOA) principles. These standards include JAX-WS 2.0 (formerly JAX-RPC 1.1) [JSR 224], JAXB 2.0 [JSR 222], Web Services Metadata 2.0 (WS-Metadata) [JSR 181], and Web Services for Java EE 1.2 (WSEE) [JSR 109]. I call these standards, taken together, Java EE 5 Web Services (JavaEE5-WS).

SOA applications are constructed from loosely-coupled Web services. So, naturally, as Enterprise Java developers, we turn to the JavaEE5-WS specifications as our tools for creating SOA applications. Furthermore, the leading Enterprise Java vendors hold out JavaEE5-WS technologies as the development platform of choice for SOA applications.

So, the JavaEE5-WS standards are very important. They are the foundation for SOA. And loosely-coupled SOA applications are critical to corporate competitiveness because they enable business processes to be flexible and adapt to rapidly changing global markets.

Unfortunately, if you are like me, you have found JavaEE5-WS complex and difficult to work with. There often seems to be lots of complex machinery required just to deploy a Java class as a Web Service or create a simple client to consume such services. Sure, you can get the simple “Hello World” application from the Java EE 5 tutorial working. But when you need to deploy your purchase ordering system, things suddenly get a lot more complicated. Either the WSDL you start with gets compiled into a myriad of bizarre classes that have to be manually wrapped and mapped into your real purchasing system. Or, if you start from your Java classes, the WSDL that gets produced doesn’t turn out the way you need it to. If you have run into these problems, then I sympathize with you. So have I, and that is what motivated me to write this book.

Am I Stupid or is Java Web Services Really Hard?

At first, I just thought I was stupid. Prior to getting involved with Java Web Services, I had been running a consulting business. I figured that since I’d been a manager for the past several years, the technologist side of my brain had atrophied. “Keep working at it!”, I said to myself, “and you’ll master this stuff.”. That was 3 years ago, and I’m still struggling to figure out how to best make use of the Enterprise Java standards for Web Services.

During those past 3 years, I’ve mastered topics such as Java generics, reflection, and EJBs. I’ve studied the Apache Axis [AXIS, AXIS2] source code – and even submitted a few patches. I’ve convinced myself that I’m not stupid. Yet, I’m still struggling to develop an intuitive understanding of these complex standards. And I’m not alone.

Richard Monson-Haefel, a distinguished technologist, published a 960 page book on the J2EE 1.4 versions of these Java Web Services specifications in late 2003. 960 pages! That is all the evidence anybody needs to prove that this stuff really is complex. Its not that any one particular topic is all that difficult. Sure, it takes a little while to figure out what the JAX-WS API does – for example. But, the real difficulty is getting your mind around all these APIs and how they relate to the underlying Web Services standards (e.g., XML, WSDL, and SOAP), the HTTP protocol, and the other Java EE container services (e.g., dependency injection). This complexity can make working with the JavaEE5-WS standards feel awkward and unnatural.

During the past two years, there has been a growing chorus of leading technologists - Monson-Haefel among them - bashing the Enterprise Java Web Services standards. And I agree that it is very difficult to do useful SOA-style application development work with the J2EE 1.4 versions of the Java Web Services standards. But, I have trouble agreeing that the specifications themselves are the real problem. Instead, I suspect that the problem itself – creating a general purpose framework for Web Services development – is just plain complicated.

Richard Monson-Haefel posted this email on his blog on April 22, 2006. It summarizes pretty well how a lot of us feel after having spent a lot of time working on Java Web Services:

Dave Podnar’s 5 Stages of Dealing with Web Services

  1. Denial - It’s Simple Object Access Protocol, right?
  2. Over Involvement - OK, I’ll read the SOAP, WSDL, WS-I BP, JAX-RPC, SAAJ, JAX-P,… specs. next, I’ll check the Wiki and finally follow an example showing service and client sides.
  3. Anger - I can’t believe those #$%&*@s made it so difficult!
  4. Guilt - Everyone is using Web Services, it must be me, I must be missing something.
  5. Acceptance - It is what it is, Web Services aren’t simple or easy.

One thesis of this book, simply stated, is that Web Services are hard. We need to accept that fact and move on. Web Services are hard because they are a form of distributed computing and distributed computing is just about the hardest problem in computer science.

Don’t Drink That Kool-Aid

In early 2001, when Ariba, IBM, and Microsoft published WSDL 1.1 as a W3C Note, Web Services were envisioned as a way make distributed computing easier. No longer would developers need to understand CORBA to create cross-platform, distributed applications. Even better, Web Services were envisioned as a technology to make distributed computing over the Internet possible.

Like me, most Java developers bought into this early Web Services vision. It made sense given our experience with the Internet during the 1990s. HTML over HTTP had fueled the astonishing growth of the World Wide Web – a distributed computing platform for people. We believed that standards (like SOAP and WSDL) for XML over HTTP would fuel similar growth for Web Services – a distributed computing platform for business applications.

We all drank that Kool-Aid. We believed that Web Services would make distributed computing easy.

The leaders of the Enterprise Java industry set to work implementing the Web Services vision. Along the way to realizing this vision, the Java industry discovered that they had created some pretty daunting specifications. The people who read the JAX-WS, JAXB, and other Enterprise Java Web Services specifications – including myself – got alarmed. We figured that something must have gone wrong. We assumed that the Expert Groups leading these specifications had gotten off-track. We got disillusioned and bitter about the lost promise of Web Services. We started bickering amongst ourselves about SOAP vs. REST and who is to blame for the complexity of the Java Web Services specifications.

But the complexity problem doesn’t result of choosing the SOAP framework instead of REST. It’s not a result of over-engineering on the part of the Expert Groups. As the Expert Groups got down to brass tacks – trying to make the Web Services vision happen – they rediscovered that distributed computing really is a daunting challenge. SOAP, WSDL, XML, and even REST, are not going to make distributed computing easy.

Certainly the Enterprise Java specifications for Web Services are flawed. But that is to be expected – new technologies always come with mistakes (look at EJB). The mistakes get corrected and flushed out with subsequent versions [1].

As one example of how the Enterprise Java specifications have improved, consider JAX-WS 2.0. Chapters 6 and 7 describe that specification in detail, so for now, I’m just going to give a preview of why I think it’s such a big improvement over JAX-RPC 1.1. For starters, the JAX-RPC data binding has been removed and the specification has been simplified to focus entirely on the WSDL to Java mapping. The XML Schema to Java data binding from JAX-RPC has been eliminated and the data binding features in Java EE 5 are provided by JAXB 2.0. Second, JAX-WS lets you use annotations to control the shape of the WSDL generated from a Java interface. The use of annotations in this manner simplifies and in some cases eliminates the need for the deployment descriptors required to deploy a JAX-RPC service. Third, JAX-WS provides interfaces (Dispatch on the client side, and Provider on the server side) that enable programmers to directly access and work with XML – effectively bypassing the JAXB data binding when they don’t want to use it. For certain, JAX-WS 2.0 could still be improved greatly. The biggest improvement that I can think of would be to provide an alternative binding (in addition to JAXB) that lets the developer work directly the native XML types that are specified in a WSDL and its associated schema. Some type of XML extension to the Java like XJ [XJ] might do the job. Much of the complexity and confusion that developers experience when working with JAX-WS relates to the difficulty of determining how the JAX-WS / JAXB generated classes created by the JAX-WS WSDL compiler map to the XML messages specified in the WSDL. But, that is a whole research area (creating a language that makes it simple to program directly with native XML types) unto itself where we are all still waiting for some breakthroughs. My point here is not that JAX-WS is ideal, but simply that is has improved on JAX-RPC much as EJB 3.0 has improved on EJB 2.1.

To summarize, in the years since the WSDL specification came out, the Enterprise Java community has created from scratch a Java-centric platform for distributed computing based on Web Services technologies. This has been a Herculean task and it shouldn’t surprise anyone that the specifications are difficult to understand! Viewed from this perspective, the JavaEE5-WS standards are not bad at all. In fact, they are a huge step forward toward enabling Enterprise Java to become a SOA development platform. These standards give us the APIs that we need to wrestle with the complexities of Web Services development.

So why are we disillusioned? What lesson should we be learning as we wallow in our disillusionment? I think it is the same lesson that we learn over and over again in this business – “Don’t drink the Kool-Aid”! If we didn’t start out by assuming that Web Services was going to be a silver bullet for distributed computing, we wouldn’t be disillusioned. Instead, we would be optimistic.

Round Pegs and Square Holes - Application Frameworks vs. Toolsets

Realizing that Web Services are intrinsically difficult forced me to rethink my assumptions about the JavaEE5-WS specifications. I no longer believed that these specifications could be significantly simplified. I accepted their complexity as the natural expression of the complexity of the underlying distributed computing problem.

Instead of viewing JavaEE5-WS as an application framework for SOA-style development, I recognized it as a toolset for distributed computing. My problem had not been stupidity, but using the tools incorrectly. Trying to create SOA applications with the JavaEE5-WS technologies is like trying to pound a square peg in a round hole. JavaEE5-WS is not an application framework.

Application frameworks make programming easier by encouraging application development along the lines of a particular architecture. For example, the Apache Struts [STRUTS] framework encourages the applications based on the Model 2 or Model View Controller (MVC) framework. Frameworks offer a layer of abstraction on top of complex toolsets. The layer of abstraction encourages you to program in a certain way. By restricting your programming choices to a sub-set of proven patterns, the framework makes your job easier and less confusing.

Application frameworks can also encourage good design. For example, in Chapter 4, I discuss the use of centralized XML Schema libraries as a mechanism to promote separation of concerns. Such libraries separate the type definition process (a necessary part of creating SOA application with Web Services) from the interface definition process (i.e., creating WSDL representations of individual SOA components). A good SOA framework, therefore, should encourage the use of XML Schema libraries and promote the reuse of schema across WSDL documents.

Application frameworks employ toolsets, but they go beyond toolsets. They encourage a particular manner of using toolsets. Struts, for example, employs Servlets and JavaServer Pages (JSP) among other toolsets. On top of these toolsets, Struts provides a framework of classes (e.g., Action, ActionMapping) for building applications according to the MVC framework.

Thinking through the Struts analogy to Web Services, I realized that JavaEE5-WS provides a toolset but not an application framework. To develop SOA business applications, I really wanted an application framework like Struts - not just the underlying toolset.

Along these lines, I started to think that a useful SOA application framework could be created on a foundation analogous to the ActionMapping and Action classes from Struts. In Struts, an ActionMapping maps an HTTP request to an Action instance that encapsulates calls to the appropriate business logic and dispatches the response to the appropriate View. Likewise, I thought, a SOA application framework could have a customizable Controller layer that receives SOAP messages and dispatches them to the appropriate implementation class. In this approach, the WSDL representation can be thought of as the View (using the MVC analogy), and the Java classes that implement the WSDL are the Model. One current limitation with the JavaEE5-WS toolset that hampers the implementation of this approach is that this dispatching process (analogous to the Controller) is difficult, if not impossible, for the programmer to manipulate. That is because it is hard-wired to correspond to the WSDL to Java mapping defined by JAX-WS. What control the programmer has over dispatching comes through annotations which are embedded in the target Java classes themselves. The JavaEE5-WS design is analogous taking the ActionMapping (Controller) and embedding it in the business logic (Model).

Don’t worry if this analogy to Struts seems confusing at this point. Chapters 9 – 11 explore the concept of a Java application framework for SOA in detail. And you don’t have to be a Struts programmer to understand it. At this point, I just want to give you a flavor for where I’m headed with the application framework idea.

The good news is that, by implementing the JavaEE5-WS toolset, the Enterprise Java vendors have done a great deal of hard work that paves the way for the development of application frameworks for SOA. One just has to get a little clever to work around some of the JavasEE5-WS limitations when attempting to create a SOA application framework.


Understanding the need for SOA application frameworks built on top of the JavaEE5-WS toolset was my epiphany. Instead of trying to create SOA applications using JavaEE5-WS, I began to think about how to create an application framework for SOA.

The result is contained in the last three chapters of this book – an effort to show how application frameworks for SOA can be created using JavaEE5-WS.

Before discussing either the JavaEE5-WS toolset APIs, or how to implement a SOA application framework on top of it, I need to introduce some common terminology in order to discuss the different components of a platform, like Java EE 5 Web Services, or Apache Axis, that enables the development and deployment of Web services. I call such a system a Web Services platform. The next section introduces what I call the Web Services Platform Architecture (WSPA), which provides the common terminology that is used throughout this book for discussing Web Services platforms. Think of the WSPA as our reference architecture. As we discuss Java EE 5 Web Services, we will refer back to the WSPA to discuss its strengths and weaknesses.


[1] Note that EJB 3.0 continues to improve and implements advanced Aspect Oriented Programming and Inversion of Control features that its many detractors have been calling for.

6 Responses to “Why is Java Web Services so Hard?”

  1. SCJWSD says:

    Thank you for clearing my painful points about Java Web Services. It is not so easy like you said.

    I have been waited for Head First Java Web Services. Head First make my life easier. :)

  2. bv says:

    Headfirst is good to understand the concepts. i feel it has very limited details for day to day programming..

  3. Matt G. Madhavan says:

    Thank God! I am not stupid!

    Great article and summarizes all the pain, agony, self doubt, exhilarations etc I went through dealing with web-services over the years!


  4. Dhanalakshmi says:


    I would like to create a web application which has front end as JSP+ Struts framewrok and it should call a web service. But I am not able to call that webservice which I’ve created from the stub class into Action class.

    If you have any sample code with you please send it me either the link to download or send it to me my email Id as given

  5. Mark says:

    Try posting your question on one of the java.net forums related to JSPs or Web Services. See http://forums.java.net/jive/index.jspa

  6. Nick says:

    Microsoft’s Web Services on .NET is so easy to use? Is there are Koolaid factor here ?

    I would like to know if anyone here can contrast java vs microsoft web services.


Leave a Reply

You must be logged in to post a comment.