Since we're on a major migration process of this website, some component documents here are out of sync right now. In the meantime you may want to look at the early version of the new website
https://camel.apache.org/staging/
We would very much like to receive any feedback on the new site, please join the discussion on the Camel user mailing list.
Part 1PrerequisitesThis tutorial uses the following frameworks:
Note: The sample project can be downloaded, see the resources section. Initial Project SetupWe want the integration to be a standard .war application that can be deployed in any web container such as Tomcat, Jetty or even heavy weight application servers such as WebLogic or WebSphere. There fore we start off with the standard Maven webapp project that is created with the following long archetype command: mvn archetype:create -DgroupId=org.apache.camel -DartifactId=camel-example-reportincident -DarchetypeArtifactId=maven-archetype-webapp Notice that the groupId etc. doens't have to be org.apache.camel it can be com.mycompany.whatever. But I have used these package names as the example is an official part of the Camel distribution. Then we have the basic maven folder layout. We start out with the webservice part where we want to use Apache CXF for the webservice stuff. So we add this to the pom.xml <properties> <cxf-version>2.6.1</cxf-version> </properties> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-core</artifactId> <version>${cxf-version}</version> </dependency> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-frontend-jaxws</artifactId> <version>${cxf-version}</version> </dependency> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http</artifactId> <version>${cxf-version}</version> </dependency> Developing the WebServiceAs we want to develop webservice with the contract first approach we create our .wsdl file. As this is a example we have simplified the model of the incident to only include 8 fields. In real life the model would be a bit more complex, but not to much. We put the wsdl file in the folder <?xml version="1.0" encoding="ISO-8859-1"?> <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://reportincident.example.camel.apache.org" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://reportincident.example.camel.apache.org"> <!-- Type definitions for input- and output parameters for webservice --> <wsdl:types> <xs:schema targetNamespace="http://reportincident.example.camel.apache.org"> <xs:element name="inputReportIncident"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="incidentId"/> <xs:element type="xs:string" name="incidentDate"/> <xs:element type="xs:string" name="givenName"/> <xs:element type="xs:string" name="familyName"/> <xs:element type="xs:string" name="summary"/> <xs:element type="xs:string" name="details"/> <xs:element type="xs:string" name="email"/> <xs:element type="xs:string" name="phone"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="outputReportIncident"> <xs:complexType> <xs:sequence> <xs:element type="xs:string" name="code"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> </wsdl:types> <!-- Message definitions for input and output --> <wsdl:message name="inputReportIncident"> <wsdl:part name="parameters" element="tns:inputReportIncident"/> </wsdl:message> <wsdl:message name="outputReportIncident"> <wsdl:part name="parameters" element="tns:outputReportIncident"/> </wsdl:message> <!-- Port (interface) definitions --> <wsdl:portType name="ReportIncidentEndpoint"> <wsdl:operation name="ReportIncident"> <wsdl:input message="tns:inputReportIncident"/> <wsdl:output message="tns:outputReportIncident"/> </wsdl:operation> </wsdl:portType> <!-- Port bindings to transports and encoding - HTTP, document literal encoding is used --> <wsdl:binding name="ReportIncidentBinding" type="tns:ReportIncidentEndpoint"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="ReportIncident"> <soap:operation soapAction="http://reportincident.example.camel.apache.org/ReportIncident" style="document"/> <wsdl:input> <soap:body parts="parameters" use="literal"/> </wsdl:input> <wsdl:output> <soap:body parts="parameters" use="literal"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <!-- Service definition --> <wsdl:service name="ReportIncidentService"> <wsdl:port name="ReportIncidentPort" binding="tns:ReportIncidentBinding"> <soap:address location="http://reportincident.example.camel.apache.org"/> </wsdl:port> </wsdl:service> </wsdl:definitions> CXF wsdl2javaThen we integration the CXF wsdl2java generator in the pom.xml so we have CXF generate the needed POJO classes for our webservice contract. <!-- to compile with 1.6 --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.6</source> <target>1.6</target> </configuration> </plugin> And then we can add the CXF wsdl2java code generator that will hook into the compile goal so its automatic run all the time: <!-- CXF wsdl2java generator, will plugin to the compile goal --> <plugin> <groupId>org.apache.cxf</groupId> <artifactId>cxf-codegen-plugin</artifactId> <version>${cxf-version}</version> <executions> <execution> <id>generate-sources</id> <phase>generate-sources</phase> <configuration> <sourceRoot>${basedir}/target/generated/src/main/java</sourceRoot> <wsdlOptions> <wsdlOption> <wsdl>${basedir}/src/main/webapp/WEB-INF/wsdl/report_incident.wsdl</wsdl> </wsdlOption> </wsdlOptions> </configuration> <goals> <goal>wsdl2java</goal> </goals> </execution> </executions> </plugin> You are now setup and should be able to compile the project. So running the Configuration of the web.xmlNext up is to configure the web.xml to be ready to use CXF so we can expose the webservice. <!-- the listener that kick-starts Spring --> <listener> <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> </listener> And then we have the CXF part where we define the CXF servlet and its URI mappings to which we have chosen that all our webservices should be in the path <!-- CXF servlet --> <servlet> <servlet-name>CXFServlet</servlet-name> <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <!-- all our webservices are mapped under this URI pattern --> <servlet-mapping> <servlet-name>CXFServlet</servlet-name> <url-pattern>/webservices/*</url-pattern> </servlet-mapping> Then the last piece of the puzzle is to configure CXF, this is done in a spring XML that we link to fron the web.xml by the standard Spring <!-- location of spring xml files --> <context-param> <param-name>contextConfigLocation</param-name> <param-value>classpath:cxf-config.xml</param-value> </context-param> We have named our CXF configuration file Getting rid of the old jsp worldThe maven archetype that created the basic folder structure also created a sample .jsp file index.jsp. This file Configuration of CXFThe cxf-config.xml is as follows: <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd"> <import resource="classpath:META-INF/cxf/cxf.xml"/> <import resource="classpath:META-INF/cxf/cxf-extension-soap.xml"/> <import resource="classpath:META-INF/cxf/cxf-servlet.xml"/> <!-- implementation of the webservice --> <bean id="reportIncidentEndpoint" class="org.apache.camel.example.reportincident.ReportIncidentEndpointImpl"/> <!-- export the webservice using jaxws --> <jaxws:endpoint id="reportIncident" implementor="#reportIncidentEndpoint" address="/incident" wsdlLocation="/WEB-INF/wsdl/report_incident.wsdl" endpointName="s:ReportIncidentPort" serviceName="s:ReportIncidentService" xmlns:s="http://reportincident.example.camel.apache.org"/> </beans> The configuration is standard CXF and is documented at the Apache CXF website. The 3 import elements is needed by CXF and they must be in the file. Noticed that we have a spring bean reportIncidentEndpoint that is the implementation of the webservice endpoint we let CXF expose. Implementing the ReportIncidentEndpointPhew after all these meta files its time for some java code so we should code the implementor of the webservice. So we fire up You can use As we want to quickly see our webservice we implement just a quick and dirty as it can get. At first beware that since its jaxws and Java 1.5 we get annotations for the money, but they reside on the interface so we can remove them from our implementations so its a nice plain POJO again: package org.apache.camel.example.reportincident; /** * The webservice we have implemented. */ public class ReportIncidentEndpointImpl implements ReportIncidentEndpoint { public OutputReportIncident reportIncident(InputReportIncident parameters) { System.out.println("Hello ReportIncidentEndpointImpl is called from " + parameters.getGivenName()); OutputReportIncident out = new OutputReportIncident(); out.setCode("OK"); return out; } } We just output the person that invokes this webservice and returns a OK response. This class should be in the maven source root folder To test if we are home free we run Running our webserviceNow that the code compiles we would like to run it inside a web container, for this purpose we make use of Jetty which we will bootstrap using it's plugin <build> <plugins> ... <!-- so we can run mvn jetty:run --> <plugin> <groupId>org.mortbay.jetty</groupId> <artifactId>maven-jetty-plugin</artifactId> <version>${jetty-version}</version> </plugin> Notice: We make use of the Jetty version being defined inside the Camel's Parent POM. So to see if everything is in order we fire up jetty with So where is the damn webservice then? Well as we did configure the web.xml to instruct the CXF servlet to accept the pattern Hitting the webserviceNow we have the webservice running in a standard .war application in a standard web container such as Jetty we would like to invoke the webservice and see if we get our code executed. Unfortunately this isn't the easiest task in the world - its not so easy as a REST URL, so we need tools for this. So we fire up our trusty webservice tool SoapUI and let it be the one to fire the webservice request and see the response. Using SoapUI we sent a request to our webservice and we got the expected OK response and the console outputs the System.out so we are ready to code. Remote DebuggingOkay a little sidestep but wouldn't it be cool to be able to debug your code when its fired up under Jetty? As Jetty is started from maven, we need to instruct maven to use debug mode. MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=128m -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005 Then you need to restart Jetty so its stopped with ctrl + c. Remember to start a new shell to pickup the new environment settings. And start jetty again. Then we can from our IDE attach a remote debugger and debug as we want. Then we set a breakpoint in our code Adding a unit testOh so much hard work just to hit a webservice, why can't we just use an unit test to invoke our webservice? Yes of course we can do this, and that's the next step. package org.apache.camel.example.reportincident; import junit.framework.TestCase; /** * Plain JUnit test of our webservice. */ public class ReportIncidentEndpointTest extends TestCase { } Here we have a plain old JUnit class. As we want to test webservices we need to start and expose our webservice in the unit test before we can test it. And JAXWS has pretty decent methods to help us here, the code is simple as: import javax.xml.ws.Endpoint; ... private static String ADDRESS = "http://localhost:9090/unittest"; protected void startServer() throws Exception { // We need to start a server that exposes or webservice during the unit testing // We use jaxws to do this pretty simple ReportIncidentEndpointImpl server = new ReportIncidentEndpointImpl(); Endpoint.publish(ADDRESS, server); } The Endpoint class is the /* * */ package org.apache.camel.example.reportincident; import javax.jws.WebMethod; import javax.jws.WebParam; import javax.jws.WebResult; import javax.jws.WebService; import javax.jws.soap.SOAPBinding; import javax.jws.soap.SOAPBinding.ParameterStyle; import javax.xml.bind.annotation.XmlSeeAlso; /** * This class was generated by Apache CXF 2.1.1 * Wed Jul 16 12:40:31 CEST 2008 * Generated source version: 2.1.1 * */ /* * */ @WebService(targetNamespace = "http://reportincident.example.camel.apache.org", name = "ReportIncidentEndpoint") @XmlSeeAlso({ObjectFactory.class}) @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) public interface ReportIncidentEndpoint { /* * */ @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) @WebResult(name = "outputReportIncident", targetNamespace = "http://reportincident.example.camel.apache.org", partName = "parameters") @WebMethod(operationName = "ReportIncident", action = "http://reportincident.example.camel.apache.org/ReportIncident") public OutputReportIncident reportIncident( @WebParam(partName = "parameters", name = "inputReportIncident", targetNamespace = "http://reportincident.example.camel.apache.org") InputReportIncident parameters ); } Next up is to create a webservice client so we can invoke our webservice. For this we actually use the CXF framework directly as its a bit more easier to create a client using this framework than using the JAXWS style. We could have done the same for the server part, and you should do this if you need more power and access more advanced features. import org.apache.cxf.jaxws.JaxWsProxyFactoryBean; ... protected ReportIncidentEndpoint createCXFClient() { // we use CXF to create a client for us as its easier than JAXWS and works JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean(); factory.setServiceClass(ReportIncidentEndpoint.class); factory.setAddress(ADDRESS); return (ReportIncidentEndpoint) factory.create(); } So now we are ready for creating a unit test. We have the server and the client. So we just create a plain simple unit test method as the usual junit style: public void testRendportIncident() throws Exception { startServer(); ReportIncidentEndpoint client = createCXFClient(); InputReportIncident input = new InputReportIncident(); input.setIncidentId("123"); input.setIncidentDate("2008-07-16"); input.setGivenName("Claus"); input.setFamilyName("Ibsen"); input.setSummary("bla bla"); input.setDetails("more bla bla"); input.setEmail("davsclaus@apache.org"); input.setPhone("+45 2962 7576"); OutputReportIncident out = client.reportIncident(input); assertEquals("Response code is wrong", "OK", out.getCode()); } Now we are nearly there. But if you run the unit test with <!-- cxf web container for unit testing --> <dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-jetty</artifactId> <version>${cxf-version}</version> <scope>test</scope> </dependency> Well what is that, CXF also uses Jetty for unit test - well its just shows how agile, embedable and popular Jetty is. So lets run our junit test with, and it reports: mvn test Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 [INFO] BUILD SUCCESSFUL Yep thats it for now. We have a basic project setup. End of part 1Thanks for being patient and reading all this more or less standard Maven, Spring, JAXWS and Apache CXF stuff. Its stuff that is well covered on the net, but I wanted a full fledged tutorial on a maven project setup that is web service ready with Apache CXF. We will use this as a base for the next part where we demonstrate how Camel can be digested slowly and piece by piece just as it was back in the times when was introduced and was learning the Spring framework that we take for granted today. #ResourcesLinks |