As the debate regarding the right way to service contract design has increased as can be seen from here, and here, I wanted to reiterate some of the points I made earlier regarding the same. When designing a Service Contract, you can take two major approaches - well three (if you factor in the Meet-in-the-Middle case) but in reality that is a mix of the other two. The approaches as I have already mentioned in a previous blog entry are:

• Implementation-first development (a.k.a. Bottom-up)
  
• Contract-first development (a.k.a. Design by Contract, a.k.a. Top-Down)

As I have already mentioned, the preferred approach to Service Contract Design is the Top-Down approach, namely Contract-First Development.

You should avoid the Bottom-up approach, namely Implementation-First Development as much as possible. Granted that an Implementation-First approach allows the developer to write a lot of code that we developers are fond of writing, and tools like the NetBeans SOA pack can generate WSDL and XSD from the implemented classes. There are a lot of issues with the Implementation-First approach, but I will re-iterate a couple of them in this blog entry once again:

1. With the Implementation-First style, it is possible that programming language specific styles, idioms, and implementation details may unintentionally creep into the service contract.
2. This will make it extremely difficult for the consumer of the service - especially if the consumer is being implemented using a different programming language than the provider.

Therefore, try to avoid Implementation-First Development as much as possible. However, if you do have to do Implementation-First Development, you have to pay special attention to the following points:

1. Only use Java data types that can be expressed unambiguously through an XML-Schema. This ensures that the data can be marshaled and unmarshaled in a platform and programming language-neutral manner for attributes, operation parameters and return types.
2. Extensible type mapping should be avoided as much as possible. Keep in mind that extensible type mappings are not standard
3. If you have a choice between using standard Java type arrays prefer them to using say an ArrayList or a Collection
   

 Moreover, when exposing the Interface Endpoint, you have a couple of choices to make. Your service endpoint can be exposed as:

1. Service Endpoint exposed from an EJB WebService
2. Service Endpoint  exposed from a Web Application

Service Endpoint exposed from an EJB WebService

In this approach, the service is generally implemented as a Stateless EJB SessionBean and therefore, multi-threaded access is handled by the EJB Container. Also, since the service interface is exposed through an EJB, the service runs in the transactional context of the EJB container. This has many advantages for example, for one, it allows you to declaratively demarcate transactions.

Service Endpoint  exposed from a Web Application

In this approach, the service is generally implemented as a servlet, and therefore, the service has to handle concurrent client access on its own. Since the service implementation is done through a servlet, the transactional context is unspecified. For the same reason, you do not have any declarative means to start a transaction.

Please be aware of these when designing your service contract.

Like this write-up? Subscribe to receive  more  like it.