Page History

CXF includes a provides the 'simple frontend which builds services from reflection. This is in contrast to the JAX-WS frontend which requires you to annotate your services. The simple frontend will use reflection to intelligently map your classes to a WSDL model. ' frontend to map Java APIs to and from WSDL models for web services. The simple front end is much like JAX-WS, however, where JAX-WS uses Java annotations to specify detailed configuration (and, indeed, requires a few), Simple is willing to map a 'naked' interface or class to a service, and respects some configuration options from .aegis.xml files shared with the Aegis data binding.

Note

title	Most Applications Should Use JAX-WS

The JAX-WS frontend is far more flexible than the Simple frontend. There are only two reasons to select Simple over JAX-WS:

You must avoid the use of Java annotations. JAX-WS requires them, Simple does not.
You want to have the absolutely smallest possible collection of additional dependencies. JAX-WS has more dependencies than Simple.

Other than these items, Simple has no advantages over JAX-WS. The implementation classes of JAX-WS in CXF are all subclasses of the implementation classes of Simple. In a 'simple' case, very nearly identical things happen in the Simple front end as in JAX-WS. CXF's extensions to JAX-WS, on the other hand, make it very 'simple' to use.

Simple Pitfall: Unreliable Parameter Names

The typical pattern of a web service is to define a Service Endpoint Interface and then create a class that implements that interface. When you own both ends of the process, you can simply use the SEI in both the server and the client.

The problem has to do with a quirk of Java reflection. If a program uses Java reflection to examine a concrete method of a class, the data available may provide the parameter names from the source. The behavior of current Java compilers depends on whether you ask them to provide debug symbols. However, if a program uses reflection to look at an abstract method, current Java compilers never provide the parameter names.

If there are no names, Simple creates ugly parameters named arg0, arg1, ... Further, if you forget to specify the SEI when creating a service, and only provide the SEB, Simple will see your concrete methods and assign actual parameter names (if you have debug symbols). If you client uses the SEI, they won't communicate. If you change your mind about debug symbols, you will change the contract.

Thus, while JAX-WS @WebParam annotations may seem noisy and inconvenient, they are, in fact, ensuring that your service has a consistent contract.

If you choose to use the Simple front end, you will need to use parameter elements in a .aegis.xml file to give useful names, or be sure to provide the SEI to the ServerFactoryBean.

Simple and Data Bindings

By default CXF uses the JAXB databinding. If you are interested in a databinding which does not require annotations, please see the documentation on the Aegis Databinding.

...

This is a historical default, but often not what you will want, both due to the pitfall described above and the JAX-B issue described at the bottom of this page. If you choose to use the Simple front end, we recommend that you use the Aegis databinding.

ServerFactoryBean – Making a Service Endpoint

The ServerFactoryBean produces a Server instance for you. It requires a service class and an address to publish the service on. By creating a Server you'll have started your service and made it available to the outside world.

...

Your service is now started! You can access the wsdl at "http://localhost:9000/Hello?wsdl".

ClientProxyFactoryBean – Making a Client Proxy

You'll also want to create a client for your service. CXF includes a ClientProxyFactoryBean which will create a Java proxy for you from your interface which will invoke the service.

...

Code Block

	xml
	xml

<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:simple="http://cxf.apache.org/simple"
      xmlns:soap="http://cxf.apache.org/bindings/soap"
      xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd
http://cxf.apache.org/simple http://cxf.apache.org/schemas/simple.xsd">

  <simple:server id="pojoservice" serviceClass="demo.hw.server.HelloWorld" address="/hello_world">
  	<simple:serviceBean>
  		<bean class="demo.hw.server.HelloWorldImpl" />
  	</simple:serviceBean>
  </simple:server>
</beans>

The simple:server element supports many additional attributes:

Name	Value
endpointName	The endpoint name this service is implementing, it maps to the wsdl:port@name. In the format of "ns:ENDPOINT_NAME" where ns is a namespace prefix valid at this scope.
serviceName	The service name this service is implementing, it maps to the wsdl:service@name. In the format of "ns:SERVICE_NAME" where ns is a namespace prefix valid at this scope.
wsdlLocation	The location of the WSDL. Can be on the classpath, file system, or be hosted remotely.
bindingId	The binding uri for the service model to use
transportId	The transport uri which is used for looking up the transport factory in CXF
address	The service publish address
bus	The bus name that will be used in the jaxws endpoint.
serviceBean	The implementor of jaxws endpoint. You can specify the implementor class name here, or just the ref bean name in the format of "#REF_BEAN_NAME"
serviceClass	The implementor class name, it is really useful when you specify the implementor with the ref bean which is wrapped by using Spring AOP
start	Whether the service endpoint should be published now, or whether it will be published at a later point

It also supports many child elements:

Name	Value
simple:executor	A Java executor which will be used for the service. This can be supplied using the Spring <bean class="MyExecutor"/> syntax.
simple:inInterceptors	The incoming interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:inFaultInterceptors	The incoming fault interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:outInterceptors	The outgoing interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:outFaultInterceptors	The outgoing fault interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:properties	A properties map which should be supplied to the JAX-WS endpoint. See below.
simple:dataBinding	You can specify the which DataBinding will be use in the endpoint , This can be supplied using the Spring <bean class="MyDataBinding"/> syntax.
simple:binding	You can specify the BindingFactory for this endpoint to use. This can be supplied using the Spring <bean class="MyBindingFactory"/> syntax.
simple:features	The features that hold the interceptors for this endpoint. A list of <bean>s or <ref>s
simple:invoker	The invoker which will be supplied to this endpoint. This can be supplied using the Spring <bean class="MyInvoker"/> syntax.
simple:schemaLocations	The schema locations for endpoint to use. A list of <schemaLocation>s
simple:serviceFactory	The service factory for this endpoint to use. This can be supplied using the Spring <bean class="MyServiceFactory"/> syntax
simple:serviceBean	The service implementation instance to be used. This can be supplied using the Spring <bean class="MyServiceBean"/> syntax

Here is a more advanced example which shows how to provide interceptors and properties:

Code Block

xml


<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:simple="http://cxf.apache.org/simple"
      xmlns:soap="http://cxf.apache.org/bindings/soap"
      xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd
http://cxf.apache.org/simple http://cxf.apache.org/schemas/simple.xsd">

    <simple:server id="inlineInvoker" 
    serviceClass="org.apache.cxf.service.factory.HelloServiceImpl"
    address="http://localhost:8080/simpleWithAddress">
    <simple:invoker>
      <bean class="org.apache.cxf.service.invoker.BeanInvoker">
        <constructor-arg>
          <bean class="org.apache.cxf.service.factory.HelloServiceImpl"/>
        </constructor-arg>
      </bean>
    </simple:invoker>    
  </simple:server>
  
  <simple:server id="inlineSoapBinding" 
    serviceClass="org.apache.cxf.service.factory.HelloService"
    serviceBean="#greeter"
    address="http://localhost:8080/test"   
    serviceName="t:HelloService"
    xmlns:t="http://apache.org/hello_world_soap_http"
    endpointName="t:HelloPort"
    >
    <simple:binding>
      <soap:soapBinding mtomEnabled="true" version="1.2"/>
    </simple:binding>
  </simple:server>
</beans>

Configure with Spring for the simple front end client

You could use the <simple:client> element to configure the simple front end client, you can use the spring's getBean API to get the client instance from the application context.

...


<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:simple="http://cxf.apache.org/simple"
      xmlns:soap="http://cxf.apache.org/bindings/soap"
      xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd
http://cxf.apache.org/simple http://cxf.apache.org/schemas/simple.xsd">

  <simple:client id="client" 
    serviceClass="org.apache.cxf.service.factory.HelloService"
    address="http://localhost:9000/foo2"
    serviceName="s:XMLService"
    xmlns:s="http://apache.org/hello_world_soap_http"
    endpointName="s:XMLPort"    
    bindingId="http://cxf.apache.org/bindings/xformat"/>
</beans>

The simple:client element supports many additional attributes:

Name	Value
endpointName	The endpoint name this service is implementing, it maps to the wsdl:port@name. In the format of "ns:ENDPOINT_NAME" where ns is a namespace prefix valid at this scope.
serviceName	The service name this service is implementing, it maps to the wsdl:service@name. In the format of "ns:SERVICE_NAME" where ns is a namespace prefix valid at this scope.
wsdlLocation	The location of the WSDL. Can be on the classpath, file system, or be hosted remotely.
bindingId	The binding uri for the service model to use
address	The service publish address
bus	The bus name that will be used in the jaxws endpoint.
serviceClass	The implementor class name, it is really useful when you specify the implementor with the ref bean which is wrapped by using Spring AOP
username	The user name which is used in the transport layer
password	The password that is used in the transport layer

It also supports many child elements:

Name	Value
simple:inInterceptors	The incoming interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:inFaultInterceptors	The incoming fault interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:outInterceptors	The outgoing interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:outFaultInterceptors	The outgoing fault interceptors for this endpoint. A list of <bean>s or <ref>s.
simple:properties	A properties map which should be supplied to the JAX-WS endpoint. See below.
simple:dataBinding	You can specify the which DataBinding will be use in the endpoint , This can be supplied using the Spring <bean class="MyDataBinding"/> syntax.
simple:binding	You can specify the BindingFactory for this endpoint to use. This can be supplied using the Spring <bean class="MyBindingFactory"/> syntax.
simple:features	The features that hold the interceptors for this endpoint. A list of <bean>s or <ref>s
simple:conduitSelector	The conduit selector which is strategy for retreival of a conduit to mediate an outbound message to be injected into the client.

Here is a more advanced example which shows how to provide interceptors and properties:

Code Block

xml

<beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:simple="http://cxf.apache.org/simple"
      xmlns:soap="http://cxf.apache.org/bindings/soap"
      xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd
http://cxf.apache.org/simple http://cxf.apache.org/schemas/simple.xsd">

  <bean id="saajIn" class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/>
  <bean id="saajOut" class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/>
  
  <simple:client id="client1" 
    serviceClass="org.apache.cxf.service.factory.HelloService"
    address="http://localhost:9000/foo"
    serviceName="s:SOAPService"
    xmlns:s="http://apache.org/hello_world_soap_http">
    <simple:binding>
      <soap:soapBinding mtomEnabled="true" version="1.2"/>
    </simple:binding>
    <simple:inInterceptors>
	  <bean class="org.apache.cxf.interceptor.LoggingInInterceptor"/>
	  <ref bean="saajIn"/>
	</simple:inInterceptors>
	<simple:outInterceptors>
	  <bean class="org.apache.cxf.interceptor.LoggingOutInterceptor"/>
	  <ref bean="saajOut"/>
	</simple:outInterceptors>
    <simple:conduitSelector>
      <bean class="org.apache.cxf.endpoint.NullConduitSelector"/>
    </simple:conduitSelector>
  </simple:client>
</beans>

Deploying Simple FrontEnd service to a container

...

Warning

There is a known issue for the JAXB data binding with POJO, please see Dan Kulp's comment in https://issues.apache.org/jira/browse/CXF-897^{Image Removed} .
If you want to use JAXB binding you should use the JAX-WS Frontend. Mixing Simple Frontend and JAXB binding leads to problems. The article A simple JAX-WS service shows a code first JAX-WS service that is almost as easy to use as the Simple Frontend.

Child pages

Versions Compared

Old Version 14

New Version Current

Key

Simple Pitfall: Unreliable Parameter Names

Simple and Data Bindings

ServerFactoryBean – Making a Service Endpoint

ClientProxyFactoryBean – Making a Client Proxy

Configure with Spring for the simple front end client

Deploying Simple FrontEnd service to a container