JAX-WS - CXF Contract First Hello World Webservice Tutorial

Apache CXF is an open source services framework. CXF helps to build and develop services using front-end programming APIs like JAX-WS and JAX-RS. These services can speak a variety of protocols such as SOAP, XML/HTTP or RESTful HTTP and work over a variety of transports such as HTTP or JMS.

The following tutorial illustrates a basic example in which we will configure, build and run a Hello World contract first client and web service using CXF, Spring, Maven, and Jetty.

Start with a WSDL contract and generate Java objects to implement the service.

Start with a Java object and service-enable it using annotations.

For new development, the preferred approach is to first design your services using the Web Services Description Language (WSDL) and then generate the code to implement them. This approach enforces the concept that a service is an abstract entity that is implementation neutral.

For the following example, we will use a Hello World service that is defined by the helloworld.wsdl WSDL shown below. It takes as input a persons first and last name and as result returns a greeting.

Next is the Maven POM file which contains the needed dependencies. At the top of the list we find the CXF dependencies. The cxf-rt-transports-http-jetty dependency is only needed in case the CFXServlet is not used. As the example includes a JUnit test that runs without CXFServlet we need to add this dependency.

CXF supports the Spring 2.0 XML syntax, which makes it easy to declare endpoints which are backed by Spring and inject clients into application code. It is also possible to use CXF without Spring but it may take a little extra effort. A number of things like policies and annotation processing are not wired in without Spring. To take advantage of those you would need to do some pre-setup coding. The example below will use Spring to create both requester (client) and provider (service) as such the needed Spring dependencies are included.

In addition to a unit test case we will also create an integration test case for which an instance of Jetty will be started that will host the above Hello World service. In order to achieve this the jetty-maven-plugin has been added which is configured to be started/stopped, before/after the 'integration-test' phase of Maven. The '<daemon>true</daemon>' configuration option forces Jetty to execute only while Maven is running, instead of running indefinitely.

CXF includes a Maven plugin called cxf-codegen-plugin which can generate Java artifacts from a WSDL. In the above POM the 'wsdl2java' goal is configured to run in the generate-sources phase. By running the below Maven command, CXF will generate the Java artifacts. Each '<wsdlOption>' element corresponds to a WSDL that needs generated artifacts.

mvn generate-sources

In order to avoid a hard-coded absolute path towards the configured WSDL in the generated Java artifacts, specify a '<wsdlLocation>' element using the classpath reference as shown above.

After running the 'mvn generate-sources' command you should be able to find back a number of auto-generated classes amongst which the HelloWorldPort interface as shown below. In the next sections, we will use this interface to implement both the client and service.

Creating The Requester (Client)

Creating a CXF client using Spring is done by specifying a jaxws:client bean as shown in the below cxf-requester.xml. In addition to a bean name, the service interface and the service address (or URL) need to be specified.

The result of below configuration is a bean that will be created with the specified name, implementing the service interface and invoking the remote SOAP service under the covers.

For this example, the CXF Spring configuration is kept in a separate file that is imported in the main context-requester.xml shown below. In addition to this, annotation-based configuration is enabled and a cxf.properties file is loaded which contains the address at which the Hello World service was made available in the previous section.

The actual client code is specified in the HelloWorldClient class which exposes a sayHello() method that takes as input a Person object. The helloworldRequesterBean previously defined in the cxf-requester.xml is auto wired using the corresponding annotation.

Creating The Provider (Service)

Creating a CXF service using Spring is done by specifying a jaxws:endpoint bean as shown in the below cxf-provider.xml. In addition to a bean name, the implementer class name and the address at which the service will be published need to be specified. In other words, the below configuration tells CXF how to route requests received by the servlet to the service-implementation code.

Java web applications use a deployment descriptor file to determine how URLs map to servlets and other information. This file is named web.xml, and resides in the app’s WAR under the WEB-INF directory. The below web.xml defines the CXFServlet and maps all request on '/codenotfound/services/*' to this servlet.

In this example, a Spring context is used to load the previous defined CXF provider configuration. Spring can be integrated into any Java-based web framework by declaring the ContextLoaderListener and using a contextConfigLocation to set which context file(s) to load.

Note that if a specific 'contextConfigLocation' context parameter is not specified, CXF looks for a context with the file name cxf-servlet.xml.

The HelloWorldImpl class contains the implementation of the Hello World service. It implements the sayHello() method of the HelloWorldPortType interface which was automatically generated by the 'cxf-codegen-plugin'. The method takes a Person object as input and generates a Greeting object that is returned.

Testing The CXF Web Service

In order to verify the correct working of the provider, below HelloWorldImplTest contains a unit test case that uses the JaxWsServerFactoryBean to create a server endpoint. The factory bean needs an instance of the HelloWorldImpl web service implementation and an endpoint address on which the service can be exposed. When the createServerEndpoint() method is called it starts an embedded standalone Jetty server.

The JaxWsProxyFactoryBean is used for creating a client proxy that is used for calling the web service implementation. The createClientProxy() method needs the HelloWorldPortType interface to be passed as well as the endpoint address to invoke.

packagecom.codenotfound.endpoint;importstaticorg.junit.Assert.assertEquals;importorg.apache.cxf.jaxws.JaxWsProxyFactoryBean;importorg.apache.cxf.jaxws.JaxWsServerFactoryBean;importorg.junit.BeforeClass;importorg.junit.Test;importcom.codenotfound.endpoint.HelloWorldImpl;importcom.codenotfound.services.helloworld.Greeting;importcom.codenotfound.services.helloworld.HelloWorldPortType;importcom.codenotfound.services.helloworld.Person;publicclassHelloWorldImplTest{privatestaticStringENDPOINT_ADDRESS="http://localhost:9080/codenotfound/services/helloworld";privatestaticHelloWorldPortTypehelloWorldRequesterProxy;@BeforeClasspublicstaticvoidsetUpBeforeClass()throwsException{createServerEndpoint();helloWorldRequesterProxy=createClientProxy();}@TestpublicvoidtestSayHelloProxy(){Personperson=newPerson();person.setFirstName("Jane");person.setLastName("Doe");Greetinggreeting=helloWorldRequesterProxy.sayHello(person);assertEquals("Hello Jane Doe!",greeting.getText());}privatestaticvoidcreateServerEndpoint(){// use a CXF JaxWsServerFactoryBean to create JAX-WS endpointsJaxWsServerFactoryBeanjaxWsServerFactoryBean=newJaxWsServerFactoryBean();// set the HelloWorld implementationHelloWorldImplimplementor=newHelloWorldImpl();jaxWsServerFactoryBean.setServiceBean(implementor);// set the address at which the HelloWorld endpoint will be exposedjaxWsServerFactoryBean.setAddress(ENDPOINT_ADDRESS);// create the serverjaxWsServerFactoryBean.create();}privatestaticHelloWorldPortTypecreateClientProxy(){// create a CXF JaxWsProxyFactoryBean for creating JAX-WS proxiesJaxWsProxyFactoryBeanjaxWsProxyFactoryBean=newJaxWsProxyFactoryBean();// // set the HelloWorld portType classjaxWsProxyFactoryBean.setServiceClass(HelloWorldPortType.class);// set the address at which the HelloWorld endpoint will be calledjaxWsProxyFactoryBean.setAddress(ENDPOINT_ADDRESS);// create a JAX-WS proxy for the HelloWorld portTypereturn(HelloWorldPortType)jaxWsProxyFactoryBean.create();}}

To test the requester we reuse the JaxWsServerFactoryBean approach. For the client, instead of creating a proxy, SpringJUnit4ClassRunner is used in order to allow auto-wiring the HelloWorldClient bean. The actual test simply calls the sayHello() method of the client and then verifies the response.

packagecom.codenotfound.client;importstaticorg.junit.Assert.assertEquals;importorg.apache.cxf.jaxws.JaxWsServerFactoryBean;importorg.junit.BeforeClass;importorg.junit.Test;importorg.junit.runner.RunWith;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.test.context.ContextConfiguration;importorg.springframework.test.context.junit4.SpringJUnit4ClassRunner;importcom.codenotfound.client.HelloWorldClient;importcom.codenotfound.endpoint.HelloWorldImpl;importcom.codenotfound.services.helloworld.Person;@RunWith(SpringJUnit4ClassRunner.class)@ContextConfiguration(locations={"classpath:/META-INF/spring/context-requester.xml"})publicclassHelloWorldClientTest{privatestaticStringENDPOINT_ADDRESS="http://localhost:9090/codenotfound/services/helloworld";@AutowiredprivateHelloWorldClienthelloWorldClientBean;@BeforeClasspublicstaticvoidsetUpBeforeClass()throwsException{createServerEndpoint();}@TestpublicvoidtestSayHello(){Personperson=newPerson();person.setFirstName("Jane");person.setLastName("Doe");assertEquals("Hello Jane Doe!",helloWorldClientBean.sayHello(person));}privatestaticvoidcreateServerEndpoint(){// use a CXF JaxWsServerFactoryBean to create JAX-WS endpointsJaxWsServerFactoryBeanjaxWsServerFactoryBean=newJaxWsServerFactoryBean();// set the HelloWorld implementationHelloWorldImplimplementor=newHelloWorldImpl();jaxWsServerFactoryBean.setServiceBean(implementor);// set the address at which the HelloWorld endpoint will be exposedjaxWsServerFactoryBean.setAddress(ENDPOINT_ADDRESS);// create the serverjaxWsServerFactoryBean.create();}}

In addition to above unit tests, a HelloWorldImplIT integration test is defined for which an instance of Jetty will be started, using the 'jetty-maven-plugin', that will host the HelloWorldImpl. The actual web service call is made by the HelloWorldClient.

Note that by default, the Maven integration-test phase runs test classes named '**/IT*.java, **/*IT.java, and **/*ITCase.java'.

packagecom.codenotfound;importstaticorg.junit.Assert.assertEquals;importorg.junit.Test;importorg.junit.runner.RunWith;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.test.context.ContextConfiguration;importorg.springframework.test.context.junit4.SpringJUnit4ClassRunner;importcom.codenotfound.client.HelloWorldClient;importcom.codenotfound.services.helloworld.Person;@RunWith(SpringJUnit4ClassRunner.class)@ContextConfiguration(locations={"classpath:/META-INF/spring/context-requester.xml"})publicclassHelloWorldImplIT{@AutowiredprivateHelloWorldClienthelloWorldClientBean;@TestpublicvoidtestSayHello(){Personperson=newPerson();person.setFirstName("John");person.setLastName("Doe");assertEquals("Hello John Doe!",helloWorldClientBean.sayHello(person));}}

In order to run the above example open a command prompt and execute following Maven command:

mvn verify

Maven will download the needed dependencies, compile the code and run the unit test case. Subsequent Maven will start a Jetty server instance and run the integration test case. The result should be a successful build as shown below.