Page History

...

The original post is from Christian Schneider´s blog and can be found here

What we would like to have

Ideally I would imagine to have a domain specific language that makes designing the webservice very easy and fail safe. Then there should be an IDE that supports me in writing the DSL. Either with content assist or with a graphical editor. In any case the IDE should check the DSL while it is entered and help me to do the right thing. Some people favor using Model Driven Design tools to do this job but it is quite hard finding good tools and configuring them for the job.

Which tools did I choose and why

I wanted to go some way in the direction of a DSL for webservices but without using a big MDD tool. So I thought about how to have most advantages of a DSL with just Java and the normal Eclipse IDE. So I needed Java code that looks almost like a DSL and a tool to generate the webservice out of it. For the WSDl generation I used Apache CXF with JAXWS and JAXB annotations to describe the webservice. While this setup is quite standard I focused on keeping the syntax as simple as possible.

So how does the DSL look like

To describe a data object I use a java class with just attributes. The Namespace will come from the package name. To make JAXB understand this syntax only one annotation is necessary. Of course some more annotations are necessary if you want to use special fetaures.

Customer datatype

package com.example.customerservice;

@XmlAccessorType( XmlAccessType.FIELD )
public class Customer {
  String name;
  String[] address;
  int numOrders;
  double revenue;
  BigDecimal test;
  Date birthDate;
  CustomerType type;
}

...

package com.example.customerservice;

public enum CustomerType {
  PRIVATE, BUSINESS
}

Service definition

package com.example.customerservice;

@WebService
public interface CustomerService {
public Customer[] getCustomersByName(@WebParam(name="name") String name);
}

As you can see only two annotations are necessary here. @WebService marks the interface as a service and @Webparam is necessary as Java will else loose the name of the parameter and the wsdl will contain arg0 instead of the desired name.

How is the wsdl generated

To generate the wsdl the maven plugin cxf-java2ws-plugin is used. See the pom.xml in the complete example for details.

Let´s take a look at the resulting WSDL

You can download the wsdl this example creates here\.

...

The wsdl defines a SOAP/HTTP binding by default but can also be used to build services based on JMS as I will show in my next post.

Summary

As you can see the generated WSDL looks quite clean and correctly expresses the service interface we wanted to describe. In most cases where you are not satisfied with what the conversion does you can correct the WSDL using JAX-WS or JAXB annotations. But I recommend to use them sparsly to keep the DSL easy to read.

...