Tutorial using Axis 1.4 with Apache Camel
This tutorial uses Maven 2 to setup the Camel project and for dependencies for artifacts.
This sample is distributed with the Camel 1.5 distribution as
Apache Axis is/was widely used as a webservice framework. So in line with some of the other tutorials to demonstrate how Camel is not an invasive framework but is flexible and integrates well with existing solution.
We have an existing solution that exposes a webservice using Axis 1.4 deployed as web applications. This is a common solution. We use contract first so we have Axis generated source code from an existing wsdl file. Then we show how we introduce Spring and Camel to integrate with Axis.
This tutorial uses the following frameworks:
Setting up the project to run Axis
This first part is about getting the project up to speed with Axis. We are not touching Camel or Spring at this time.
Axis dependencies is available for maven 2 so we configure our pom.xml as:
Then we need to configure maven to use Java 1.5 and the Axis maven plugin that generates the source code based on the wsdl file:
We use the same .wsdl file as the Tutorial-Example-ReportIncident and copy it to
Okay we are now setup for the contract first development and can generate the source file. For now we are still only using standard Axis and not Spring nor Camel. We still need to setup Axis as a web application so we configure the web.xml in
The web.xml just registers Axis servlet that is handling the incoming web requests to its servlet mapping. We still need to configure Axis itself and this is done using its special configuration file
The tool will generate the source code based on the wsdl and save the files to the following folder:
This is standard Axis and so far no Camel or Spring has been touched. To implement our webservice we will add our code, so we create a new class
Now we need to configure Axis itself and this is done using its
The globalConfiguration and transport is not in the deploy.wsdd file so you gotta write that yourself. The service is a 100% copy from deploy.wsdd. Axis has more configuration to it than shown here, but then you should check the Axis documentation.
What we need to do now is important, as we need to modify the above configuration to use our webservice class than the default one, so we change the classname parameter to our class AxisReportIncidentService:
Running the Example
Now we are ready to run our example for the first time, so we use Jetty as the quick web container using its maven command:
Then we can hit the web browser and enter this URL:
Clicking on the .wsdl link shows the wsdl file, but what. It's an auto generated one and not our original .wsdl file. So we need to fix this ASAP and this is done by configuring Axis in the server-config.wsdd file:
We do this by adding the wsdlFile tag in the service element where we can point to the real .wsdl file.
First we need to add its dependencies to the pom.xml.
Spring is integrated just as it would like to, we add its listener to the web.xml and a context parameter to be able to configure precisely what spring xml files to use:
Next is to add a plain spring XML file named axis-example-context.xml in the src/main/resources folder.
The spring XML file is currently empty. We hit jetty again with
We would like to be able to get hold of the Spring ApplicationContext from our webservice so we can get access to the glory spring, but how do we do this? And our webservice class AxisReportIncidentService is created and managed by Axis we want to let Spring do this. So we have two problems.
We solve these problems by creating a delegate class that Axis creates, and this delegate class gets hold on Spring and then gets our real webservice as a spring bean and invoke the service.
First we create a new class that is 100% independent from Axis and just a plain POJO. This is our real service.
So now we need to get from AxisReportIncidentService to this one ReportIncidentService using Spring. Well first of all we add our real service to spring XML configuration file so Spring can handle its lifecycle:
And then we need to modify AxisReportIncidentService to use Spring to lookup the spring bean id="incidentservice" and delegate the call. We do this by extending the spring class
To see if everything is okay we run
In the code above we get hold of our service at each request by looking up in the application context. However Spring also supports an init method where we can do this once. So we change the code to:
So now we have integrated Axis with Spring and we are ready for Camel.
Again the first step is to add the dependencies to the maven pom.xml file:
Now that we have integrated with Spring then we easily integrate with Camel as Camel works well with Spring.
We choose to integrate Camel in the Spring XML file so we add the camel namespace and the schema location:
Store a file backup
We want to store the web service request as a file before we return a response. To do this we want to send the file content as a message to an endpoint that produces the file. So we need to do two steps:
The endpoint is configured in spring XML so we just add it as:
In the CamelContext we have defined our endpoint with the id
Next up is to be able to send a message to this endpoint. The easiest way is to use a ProducerTemplate. A ProducerTemplate is inspired by Spring template pattern with for instance JmsTemplate or JdbcTemplate in mind. The template that all the grunt work and exposes a simple interface to the end-user where he/she can set the payload to send. Then the template will do proper resource handling and all related issues in that regard. But how do we get hold of such a template? Well the CamelContext is able to provide one. This is done by configuring the template on the camel context in the spring XML as:
Then we can expose a ProducerTemplate property on our service with a setter in the Java code as:
And then let Spring handle the dependency inject as below:
Now we are ready to use the producer template in our service to send the payload to the endpoint. The template has many sendXXX methods for this purpose. But before we send the payload to the file endpoint we must also specify what filename to store the file as. This is done by sending meta data with the payload. In Camel metadata is sent as headers. Headers is just a plain
The template in the code above uses 4 parameters:
Running the example
We start our integration with maven using
You can then test it using a web service test tools such as SoapUI.
And there should be a file in the target subfolder.
We would like to be able to unit test our ReportIncidentService class. So we add junit to the maven dependency:
And then we create a plain junit testcase for our service class.
Then we can run the test with maven using:
What is the problem? Well our service uses a CamelProducer (the template) to send a message to the file endpoint so the message will be stored in a file. What we need is to get hold of such a producer and inject it on our service, by calling the setter.
Since Camel is very light weight and embedable we are able to create a CamelContext and add the endpoint in our unit test code directly. We do this to show how this is possible:
So now we are ready to set the ProducerTemplate on our service, and we get a hold of that baby from the CamelContext as:
And this time when we run the unit test its a success:
We would like to test that the file exists so we add these two lines to our test method:
Smarter Unit Testing with Spring
The unit test above requires us to assemble the Camel pieces manually in java code. What if we would like our unit test to use our spring configuration file axis-example-context.xml where we already have setup the endpoint. And of course we would like to test using this configuration file as this is the real file we will use. Well hey presto the xml file is a spring ApplicationContext file and spring is able to load it, so we go the spring path for unit testing. First we add the spring-test jar to our maven dependency:
And then we refactor our unit test to be a standard spring unit class. What we need to do is to extend
What we must remember to add is the classpath: prefix as our xml file is located in
The last change is to get hold of the producer template and now we can just refer to the bean id it has in the spring xml file:
So we get hold of it by just getting it from the spring ApplicationContext as all spring users is used to do:
Now our unit test is much better, and a real power of Camel is that is fits nicely with Spring and you can use standard Spring'ish unit test to test your Camel applications as well.
Unit Test calling WebService
What if you would like to execute a unit test where you send a webservice request to the AxisReportIncidentService how do we unit test this one? Well first of all the code is merely just a delegate to our real service that we have just tested, but nevertheless its a good question and we would like to know how. Well the answer is that we can exploit that fact that Jetty is also a slim web container that can be embedded anywhere just as Camel can. So we add this to our pom.xml:
Then we can create a new class AxisReportIncidentServiceTest to unit test with Jetty. The code to setup Jetty is shown below with code comments:
Now we just need to send the incident as a webservice request using Axis. So we add the following code:
And now we have an unittest that sends a webservice request using good old Axis.
Both Camel and Spring has annotations that can be used to configure and wire trivial settings more elegantly. Camel has the endpoint annotation
Camel is smart as
Running the unit test with
And since we use the
And the final touch we can do is that since the endpoint is injected with concrete endpoint to use we can remove the
To without the name:
Then we avoid to duplicate the name and if we rename the endpoint name then we don't forget to change it in the code also.
This tutorial hasn't really touched the one of the key concept of Camel as a powerful routing and mediation framework. But we wanted to demonstrate its flexibility and that it integrates well with even older frameworks such as Apache Axis 1.4.
Check out the other tutorials on Camel and the other examples.
Note that the code shown here also applies to Camel 1.4 so actually you can get started right away with the released version of Camel. As this time of writing Camel 1.5 is work in progress.