Code First or Contract First with WSO2 Web Services Application Server?

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Isuru Suriarachchi
  • 20 Jan, 2010

“Code First or Contract First?”. This has been a hot topic in the Web services world for many years among the Web service developers. Some developers argue that the Contract First approach is the best and some others argue that the Code First approach is the best when it comes to developing Web services. Isuru Suriarachchi, Senior Software Engineer at WSO2, helps you to understand the importance of selecting the best suited Web service development patterns (Code First or Contract First) according to your application and its requirements.

Abstract

If you have developed a Web service using WSO2 Web Services Application Server (WSO2 WSAS) or hoping to do so, this article will help you to understand the most suitable approach to follow Web service development patterns, Code First and Contract First. And also you will realize the importance of selecting the best suited approach according to your application and requirements.

Table of Contents

Introduction

When it comes to developing Web services, there are two main approaches: “Code First” and “Contract First”. “Code First or Contract First?”. This has been a hot topic in the Web services world for many years among the Web service developers. Some developers argue that the Contract First approach is the best and some others argue that the Code First approach is the best when it comes to developing Web services.

Web Services Description Language (WSDL) [1] is used to define a contract between a Web service and a client who is consuming the service. This contract acts as an agreement on all aspects of a Web service. So in the Contract First approach, the service provider defines the WSDL document first and develops the service according to it and publishes the WSDL after deploying the service inside a Web service engine. But in the Code First approach, Web service developer writes his business logic first and deploys it as a Web service inside a Web service engine. The engine generates the WSDL for the developer who finally publishes the generated WSDL.

The core responsibility of a Web service engine is to support deployment of Web services. All well known Web service engines support both Contract First and Code First approaches. In order to support the above 2 approches, there are WSDL to code and code to WSDL tools which comes with such Web service engines. If the developer is trying to use the Code First approach, he just has to write his code and deploy in the engine which internally generates the WSDL. Even if the developer is using the Contract First approach, he can use a WSDL to code tool to generate the skeleton of the service. Then he can fill up the business logic and deploy the service with the WSDL.

WSO2 Web Services Application Server (WSO2 WSAS) [2] is one such well known Web service engine, using which you can develop your services easily. WSO2 Web Services Application Server (WSO2 WSAS) supports deployment of many different service types. Through those, WSO2 Web Services Application Server (WSO2 WSAS) supports both Code First and Contract First approaches in many ways. It is extremely important to have a knowledge on these approaches if you are developing long running business applications. Here, I'm going to discuss the topic “Contract First or Code First”, in the context of WSO2 Web Services Application Server (WSO2 WSAS) 3.x.

Code First Approach

In the Code First approach, development of the service is started from a code. So the developer can write a service without knowing anything about WSDL. When it comes to WSO2 Web Services Application Server (WSO2 WSAS), what he has to do is to write his business logic as a set of java classes and deploy it in WSO2 Web Services Application Server (WSO2 WSAS). WSO2 Web Services Application Server (WSO2 WSAS) will generate the WSDL file and make his code a Web service.

There are four simple mechanisms in WSO2 Web Services Application Server (WSO2 WSAS) to support Code First approach. In all these mechanisms, WSDL is generated by WSO2 Web Services Application Server (WSO2 WSAS).

  1. POJO services – Converts a single Java class (without packages) into a Web service

  2. Jar Services – Converts a set of Java classes (packaged as a Jar) into one or more Web services

  3. AAR Code First Services – Converts a set of Java classes with a services.xml file into one or more Web services. In this case, you don't have to include a WSDL file in the AAR archive.

  4. Spring Services – Converts Spring beans into Web services

  5. EJB Services – Converts Enterprise Java Beans (EJBs) into Web services

  6. JAX-WS Code First services – Converts a set of annotated (JAX-WS 2.0 [3]) Java classes into a Web Service. 

The Code First approach is simple, less time consuming and easy to use for people who are not familiar with Web services standards because WSDL is somewhat hard to understand and use for a beginner. And also, Code First is a good approach to convert a legacy code into a Web service. Jar Service and AAR Services in WSO2 Web Services Application Server (WSO2 WSAS) can be used for such purposes.

But this approach provides less control over the service contract as the WSDL is generated by WSO2 Web Services Application Server (WSO2 WSAS). If someone changes the service code, WSDL will be changed accordingly. And also the generated WSDL can have minor differences in different versions of WSO2 Web Services Application Server (WSO2 WSAS). Normally a WSDL definition is a contract between the service provider and the client. Therefore, such time to time changes in the WSDL should not be allowed. In addition to that, performance of Code First services are less in WSO2 Web Services Application Server (WSO2 WSAS) compared to Contract First services. This also becomes a disadvantage if the application is performance critical.

Contract First Approach

In the Contract First approach, development of the service is started from a WSDL definition, which becomes a contract between the service provider and the client. In this approach, WSDL definition is defined using Web services standards and the service implementation is done after that according to this contract. However, as mentioned in the introduction, manually implementing the service according to a WSDL definition is not very easy and it's time consuming. Therefore, WSO2 Web Services Application Server (WSO2 WSAS) provides the WSDL2Java tool which can generate the service code. So what you have to do is to generate server side code and fill the business logic and deploy the service. If you are using Contract First JAX-WS services, you can generate code using wsimport tool which comes with JDK.

There are two simple mechanisms in WSO2 Web Services Application Server (WSO2 WSAS) to support Contract First approch.

  1. AAR Contract First Services – Here you can have your service classes, WSDL file, services.xml file and custom Message Receivers in the AAR archive.

  2. JAX-WS Contract First Services – Here you can have your annotated service classes and the WSDL file in the Jar archive.

Contract First approach is more complex compared to Code First approach. And also it requires an in depth understanding of Web services standards. But it is the recommended approach in the Web services world. In this approach, the contract between the service provider and the client is kept constant. Therefore even if the business logic of the service implementation changes, it doesn't affect the client. Most importantly, Contract First approach can provide better performance in the context of WSO2 Web Services Application Server (WSO2 WSAS). When you generate code for your WSDL document, you can specify the appropriate data binding framework which suites your application. And also WSO2 Web Services Application Server (WSO2 WSAS) code generator can generate a custom Message Receiver for you and it helps a lot to improve performance of your service. In simple terms, the service is optimized according to the WSDL.

Code First or Contract First?

Now we know about both approaches and how to use both approaches in WSO2 Web Services Application Server (WSO2 WSAS). So which approach is the best? The answer depends on the service developer's requirement. When it comes to testing purposes or converting legacy code into Web services, Code First approach is far more convenient. But for a long running, performance critical business application, Contract First approach can be highly recommended.

Even if you are not familiar with Web services standards, still there is a way to achieve the advantages of Contract First development using WSO2 Web Services Application Server (WSO2 WSAS). In that case, you can initially write the service in the Code First manner and get the generated WSDL contract from WSO2 Web Services Application Server (WSO2 WSAS). You can use the Java2WSDL tool which comes with WSO2 Web Services Application Server (WSO2 WSAS) to generate the WSDL. Then if you want, you can modify the generated WSDL according to your requirements. Now you have the contract. Therefore, this contract can be used to generate code and create a service using the Contract First approach.

Finally, I can summarize the advantages and disadvantages of Code First and Contract First approaches as follows. Please note that, as I mentioned above, this is in the context of WSO2 Web Services Application Server (WSO2 WSAS). But some points applies generally as well.

Code First

Advantages
Easy to use
Simple and less time consuming
No need of in-depth knowledge on WSDL
Useful at development stage
Can be used to make Web services out of legacy systems
Disadvantages
Less performance
Can't guarantee the integrity of the WSDL

Contract First

Advantages
Can achieve better performance
Integrity of the WSDL is assured
Useful for long running business critical service development
Disadvantages
Complex than Code First
Need a better understanding on WSDL

Conclusion

In this article, first we discussed the background of Code First and Contract First approaches. Then we went through the mechanisms supported by WSO2 Web Services Application Server (WSO2 WSAS) for both approaches and their pros and cons. Finally, we discussed how to select the better approach accordingly.

When it comes to developing Web services, it is always better to consider the requirements and select the approach which suites the best. This will always allow you to find the best solution for the existing problem. Specially, if the services you are developing is business critical and log running ones, it is almost a must to take the best approach to gain the maximum outcome.

References

[1] WSLD 1.1 Specification
[2] WSO2 Web Services Application Server (WSO2 WSAS)
[3] JAX-WS 2.0 Specification 

Author 

Isuru Suriarachchi, Senior Software Engineer, WSO2, isuru AT wso2 DOT com

 

About Author

  • Isuru Suriarachchi
  • Technical Lead and Product Manager
  • WSO2 Inc.