Chapter 15. Configuring JAX-WS Endpoints
Abstract
jaxws:client
element. For service providers you can use either the jaxws:endpoint
element or the jaxws:server
element.
15.1. Configuring Service Providers
15.1.1. Elements for Configuring Service Providers
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.
15.1.2. Using the jaxws:endpoint Element
Overview
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
jaxws:endpoint
element's implementor
attribute.
- a combination of the
serviceName
attribute and theendpointName
attributeTheserviceName
attribute specifies thewsdl:service
element defining the service's endpoint. TheendpointName
attribute specifies the specificwsdl:port
element defining the service's endpoint. Both attributes are specified as QNames using the formatns:name
. ns is the namespace of the element and name is the value of the element'sname
attribute.NoteIf thewsdl:service
element only has onewsdl:port
element, theendpointName
attribute can be omitted. - the
name
attributeThename
attribute specifies the QName of the specificwsdl:port
element defining the service's endpoint. The QName is provided in the format{ns}localPart
. ns is the namespace of thewsdl:port
element and localPart is the value of thewsdl:port
element'sname
attribute.
Attributes
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.
jaxws:endpoint
element.
Table 15.1. Attributes for Configuring a JAX-WS Service Provider Using the jaxws:endpoint Element
Attribute | Description |
---|---|
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 endpoint as 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 Appendix C, 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:
|
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. |
xmlns:shortName
attributes to declare the namespaces used by the endpointName
and serviceName
attributes.
Example
Example 15.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>
serviceName
attribute.
Example 15.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>
xmlns:samp
attribute specifies the namespace in which the WSDL service
element is defined.
15.1.3. Using the jaxws:server Element
Overview
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.
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
jaxws:server
element's serviceBean
attribute.
- a combination of the
serviceName
attribute and theendpointName
attributeTheserviceName
attribute specifies thewsdl:service
element defining the service's endpoint. TheendpointName
attribute specifies the specificwsdl:port
element defining the service's endpoint. Both attributes are specified as QNames using the formatns:name
. ns is the namespace of the element and name is the value of the element'sname
attribute.NoteIf thewsdl:service
element only has onewsdl:port
element, theendpointName
attribute can be omitted. - the
name
attributeThename
attribute specifies the QName of the specificwsdl:port
element defining the service's endpoint. The QName is provided in the format{ns}localPart
. ns is the namespace of thewsdl:port
element and localPart is the value of thewsdl:port
element'sname
attribute.
Attributes
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.
jaxws:server
element.
Table 15.2. Attributes for Configuring a JAX-WS Service Provider Using the jaxws:server Element
Attribute | Description |
---|---|
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 endpoint as 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 Appendix C, 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:
|
xmlns:shortName
attributes to declare the namespaces used by the endpointName
and serviceName
attributes.
Example
Example 15.3. 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>
15.1.4. Adding Functionality to Service Providers
Overview
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.
Elements
jaxws:endpoint
supports.
Table 15.3. Elements Used to Configure JAX-WS Service Providers
Element | Description |
---|---|
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.
[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.
|