SOA / Web Services / Java

A Technology Blog

Posts Tagged ‘Web Services’

Developing web service – Top-Down vs Bottom-Up approach

Posted by Vivek on December 25, 2009

I have worked on or seen a lot of projects using web services and there are many projects that even if use a single web service are touted as a SOA based project. Also, if you look at their approach of developing web service, you will find that they had never gone through a service identification phase and that they could have done without using any webservice. Most of the developers are nowadays handed over an intelligent IDE like jdeveloper or RAD and it becomes very easy for them to write some java code and just right click on the service interface class and choose the option of “generate web service”. And it’s all done. They become web service developers. Do you really think it’s that easy :). Forget about web services, I have come across developers who have worked on one of the many ESBs in the market without having any knowledge of web service or principles of SOA and they call themselves Integration architect or EAI specialist. This post is for those who have used bottom-up approach or code-first approach of developing web service and do not understand the limitation of using it. This post is to highlight the advantages of using contract or WSDL first or top-down approach of developing a web services.

1. Almost all projects are business driven and not IT driven. This means that your business should be aligned with IT and your architecture should be agile enough to adapt to the ever-changing business requirements. Top-Down approach helps you do that. How? Imagine a web service developed using bottom-up approach. The WSDL generated will contain embedded schema often referred to as business object. So each time your business object changes, you will regenerate your WSDL. This also means that you will need to republish your WSDL to service registry and inform all consumers about the change. On the other hand, in a top-down approach you can import/include your business object and if the object changes WSDL will not undergo any change. Also, the business object or XSD can be used by many services and in such case it can be reused.

2. You can develop a service using any programming language like java, .net etc. Each language has its own datatype and when you generate a WSDL you ask the SOAP engine (that contains a binding mechanism) to perform serialization of data types and convert those data types to equivalent data types defined by an XSD. The basic mapping between Java and XSD, for instance, is defined by JAX-RPC specification. So it becomes necessary for a java developer to go through the specification to understand what data type is he/she going to advertise  to the client. Thers is another way that a developer can use if he/she insists to use a particluar java data type. In such cases, he/she needs to configure a bean and tell the binding mechanism (JAXB, xmlbeans etc.) which java class may to which XML schema type.  Each SOAP engine (Axis, CXF etc) comes with a binding mechanism inside and it is not possible to access the binding mechanism directly while generating WSDL. Also, most clients add their flavor to the SOAP engine and do not allow the developer to customize the binding framework.

3.  It is difficult to enforce restrictions in code and then generate WSDL. For instance, If the WSDL/XSD requires that an object can be nillable, then the developer may need to replace the primitive data types with their wrapper classes and regenerate the WSDL. Some developers use array in their code and when they generate WSDL it defines the datatype as arrayOfStrings. This is strictly discouraged by the WS-I basic profile as it causes interoperability issues. Remember, consumer of a web service can generate client in any language and he should have that freedom. You cannot use features that are not compliant with WS-I basic profile. There are various tools in market that allow you to check if your WSDL is WS-I BP conformant and it is very helpful for any developer who uses contract first approach. Obviously, you may not want to keep changing you code until it generates a WSDL that is WS-I BP conformant.

4. If your project is a typical SOA project then you must be using a service registry/repository to provide SOA governance. As everyone knows a registry stores metadata about the service and is a catalog of services, it should contain a lot of intricate details (version, milestones, creat date, expiration date etc) about any service. The service registry inherits a lot of information from your WSDL which means that the WSDL should be descriptive and should not require administrator to enter details manually in registry or should not require client to access registry for details that can be documented in a WSDL. The documentation element of a WSDL is an important place holder for such information but most of the tools do not generate documetation element inside WSDL.    

5. There are lot of web services standards and incorporating these standards means the SOAP header will contain extra information. Hoever, a code first approach nowadays has support of annotations to specify header details in WSDL (when generated), it is always a better idea to use contract first approach to specify the header information. The web service client should know what it is going to receive in the SOAP header.

Posted in Web Services | Tagged: , , | 37 Comments »

Parse WSDL effectively

Posted by Vivek on February 4, 2009

As a WSDL’s constituents are well-defined already, it is feasible to use a parser that can get the elements of the WSDL using APIs that are already defined. This will minimize complexity in the code and will help in achieving better performance.


Oracle WSDL parser is one such option.


It is only needed to import the necessary classes as the APIs are already defined and packaged with wsdl.jar.


//importing the necessary classes from library

import oracle.wsdl.WSDLDocument;

import oracle.wsdl.internal.Binding;

import oracle.wsdl.internal.Definitions;

import oracle.wsdl.internal.Documentation;

import oracle.wsdl.internal.Import;

import oracle.wsdl.internal.Message;

import oracle.wsdl.internal.PortType;




WSDLDocument wsdldoc = new WSDLDocument(wsdl_url);

//getting definition element

Definitions definition = wsdldoc.getDefinitions();

//getting service element

Map servicesMap = definition.getServices();

//getting binding element

Map bindingsMap = definition.getBindings();

//getting PortType element

Map ptypesMap = definition.getPortTypes();

//getting message element

Map messagesMap = definition.getMessages();

//getting import details

Map importsMap = definition.getImports();

//getting documentation details

Documentation docs = definition.getDocumentation();



As there can be multiple elements, an “iterator” can be used to parse an individual element.

For Example:


Iterator iterator = servicesMap.entrySet().iterator();

        while (iterator.hasNext()) {

            Map.Entry me = (Map.Entry);




The above code fragments keep things fairly simple while processing a WSDL.


Apache Woden


Woden provides Java class library for reading, manipulating, creating and writing WSDL documents.


Woden’s DOM-based XML parsing depends on Apache Xerces 2.7.1. Its XML Schema support it depends on the schema parser and object model implemented by the Apache Web Services Commons (ws-commons) XmlSchema project.


//importing necessary classes from woden jars

import org.apache.woden.WSDLException;

import org.apache.woden.WSDLFactory;

import org.apache.woden.WSDLReader;

import org.apache.woden.wsdl20.Binding;

import org.apache.woden.wsdl20.Description;

import org.apache.woden.wsdl20.Interface;

import org.apache.woden.wsdl20.Service;





WSDLFactory factory = WSDLFactory.newInstance();

WSDLReader reader = factory.newWSDLReader();

reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);

String wsdlurl = “C://axis2-1.4.1//newwsdl.wsdl”;


//reading the WSDL Document

DescriptionElement descElem = (DescriptionElement) reader.readWSDL(wsdlurl);

Description descComp = descElem.toComponent();


//getting Interface, Binding and Service elements

InterfaceElement[] interfaces = descElem.getInterfaceElements();

BindingElement[] bindings = descElem.getBindingElements();

ServiceElement[] services = descElem.getServiceElements();



Complete details about usage and extensibility of woden are available at:





JWSDL is another option that is intended for use by developers of Web services tools and others who need to utilize WSDL documents in Java.

JWSDL is designed to allow users to read, modify, write, create and re-organize WSDL documents in memory. JWSDL is not designed to validate WSDL documents beyond syntactic validity. One use of JWSDL is to develop a tool that validates WSDL semantically.

JWSDL is designed for use in WSDL editors and tools where a partial, incomplete or incorrect WSDL document may require representation.


Details of JWSDL can be obtained by accessing the following link:

Posted in Java/J2EE, Web Services | Tagged: , , | 5 Comments »

Preserve white spaces in a SOAP message

Posted by Vivek on January 30, 2009

Sometimes, the business requirement mandates that a SOAP request/response should maintain leading or trailing spaces that are present in a variable. By default, this does not happen. For example, you may expect ” ABC” or “ABC “, but you get “ABC”. The spaces are removed. Also, you may encounter issues if you use a binding mechanism like JAXB to marshal/ unmarshal xml fragments.  This requires modifying the default marshalling or unmarshalling behavior. This is how you can still maintain any whitespaces:

Before marshalling call

marshaller.setPropertyMarshaller.JAXB_ENCODING, “UTF-8”)

 which informs MarshallerImpl#createWriter(…) to create a UTF8XmlOutput instead of SAXOutput. 

UTF8XmlOutput escapes line-break into “ ”, which will be preserved when unmarshalling is performed by any xml parser.

Posted in Web Services | Tagged: , , | Leave a Comment »

RPC-style vs Document-Style Web Service

Posted by Vivek on September 12, 2008

There has been lot of confusion on which style of web service is used but It is always recommended to use a Document-style webservice to realize SOA.

RPC style web service:
These web services are easier to create and are usually synchronous in nature.
The responsibility of marshalling and de marshalling lays with SOAP engine, This leads to significant performance degradations when message passed to an operation is large or complex.
Since large sized messages lead to performance degradation in RPC style web service, they are not suitable for implementing coarse grained functionality requiring information messages having more number of fields.
However fine grained functionalities is better implemented by RPC style web services.
Document style web service:
Document style web services are more time consuming to create, as it is the onus of the service to create the required objects from XML document.
These web services can consume large sized documents without any significant drop in performance as there are no overheads of marshalling and de marshalling associated with SOAP engine.
Document style web services are ideal for representing coarse rained functionality as a single large sized  document can be used to transfer information required to implement a business functionality.
Document style web service are primarily used for implementing asynchronous service.

RPC encoded web services are easiest  create but offers least control in terms of usage of custom data types, validation and interoperability.
RPC encoded web service are slower in performance because of added overheads of marshalling and un marshalling.
Document literal web services are harder to create but scores higher in all the above metrics and this is one of the reasons WS –I basic profile encourages the usage of document literal web services.

Document style web services are better suited for defining custom data types as they are not constrained by the usage of a particular encoding style. Document –literal web services offers the best performance and RPC –encoded web services offers the least performance as in document-literal web service overheads of marshalling and un marshalling no longer lies with SOAP engine. In a document –literal web service alternative techniques such as  SAX based parsing or custom data binding tool like XML beans, castor can be used.In case SOAP engine does not maintain state a document –literal web service can be used to carry state related data in the document. While using RPC –encoded web service often platform specific data structures are exposed in WSDL, which might not be supported by other platforms.

Posted in Web Services | Tagged: , , , , , | 10 Comments »

SOA Governance

Posted by Vivek on August 23, 2008

Any organization willing to implement SOA should already have a plan for its governance. Most people think that SOA Governance is optional and it’s not true. Without SOA Governance it is impossible to reap the true benefits of a full-fledged SOA. Some benefits that are directly related to success of any organization.

With the widespread adoption of SOA, the challenges associated with SOA projects are emerging. SOA governance isnt optional its imperative. Without it, return on investment will be low and every SOA project out of pilot phase will be at risk.
                                                        Paolo Malinverno
                                                           Gartner, Inc.1

Failure to provide effective SOA governance exposes your organization to serious risks:
• Insufficient knowledge of available services
• General failure to reuse services
• Unnecessary, uncontrolled service duplication
• Resources wasted on services that can’t be reused
• Service sprawl across siloed SOAs
• Ineffective communication of best practices.


A good blog on SOA Governance:

Posted in SOA Governance | Tagged: , | Leave a Comment »

Defining SOA

Posted by Vivek on August 23, 2008

If you ask 5 different people definition of the buzzword “SOA”, they all will come with a different answers. SOA is not something that can be defined in two or three lines. 

“SOA is the architectural style that supports loosely coupled services to enable business flexibility in an interoperable, technology-agnostic manner. SOA consists of a composite set of business-aligned services that support a flexible and dynamically re-configurable end-to-end business processes realization using interface-based service descriptions.”

To be more precise, any SOA must exhibit the following features:

Loose coupling – Services maintain a relationship that minimizes dependencies and only requires that they retain an awareness of each other.

Service contract – Services adhere to a communications agreement, as defined collectively by one or more service descriptions and related documents.

Autonomy – Services have control over the logic they encapsulate.

Abstraction – Beyond what is described in the service contract, services hide logic from the outside world.

Reusability – Logic is divided into services with the intention of promoting reuse.

Composability – Collections of services can be coordinated and assembled to form composite services.

Statelessness – Services minimize retaining information specific to an activity.

Discoverability – Services are designed to be outwardly descriptive so that they can be found and assessed via available discovery mechanisms.

This is important when the following objectives are to be achieved:

• Reducing overall total cost of ownership (TCO)
• Improving time to market
• Achieving business agility
• Fostering innovation
• Enabling compliance
• Improving the top and / or bottom line
• Increasing customer satisfaction and retention
• Global expansion

Posted in SOA | Tagged: , | Leave a Comment »

SOA Best Practices

Posted by Vivek on August 9, 2008

Hundreds of Organizations are trying to demystify SOA and each wants to win the race by providing the best possible solution even if the infrastructure becomes heavy in the process.

Here is a good link which clears the air to a large extent:

Oracle’s breed of products in making SOA a reality are unmatchable:

Posted in SOA | Tagged: , , | Leave a Comment »