O'Reilly logo

Java SOA Cookbook by Eben Hewitt

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Supporting Your SOA Efforts


You want to develop a set of guidelines and principles for designing and implementing your service-oriented architecture. It should not only record the decisions you make but also serve as an educational tool for others in your organization.


Create a reference architecture, which is a representation of your real-world implementation. Internally, you can build on this to include a collection of roadmaps, conceptual blueprints, guiding principles, and standards and conventions that will serve as the foundation of your service-oriented architecture. If you have established a Center of Excellence (CoE) or SOA Team (which is a very good idea), they will be the custodians of these resources, and will likely be responsible for sharing them with the larger development teams for educational purposes.

You could use your reference architecture documents as the cornerstone for an online resource to aid in the education of others. This could be an internal website, wiki, or portal that establishes a single entry point into your architectural blueprints and other supporting resources.


In April of 2008, OASIS published a document it called the “Reference Architecture for Service Oriented Architecture Version 1.0.” You can read the PDF at http://docs.oasis-open.org/soa-rm/soa-ra/v1.0/soa-ra-pr-01.pdf. It is written for enterprise architects, and covers governance, social structures, service modeling and ownership, security, and more. It’s very abstract, but worth a read. You will find many such documents online that you might want to screen and contextualize for your internal use.


A reference architecture (RA), as defined within the Rational Unified Process, is a predefined set of architectural patterns, designed and proven for use in particular business and technical contexts, together with supporting documents that enable their use. These can grow organically from architectural documents, standards, and conventions you have in place already. But it is useful to tailor them for SOA as appropriate.

A reference architecture serves as a blueprint across multiple projects or within a single project. Architects and developers can verify that a subsequent implementation adheres to established guidelines and will have increased likelihood of meeting business goals.


You can think of the reference architecture as being analogous to the United States Constitution. It serves to establish a variety of abstract bodies, such as the three branches of government, each of which has different responsibilities, as well as a set of revisable guidelines that ensures that people operate according to principles that support the overarching goals of the republic. (Of course, all analogies have limited usefulness and can be misleading. Your mileage may vary!)

Aims of the reference architecture

The reference architecture can help ensure the success of your architectural efforts in a variety of ways:

Act as a blueprint

The reference architecture can capture the intersection between your IT infrastructure, your code, and your models. Because these different aspects are implemented by different teams, they can inadvertently act in isolation, rendering the enterprise unable to take advantage of a potential wealth of existing work.

The blueprint can assist solutions architects to view the SOA not only from a coding or system perspective, but rather to take the more holistic view required to ensure quality-of-service levels.

Your SOA reference architecture might link to other existing enterprise architecture documents, such as network and hardware IT infrastructure, and add to this the idea of service layers. For example, within Oracle/BEA, it defines an SOA RA containing the following service layers:

Data Services and Connectivity Services

These provide flexible access to underlying data tiers and enterprise applications.

Business-Oriented Services

A logical layer above Data Services where business processes are conducted.

Presentation Services

Package business capability services, repurposed for a variety of channels.

While Oracle/BEA’s list may not be the one you choose (you might collapse Data and Connectivity Services and you might throw out Presentation Services altogether, or add another layer of your own), the point is that it is useful to conceptualize your services on this level, and not simply on the level of Entity, Process, or Functional, as these are complementary classifications.

Promote best practices

The RA can declare that services and clients must be created and consumed following certain guidelines. Perhaps there are design patterns that you want consistently implemented in certain situations. Perhaps you want to require a set of acceptable methods for service creation, messaging, encoding, and so forth.

By declaring guidelines, standards, and conventions, the RA will help to ensure consistency across the board in service implementation. Architects have an easier task in enforcing the guidelines when they are spelled out clearly in a living public document. Once everyone is used to consistently implementing services in a given manner, this will mean quicker time to market. Developers can create new assemblies with confidence that the services they are reusing will fit well together.

The RA should address how to deal with cross-cutting concerns such as security and rules engines, which are sometimes themselves implemented as services.

Clarify trade-offs

You cannot do everything. Certain requirements are always at odds with each other. Reconciling terrific performance with strong security is a continual struggle.

Enable governance

The governance of your SOA is highly dependent on the creation of an RA. The RA serves as a constitution of sorts for your SOA Center of Excellence or governance board to follow.

Reference architecture site

Your SOA reference architecture can be a deliverable, a living set of resources that can be used for a variety of purposes, and not simply some documentation that accompanies your code. As a deliverable in its own right, it works well when implemented within a website that is easy to update, such as a wiki. Members of the SOA team or governance board or the architects involved at your organization can create a site that they populate with architectural models, standards and conventions documents, and resources for evangelizing and education, and that can perhaps serve as a gateway to runtime tools.


The size and shape of your RA site will be dictated by the size, organization, and distribution of your development teams.

As a suggestion, the items outlined in the following sections might be useful within a reference architecture.


Conventions enable clearer communication. They are a matter of subjective taste initially, but once established, they must be followed to make things easier to find and understand. Here are some examples of conventions you might consider creating guidelines for:

  • Document names, including schemas, WSDLs, and binding customization files

  • File locations and physical project structure of service implementation projects


These are more strict than guidelines, and are less a matter of taste. They have a functional purpose, such that if the standards are not followed, degraded performance or functional side effects can occur.


If you are unfamiliar with WSDLs or Schema design patterns, consult Chapter 2.

It can be useful to standardize the following:

  • Allowing use of binding customization files, such as for JAXB or JAX-WS (see Chapter 3)

  • Whether customizations are allowed, inline or external (see Chapter 3)

  • Importing WSDL bindings versus defining them inline

  • Importing schema types in WSDL versus defining them inline

  • Default protocol choice, and when other protocols are acceptable

  • Choosing which “start from” method (see Chapter 2)

  • Appropriate use of schema design patterns (see Chapter 2)

  • Using interfaces

  • Using optimization methods, such as FastInfoset and MTOM/XOP

  • Using headers

  • Using attachments

  • If using SOAP, to dictate acceptable style, use, and parameter style values, such as document/literal wrapped

  • Using one-way methods

  • Using asynchronous clients

  • Encoding for binary data

  • Centralized schema

These guidelines should ideally include examples of correct and incorrect use of each item.

There are many more items to consider depending on your implementation choices, system maturity level, and environment. While the focus of this book is on Java, you might need to determine standards relating to service creation in RPG, .NET, or what have you. This list indicates the appropriate scope of guidelines for your service implementations and SOA. Failure to adhere to such guidelines can cause interoperability problems and severe performance degradation, and can waste development time.


Keep your standards up-to-date. Make sure to include your team members in determining guidelines. Receive their feedback openly and incorporate their suggestions as appropriate. Create new items, drop old or obvious ones, and make updates as necessary to ensure that the guidelines are fresh, relevant, and useful.


There are dozens of specifications that can come into play very quickly in the world of SOA and Java-based web services. Linking to the specifications can help ensure that everyone can quickly find the definitive answer to a question, and it helps implicitly direct people to what they must understand to be productive within the SOA environment. Relevant Java specifications might include the following:

  • JAX-WS

  • JAXB

  • SAAJ

  • JAXR

  • Web Services

  • WS-Annotations

  • DOM, SAX, StAX

These are only the Java-specific specs. Important SOAP and WS-* specs, some of which we will examine in detail later on, include the following:

  • XML Schema

  • XSLT

  • SOAP

  • WSDL


  • WS-Policy

  • BPEL

  • WS-Security

  • WS-Trust

  • WS-ReliableMessaging

  • WS-Transaction

  • WS-MetadataExchange

Centralized bookmarks

Create a wiki page that encourages developers to bookmark web resources publicly so that it’s easy for everyone to find and use them. Invite others to participate.

Industry standards

In addition to the various specifications you will be using, include links to a set of industry standards that everyone would benefit from knowing. These might include:

  • Basic Profile 1.1

  • OASIS XML Catalog

  • W3C Web Services Architecture

  • OASIS Web Services Implementation Methodology

This is where you should indicate what BP 1.1 guidelines you are following, or state your position on them. Define a set of best practices for your organization based on accepted industry best practices, and incorporate them into your design. Some of these can be elicited from standards such as the WS-I Basic Profile. For example, the BP 1.1 requires that WSDLs use a target namespace. Use this opportunity to explicitly state such conventions so that other developers in your organization can quickly adhere to them.


Create one section of the site devoted to security. This is a large and complex topic in the world of web services, and there are many standards that make this work. Vendors are at different stages of implementation with respect to these standards, and it could be very useful to sort this out for your team. Finally, these guidelines can be important for ensuring interoperability, and can indicate items such as:

  • Use of particular cipher suites

  • Use of digital signatures

  • Transport layer security

  • Authentication methods

As your SOA grows, it will be useful to have an aggregate list of roles allowed within each service, as this will help organize process orchestration efforts.


Depending on your team’s level of experience, you might include working examples of code that illustrate how to create services and the attendant assemblies.


Consider establishing your architecture concurrently alongside your pilot projects. Developing an architecture entirely up-front without really seeing how the tools work together and how the standards are implemented can have a devastating effect on your deadline and ultimately your product. This is particularly true when you’re in a learning stage, such as during pilots. Make a general plan with the understanding that you probably won’t stick to it. Do a little and then revise your plan. Architectures can be agile too, and don’t have to be complete to get people working in the right direction. You can also, as Frederick Brooks wrote, “Make one to throw away.”


Consider creating a list of important terms and their agreed-upon definitions that you will go by so that they are clear in your team’s mind. Some concepts within SOA are contentious, vague, or hype-laden, which can make it difficult to know that everyone is actually talking about the same thing. Using a glossary for terms, such as service, contract, governance, and so forth, can aid meaningful communication.


Here you can link to JavaDoc, project documentation, vendor documentation, requirements, use case documents, modeling analysis documents, and other such items.

If you have IT or business roadmaps or other enterprise architecture documents that might play a role in building out your SOA, you can link to them here as well.


If your infrastructure allows it, you might consider having a view into the runtime artifacts within your SOA. These might include centralized schemas, business process modeling documents as derived from a modeling tool, visual representations of BPEL orchestrations, and other items. Offer appropriate users insight into monitoring tools so that they have the information necessary to make good decisions about new service candidates, SLAs, new compositions, or infrastructure changes.


You might consider establishing a feed that aggregates various SOA-related websites into your reference architecture portal. This helps to keep everyone abreast of industry trends and give your team the best chance to keep one another informed.


While some of the items indicated here may seem excessive, remember that the purpose of the reference architecture is manifold: it serves to instruct newcomers on the way that you want web services done in your organization; it helps experienced developers find and use web services that your organization has written or endorsed; and it helps the governance board or Center of Excellence make decisions regarding service candidates and future architectural directions.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required