Chapter 17. Configuring JAX-WS Endpoints

Abstract

JAX-WS endpoints are configured using one of three Spring configuration elements. The correct element depends on what type of endpoint you are configuring and which features you wish to use. For consumers you use the jaxws:client element. For service providers you can use either the jaxws:endpoint element or the jaxws:server element.

The information used to define an endpoint is typically defined in the endpoint’s contract. You can use the configuration element’s to override the information in the contract. You can also use the configuration elements to provide information that is not provided in the contract.

You must use the configuration elements to activate advanced features such as WS-RM. This is done by providing child elements to the endpoint’s configuration element. Note that when dealing with endpoints developed using a Java-first approach it is likely that the SEI serving as the endpoint’s contract is lacking information about the type of binding and transport to use.

17.1. Configuring Service Providers

17.1.1. Elements for Configuring Service Providers

Apache CXF has two elements that can be used to configure a service provider:

The differences between the two elements are largely internal to the runtime. The jaxws:endpoint element injects properties into the org.apache.cxf.jaxws.EndpointImpl object created to support a service endpoint. The jaxws:server element injects properties into the org.apache.cxf.jaxws.support.JaxWsServerFactoryBean object created to support the endpoint. The EndpointImpl object passes the configuration data to the JaxWsServerFactoryBean object. The JaxWsServerFactoryBean object is used to create the actual service object. Because either configuration element will configure a service endpoint, you can choose based on the syntax you prefer.

17.1.2. Using the jaxws:endpoint Element

Overview

The jaxws:endpoint element is the default element for configuring JAX-WS service providers. Its attributes and children specify all of the information needed to instantiate a service provider. Many of the attributes map to information in the service’s contract. The children are used to configure interceptors and other advanced features.

Identifying the endpoint being configured

For the runtime to apply the configuration to the proper service provider, it must be able to identify it. The basic means for identifying a service provider is to specify the class that implements the endpoint. This is done using the jaxws:endpoint element’s implementor attribute.

For instances where different endpoint’s share a common implementation, it is possible to provide different configuration for each endpoint. There are two approaches for distinguishing a specific endpoint in configuration:

  • a combination of the serviceName attribute and the endpointName attribute

    The serviceName attribute specifies the wsdl:service element defining the service’s endpoint. The endpointName attribute specifies the specific wsdl:port element defining the service’s endpoint. Both attributes are specified as QNames using the format ns:name. ns is the namespace of the element and name is the value of the element’s name attribute.

    Note

    If the wsdl:service element only has one wsdl:port element, the endpointName attribute can be omitted.

  • the name attribute

    The name attribute specifies the QName of the specific wsdl:port element defining the service’s endpoint. The QName is provided in the format {ns}localPart. ns is the namespace of the wsdl:port element and localPart is the value of the wsdl:port element’s name attribute.

Attributes

The attributes of the jaxws:endpoint element configure the basic properties of the endpoint. These properties include the address of the endpoint, the class that implements the endpoint, and the bus that hosts the endpoint.

Table 17.1, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:endpoint Element” describes the attribute of the jaxws:endpoint element.

Table 17.1. Attributes for Configuring a JAX-WS Service Provider Using the jaxws:endpoint Element

AttributeDescription

id

Specifies a unique identifier that other configuration elements can use to refer to the endpoint.

implementor

Specifies the class implementing the service. You can specify the implementation class using either the class name or an ID reference to a Spring bean configuring the implementation class. This class must be on the classpath.

implementorClass

Specifies the class implementing the service. This attribute is useful when the value provided to the implementor attribute is a reference to a bean that is wrapped using Spring AOP.

address

Specifies the address of an HTTP endpoint. This value overrides the value specified in the services contract.

wsdlLocation

Specifies the location of the endpoint’s WSDL contract. The WSDL contract’s location is relative to the folder from which the service is deployed.

endpointName

Specifies the value of the service’s wsdl:port element’s name attribute. It is specified as a QName using the format ns:name where ns is the namespace of the wsdl:port element.

serviceName

Specifies the value of the service’s wsdl:service element’s name attribute. It is specified as a QName using the format ns:name where ns is the namespace of the wsdl:service element.

publish

Specifies if the service should be automatically published. If this is set to false, the developer must explicitly publish the endpointas described in Chapter 31, Publishing a Service.

bus

Specifies the ID of the Spring bean configuring the bus used to manage the service endpoint. This is useful when configuring several endpoints to use a common set of features.

bindingUri

Specifies the ID of the message binding the service uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs.

name

Specifies the stringified QName of the service’s wsdl:port element. It is specified as a QName using the format {ns}localPart. ns is the namespace of the wsdl:port element and localPart is the value of the wsdl:port element’s name attribute.

abstract

Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is false. Setting this to true instructs the bean factory not to instantiate the bean.

depends-on

Specifies a list of beans that the endpoint depends on being instantiated before it can be instantiated.

createdFromAPI

Specifies that the user created that bean using Apache CXF APIs, such as Endpoint.publish() or Service.getPort().

The default is false.

Setting this to true does the following:

  • Changes the internal name of the bean by appending .jaxws-endpoint to its id
  • Makes the bean abstract

publishedEndpointUrl

The URL that is placed in the address element of the generated WSDL. If this value is not specified, the value of the address attribute is used. This attribute is useful when the "public" URL is not be the same as the URL on which the service is deployed.

In addition to the attributes listed in Table 17.1, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:endpoint Element”, you might need to use multiple xmlns:shortName attributes to declare the namespaces used by the endpointName and serviceName attributes.

Example

Example 17.1, “Simple JAX-WS Endpoint Configuration” shows the configuration for a JAX-WS endpoint that specifies the address where the endpoint is published. The example assumes that you want to use the defaults for all other values or that the implementation has specified values in the annotations.

Example 17.1. Simple JAX-WS Endpoint Configuration

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:endpoint id="example"
                  implementor="org.apache.cxf.example.DemoImpl"
                  address="http://localhost:8080/demo" />
</beans>

Example 17.2, “JAX-WS Endpoint Configuration with a Service Name” shows the configuration for a JAX-WS endpoint whose contract contains two service definitions. In this case, you must specify which service definition to instantiate using the serviceName attribute.

Example 17.2. JAX-WS Endpoint Configuration with a Service Name

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">

  <jaxws:endpoint id="example2"
                  implementor="org.apache.cxf.example.DemoImpl"
                  serviceName="samp:demoService2"
                  xmlns:samp="http://org.apache.cxf/wsdl/example" />

</beans>

The xmlns:samp attribute specifies the namespace in which the WSDL service element is defined.

Example 17.3, “JAX-WS Endpoint Configuration with with HTTP/2 enabled” shows the configuration for a JAX-WS endpoint that specifies the address with HTTP/2 enabled.

Configuring HTTP/2 for Apache CXF

HTTP/2 is supported when using the standalone Apache CXF Undertow transport (http-undertow) on Apache Karaf. To enable the HTTP/2 protocol you must set the jaxws:endpoint element’s address attribute as an absolute URL and set the org.apache.cxf.transports.http_undertow.EnableHttp2 property as true.

Note

This HTTP/2 implementation only supports server side HTTP/2 transport with plain HTTP or HTTPS.

Example 17.3. JAX-WS Endpoint Configuration with with HTTP/2 enabled

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
  http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
  ...">

  <cxf:bus>
    <cxf:properties>
        <entry key="org.apache.cxf.transports.http_undertow.EnableHttp2" value="true"/>
    </cxf:properties>
  </cxf:bus>

  <jaxws:endpoint id="example3"
                implementor="org.apache.cxf.example.DemoImpl"
                address="http://localhost:8080/demo" />
  </jaxws:endpoint>

</beans>
Note

For improved performance, Red Hat recommends using the servlet transport on Apache Karaf (pax-web-undertow) which enables centralized configuration and tuning of the web container, however, pax-web-undertow does not support the HTTP/2 transport protocol.

17.1.3. Using the jaxws:server Element

Overview

The jaxws:server element is an element for configuring JAX-WS service providers. It injects the configuration information into the org.apache.cxf.jaxws.support.JaxWsServerFactoryBean. This is a Apache CXF specific object. If you are using a pure Spring approach to building your services, you will not be forced to use Apache CXF specific APIs to interact with the service.

The attributes and children of the jaxws:server element specify all of the information needed to instantiate a service provider. The attributes specify the information that is required to instantiate an endpoint. The children are used to configure interceptors and other advanced features.

Identifying the endpoint being configured

In order for the runtime to apply the configuration to the proper service provider, it must be able to identify it. The basic means for identifying a service provider is to specify the class that implements the endpoint. This is done using the jaxws:server element’s serviceBean attribute.

For instances where different endpoint’s share a common implementation, it is possible to provide different configuration for each endpoint. There are two approaches for distinguishing a specific endpoint in configuration:

  • a combination of the serviceName attribute and the endpointName attribute

    The serviceName attribute specifies the wsdl:service element defining the service’s endpoint. The endpointName attribute specifies the specific wsdl:port element defining the service’s endpoint. Both attributes are specified as QNames using the format ns:name. ns is the namespace of the element and name is the value of the element’s name attribute.

    Note

    If the wsdl:service element only has one wsdl:port element, the endpointName attribute can be omitted.

  • the name attribute

    The name attribute specifies the QName of the specific wsdl:port element defining the service’s endpoint. The QName is provided in the format {ns}localPart. ns is the namespace of the wsdl:port element and localPart is the value of the wsdl:port element’s name attribute.

Attributes

The attributes of the jaxws:server element configure the basic properties of the endpoint. These properties include the address of the endpoint, the class that implements the endpoint, and the bus that hosts the endpoint.

Table 17.2, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:server Element” describes the attribute of the jaxws:server element.

Table 17.2. Attributes for Configuring a JAX-WS Service Provider Using the jaxws:server Element

AttributeDescription

id

Specifies a unique identifier that other configuration elements can use to refer to the endpoint.

serviceBean

Specifies the class implementing the service. You can specify the implementation class using either the class name or an ID reference to a Spring bean configuring the implementation class. This class must be on the classpath.

serviceClass

Specifies the class implementing the service. This attribute is useful when the value provided to the implementor attribute is a reference to a bean that is wrapped using Spring AOP.

address

Specifies the address of an HTTP endpoint. This value will override the value specified in the services contract.

wsdlLocation

Specifies the location of the endpoint’s WSDL contract. The WSDL contract’s location is relative to the folder from which the service is deployed.

endpointName

Specifies the value of the service’s wsdl:port element’s name attribute. It is specified as a QName using the format ns:name, where ns is the namespace of the wsdl:port element.

serviceName

Specifies the value of the service’s wsdl:service element’s name attribute. It is specified as a QName using the format ns:name, where ns is the namespace of the wsdl:service element.

publish

Specifies if the service should be automatically published. If this is set to false, the developer must explicitly publish the endpointas described in Chapter 31, Publishing a Service.

bus

Specifies the ID of the Spring bean configuring the bus used to manage the service endpoint. This is useful when configuring several endpoints to use a common set of features.

bindingId

Specifies the ID of the message binding the service uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs.

name

Specifies the stringified QName of the service’s wsdl:port element. It is specified as a QName using the format {ns}localPart, where ns is the namespace of the wsdl:port element and localPart is the value of the wsdl:port element’s name attribute.

abstract

Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is false. Setting this to true instructs the bean factory not to instantiate the bean.

depends-on

Specifies a list of beans that the endpoint depends on being instantiated before the endpoint can be instantiated.

createdFromAPI

Specifies that the user created that bean using Apache CXF APIs, such as Endpoint.publish() or Service.getPort().

The default is false.

Setting this to true does the following:

  • Changes the internal name of the bean by appending .jaxws-endpoint to its id
  • Makes the bean abstract

In addition to the attributes listed in Table 17.2, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:server Element”, you might need to use multiple xmlns:shortName attributes to declare the namespaces used by the endpointName and serviceName attributes.

Example

Example 17.4, “Simple JAX-WS Server Configuration” shows the configuration for a JAX-WS endpoint that specifies the address where the endpoint is published.

Example 17.4. Simple JAX-WS Server Configuration

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:server id="exampleServer"
                  serviceBean="org.apache.cxf.example.DemoImpl"
                  address="http://localhost:8080/demo" />
</beans>

17.1.4. Adding Functionality to Service Providers

Overview

The jaxws:endpoint and the jaxws:server elements provide the basic configuration information needed to instantiate a service provider. To add functionality to your service provider or to perform advanced configuration you must add child elements to the configuration.

Child elements allow you to do the following:

Elements

Table 17.3, “Elements Used to Configure JAX-WS Service Providers” describes the child elements that jaxws:endpoint supports.

Table 17.3. Elements Used to Configure JAX-WS Service Providers

ElementDescription

jaxws:handlers

Specifies a list of JAX-WS Handler implementations for processing messages. For more information on JAX-WS Handler implementations see Chapter 43, Writing Handlers.

jaxws:inInterceptors

Specifies a list of interceptors that process inbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:inFaultInterceptors

Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:outInterceptors

Specifies a list of interceptors that process outbound replies. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:outFaultInterceptors

Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:binding

Specifies a bean configuring the message binding used by the endpoint. Message bindings are configured using implementations of the org.apache.cxf.binding.BindingFactory interface.[a]

jaxws:dataBinding [b]

Specifies the class implementing the data binding used by the endpoint. This is specified using an embedded bean definition.

jaxws:executor

Specifies a Java executor that is used for the service. This is specified using an embedded bean definition.

jaxws:features

Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans.

jaxws:invoker

Specifies an implementation of the org.apache.cxf.service.Invoker interface used by the service. [c]

jaxws:properties

Specifies a Spring map of properties that are passed along to the endpoint. These properties can be used to control features like enabling MTOM support.

jaxws:serviceFactory

Specifies a bean configuring the JaxWsServiceFactoryBean object used to instantiate the service.

[a] The SOAP binding is configured using the soap:soapBinding bean.
[b] The jaxws:endpoint element does not support the jaxws:dataBinding element.
[c] The Invoker implementation controls how a service is invoked. For example, it controls whether each request is handled by a new instance of the service implementation or if state is preserved across invocations.

17.1.5. Enable Schema Validation on a JAX-WS Endpoint

Overview

You can set the schema-validation-enabled property to enable schema validation on a jaxws:endpoint element or on a jaxws:server element. When schema validation is enabled, the messages sent between client and server are checked for conformity to the schema. By default, schema validation is turned off, because it has a significant impact on performance.

Example

To enable schema validation on a JAX-WS endpoint, set the schema-validation-enabled property in the jaxws:properties child element of the jaxws:endpoint element or of the jaxws:server element. For example, to enable schema validation on a jaxws:endpoint element: 

<jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort"
    wsdlLocation="wsdl/hello_world.wsdl"
    createdFromAPI="true">
    <jaxws:properties>
        <entry key="schema-validation-enabled" value="BOTH" />
    </jaxws:properties>
</jaxws:endpoint>

For the list of allowed values of the schema-validation-enabled property, see Section 24.3.4.7, “Schema Validation Type Values”.

17.2. Configuring Consumer Endpoints

Overview

JAX-WS consumer endpoints are configured using the jaxws:client element. The element’s attributes provide the basic information necessary to create a consumer.

To add other functionality, like WS-RM, to the consumer you add children to the jaxws:client element. Child elements are also used to configure the endpoint’s logging behavior and to inject other properties into the endpoint’s implementation.

Basic Configuration Properties

The attributes described in Table 17.4, “Attributes Used to Configure a JAX-WS Consumer” provide the basic information necessary to configure a JAX-WS consumer. You only need to provide values for the specific properties you want to configure. Most of the properties have sensible defaults, or they rely on information provided by the endpoint’s contract.

Table 17.4. Attributes Used to Configure a JAX-WS Consumer

AttributeDescription

address

Specifies the HTTP address of the endpoint where the consumer will make requests. This value overrides the value set in the contract.

bindingId

Specifies the ID of the message binding the consumer uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs.

bus

Specifies the ID of the Spring bean configuring the bus managing the endpoint.

endpointName

Specifies the value of the wsdl:port element’s name attribute for the service on which the consumer is making requests. It is specified as a QName using the format ns:name, where ns is the namespace of the wsdl:port element.

serviceName

Specifies the value of the wsdl:service element’s name attribute for the service on which the consumer is making requests. It is specified as a QName using the format ns:name where ns is the namespace of the wsdl:service element.

username

Specifies the username used for simple username/password authentication.

password

Specifies the password used for simple username/password authentication.

serviceClass

Specifies the name of the service endpoint interface(SEI).

wsdlLocation

Specifies the location of the endpoint’s WSDL contract. The WSDL contract’s location is relative to the folder from which the client is deployed.

name

Specifies the stringified QName of the wsdl:port element for the service on which the consumer is making requests. It is specified as a QName using the format {ns}localPart, where ns is the namespace of the wsdl:port element and localPart is the value of the wsdl:port element’s name attribute.

abstract

Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is false. Setting this to true instructs the bean factory not to instantiate the bean.

depends-on

Specifies a list of beans that the endpoint depends on being instantiated before it can be instantiated.

createdFromAPI

Specifies that the user created that bean using Apache CXF APIs like Service.getPort().

The default is false.

Setting this to true does the following:

  • Changes the internal name of the bean by appending .jaxws-client to its id
  • Makes the bean abstract

In addition to the attributes listed in Table 17.4, “Attributes Used to Configure a JAX-WS Consumer”, it might be necessary to use multiple xmlns:shortName attributes to declare the namespaces used by the endpointName and the serviceName attributes.

Adding functionality

To add functionality to your consumer or to perform advanced configuration, you must add child elements to the configuration.

Child elements allow you to do the following:

Table 17.5, “Elements For Configuring a Consumer Endpoint” describes the child element’s you can use to configure a JAX-WS consumer.

Table 17.5. Elements For Configuring a Consumer Endpoint

ElementDescription

jaxws:binding

Specifies a bean configuring the message binding used by the endpoint. Message bindings are configured using implementations of the org.apache.cxf.binding.BindingFactory interface.[a]

jaxws:dataBinding

Specifies the class implementing the data binding used by the endpoint. You specify this using an embedded bean definition. The class implementing the JAXB data binding is org.apache.cxf.jaxb.JAXBDataBinding.

jaxws:features

Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans.

jaxws:handlers

Specifies a list of JAX-WS Handler implementations for processing messages. For more information in JAX-WS Handler implementations see Chapter 43, Writing Handlers.

jaxws:inInterceptors

Specifies a list of interceptors that process inbound responses. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:inFaultInterceptors

Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:outInterceptors

Specifies a list of interceptors that process outbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:outFaultInterceptors

Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”.

jaxws:properties

Specifies a map of properties that are passed to the endpoint.

jaxws:conduitSelector

Specifies an org.apache.cxf.endpoint.ConduitSelector implementation for the client to use. A ConduitSelector implementation will override the default process used to select the Conduit object that is used to process outbound requests.

[a] The SOAP binding is configured using the soap:soapBinding bean.

Example

Example 17.5, “Simple Consumer Configuration” shows a simple consumer configuration.

Example 17.5. Simple Consumer Configuration

<beans ...
  xmlns:jaxws="http://cxf.apache.org/jaxws"
  ...
  schemaLocation="...
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd
    ...">
  <jaxws:client id="bookClient"
                serviceClass="org.apache.cxf.demo.BookClientImpl"
                address="http://localhost:8080/books"/>
  ...
</beans>

Enable schema validation on a JAX-WS consumer

To enable schema validation on a JAX-WS consumer, set the schema-validation-enabled property in the jaxws:properties child element of the jaxws:client element—for example: 

<jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort"
    createdFromAPI="true">
    <jaxws:properties>
        <entry key="schema-validation-enabled" value="BOTH" />
    </jaxws:properties>
</jaxws:client>

For the list of allowed values of the schema-validation-enabled property, see Section 24.3.4.7, “Schema Validation Type Values”.