Red Hat Training

A Red Hat training course is available for JBoss Enterprise SOA Platform

Chapter 6. Configuring Web Services

6.1. Web Service

A web service is a way of making two applications communicate over the web. A web service consists of a set of tools to achieve this aim. There are two types of web service: REST-compliant ones, (the purpose of which is to manipulate XML representations of web resources) and arbitrary Web services (through which the service can expose any operation).

6.2. Web Service End-Point

A web service end-point is software that implements a web service. They are used to implement message-based communication between web services in a service-oriented architectural environment.
The external applications to which these registry entries point can include .NET programs, other external Java-based application servers and LAMP software bundles.

6.3. Web Services Description Language (WSDL)

The Web Services Description Language (WSDL) is an XML-based language that is used to define Web service interfaces. An application that consumes a Web service parses the service’s WSDL document to discover the:
  • location of the service
  • the operations that the service supports
  • the protocol bindings the service supports (SOAP, HTTP, etc)
  • access procedure
For each operation, the WSDL describes the interface format to which the client must adhere.

6.4. Web Service Stack

The web service stack is a layer of software. Its role is to make web services available to BPEL processes.

6.5. Java API for XML Web Services (JAX-WS)

The Java API for XML Web Services (JAX-WS) is a Java API that allows you to create web services. The JAX-WS handler mechanism is used by the web service to invoke a user-specified class whenever a message (or fault) is sent or received. The handler is therefore installed in the message pipeline and used to manipulate the message header or body as required.

6.6. JAX-WS Handlers and BPEL

BPEL integrates with JBossWS through the JAX-WS API. This allows BPEL to support both the JBossWS native and Apache CXF web service stacks. Normally you install handlers either programmatically or through a HandlerChain annotation on the Java interface representing the web service. However, in the case of a process deployed to BPEL, the JAX-WS service is created dynamically upon deployment.

6.7. Configure a JAX-WS Handler for BPEL

Procedure 6.1. Task

  1. Navigate to where you have placed your BPEL process definition and deployment descriptor.
  2. Create a file called jws_handler.xml: vi jws_handler.xml.
  3. Add your configuration settings to the file. Here is an example pertaining to the bpel_service_handler quickstart:
    <handler-chains xmlns="http://java.sun.com/xml/ns/javaee" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee">
        <handler-chain>
      <handler>
       <handler-name>JAXWSHandler</handler-name>
       <handler-class>org.jboss.soa.bpel.examples.jaxws.JAXWSHandler</handler-class>
       <init-param>
           <param-name>TestParam</param-name>
           <param-value>TestValue</param-value>
       </init-param>
      </handler>
        </handler-chain>
    </handler-chains>
    
    This file is in the standard JAX-WS handler chain configuration format. One or more handler elements can be specified, with each handler defining a name and a class. (The handler configuration can optionally provide initialization parameters that are passed to the handler implementation's init method).
  4. Save the file and exit.

    Note

    This mechanism only installs JAX-WS handlers on the provider web service. At present, you cannot configure JAX-WS handlers for the client end-points that are used to invoke external web services from a BPEL process.

    Note

    To learn more, study the example of this mechanism that is provided with the service_handler quick start.

6.8. jws_handler.xml

jws_handler.xml is an XML-based configuration file for the JAX-WS API.

6.9. Apache CXF

Apache CXF is an open source framework for developing service-oriented architectures (SOAs). CXF helps you build and develop services using frontend programming APIs, like JAX-WS and JAX-RS. These services can use a variety of protocols such as SOAP, XML/HTTP, RESTful HTTP, or CORBA and work over a variety of transports such as HTTP, JMS or JBI.
For more information about CXF, refer to http://cxf.apache.org/docs/.

6.10. Configure Apache CXF for Use as a Server End-Point

Prerequisites

  • Apache CXF

Procedure 6.2. Task

  1. Navigate to the directory containing the BPEL deployment descriptor.
  2. Create a file called jbossws-cxf.xml: vi jbossws-cxf.xml
  3. Add your configuration settings to the file. Here is an example:
     
    <beans
      xmlns='http://www.springframework.org/schema/beans'
      xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
      xmlns:beans='http://www.springframework.org/schema/beans'
      xmlns:jaxws='http://cxf.apache.org/jaxws'
      xsi:schemaLocation='http://cxf.apache.org/core
        http://cxf.apache.org/schemas/core.xsd
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
        http://cxf.apache.org/jaxws
        http://cxf.apache.org/schemas/jaxws.xsd'>
      
      <bean id="UsernameTokenSign_Request"
         class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor">
        <constructor-arg>
          <map>
            <entry key="action" value="UsernameToken Timestamp Signature"/> 
            <entry key="passwordType" value="PasswordDigest"/>
         <entry key="user" value="serverx509v1"/>
            <entry key="passwordCallbackClass"
              value="org.jboss.test.ws.jaxws.samples.wsse.ServerUsernamePasswordCallback"/> 
            <entry key="signaturePropFile" value="etc/Server_SignVerf.properties"/>
            <entry key="signatureKeyIdentifier" value="DirectReference"/>
          </map>
        </constructor-arg>
      </bean>
      
      <bean id="UsernameTokenSign_Response"
         class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor">
        <constructor-arg>
          <map>
            <entry key="action" value="UsernameToken Timestamp Signature"/> 
            <entry key="passwordType" value="PasswordText"/>
         <entry key="user" value="serverx509v1"/>
            <entry key="passwordCallbackClass"
              value="org.jboss.test.ws.jaxws.samples.wsse.ServerUsernamePasswordCallback"/> 
            <entry key="signaturePropFile" value="etc/Server_Decrypt.properties"/>
            <entry key="signatureKeyIdentifier" value="DirectReference"/>
            <entry key="signatureParts"
              value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body"/>
          </map>
        </constructor-arg>
      </bean>
    
      <jaxws:endpoint
        id='SecureHelloWorldWS'
        address='http://@jboss.bind.address@:8080/Quickstart_bpel_secure_serviceWS'
        implementor='@provider@'>
        <jaxws:inInterceptors>
            <ref bean="UsernameTokenSign_Request"/>
            <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/>
        </jaxws:inInterceptors>
        <jaxws:outInterceptors>
            <ref bean="UsernameTokenSign_Response"/>
            <bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/>
        </jaxws:outInterceptors>
      </jaxws:endpoint>
      
      
    </beans>
    
    This example code configures the web service to use the username token in conjunction with digital signature authentication.

    Note

    The jaxws:endpoint element has an attribute called implementor. This attribute defines the Java class implementing the JAX-WS service. The BPEL Console dynamically creates this class automatically. Therefore, it is important that the attribute is set to the value @provider@ or it will not work.
  4. Save the file and exit.

6.11. jbossws-cxf.xml

jbossws-cxf.xml is a user-created XML-based configuration file is a user-created file. It should be placed in a project's /WEB-INF/ folder alongside the deployment descriptor. Use it to configure Apache CXF as a server end-point. It is also used by jbossws-cxf when deploying a web service based on the use of JAX-WS annotations.

6.12. Deployment Descriptor

A deployment descriptor is an XML-based configuration file for a deployable system artifact. it describes how and where the artifact is to be deployed. You can specify various options and security settings in this file.

6.13. jbossws-cxf-portname_local_part.xml

The various configuration settings for client end-points representing BPEL-invoked web services are currently distributed amongst different files on a per-port basis.
These files adhere to this naming convention: jbossws-cxf-{portname_local_part}.xml, whereby portname_local_part represents the local part of the port name of the web service being invoked.

6.14. Example of WSDL for an Apache CXF Client End-Point

<definitions name='SecureHelloWorldWSService'
  targetNamespace='http://secure_invoke/helloworld' .... >
    <portType name='SecureHelloWorld'>
        ...
    </portType>
    <service name='SecureHelloWorldWSService'>
       <port name='SecureHelloWorldPort' ... >
           ...
       </port>
    </service>
</definitions>

6.15. Configure Apache CXF for Use as a Client End-Point

Prerequisites

  • Apache CXF

Procedure 6.3. Task

  1. To edit the sample jbossws-cxf-SecureHelloWorldPort.xml CXF configuration file, issue this command: vi SOA_ROOT/jboss-as/samples/quickstarts/bpel_secure_invoke/bpelContent/jbossws-cxf-SecureHelloWorldPort.xml
  2. The configuration information contained within this file is for the CXF bus. Edit the file like this:
    <beans xmlns="http://www.springframework.org/schema/beans"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cxf="http://cxf.apache.org/core"
           xmlns:wsa="http://cxf.apache.org/ws/addressing"
           xmlns:http="http://cxf.apache.org/transports/http/configuration"
           xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
           xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager"
        xmlns:beans='http://www.springframework.org/schema/beans'
        xmlns:jaxws='http://cxf.apache.org/jaxws'
        xmlns:ns1='http://secure_invoke/helloworld'
           xsi:schemaLocation="
           http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd
           http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd
           http://schemas.xmlsoap.org/ws/2005/02/rm/policy http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd
           http://cxf.apache.org/ws/rm/manager http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd
           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">
    
      <bean id="UsernameTokenSign_Request"
         class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" >
        <constructor-arg>
          <map>
            <entry key="action" value="UsernameToken Timestamp Signature"/> 
            <entry key="passwordType" value="PasswordDigest"/>
      <entry key="user" value="clientx509v1"/>
            <entry key="passwordCallbackClass"
              value="org.jboss.test.ws.jaxws.samples.wsse.ClientUsernamePasswordCallback"/> 
            <entry key="signaturePropFile" value="etc/Client_Sign.properties"/>
            <entry key="signatureKeyIdentifier" value="DirectReference"/>
            <entry key="signatureParts"
              value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body"/>
          </map>
        </constructor-arg>
      </bean>
      
      <bean id="UsernameTokenSign_Response" 
         class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" >
        <constructor-arg>
          <map>
            <entry key="action" value="UsernameToken Timestamp Signature"/> 
            <entry key="passwordType" value="PasswordText"/>
         <entry key="user" value="serverx509v1"/>
            <entry key="passwordCallbackClass" 
              value="org.jboss.test.ws.jaxws.samples.wsse.ClientUsernamePasswordCallback"/> 
            <entry key="signaturePropFile" value="etc/Client_Encrypt.properties"/>
            <entry key="signatureKeyIdentifier" value="DirectReference"/>
          </map>
        </constructor-arg>
      </bean>
      
      <cxf:bus>
        <cxf:outInterceptors>
            <ref bean="UsernameTokenSign_Request"/>
            <bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/>
        </cxf:outInterceptors>
        <cxf:inInterceptors>
            <ref bean="UsernameTokenSign_Response"/>
            <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/>
        </cxf:inInterceptors>
      </cxf:bus>
    
    </beans>
    
    These settings configure the web service client to utilise the username token and digital signature authentication.
  3. Save the file and exit.

6.16. BPEL Processes and Web Services

When you deploy a BPEL process, a web service is automatically created. This web service represents the service end-point and it is based on the WSDL description that is bundled with the process that is being deployed.

6.17. Display a WSDL

Procedure 6.4. Task

  1. Look up the end-point URL of the service which has the "?wsdl" suffix.
  2. Once it is displayed, the <soap:address> will, by default, become associated with the server's "host bind" address.

    Note

    This address is defined in the ${jboss.bind.address} property.

6.18. Configure a BPEL Client End-Point to Invoke a Secure External Web Service

Procedure 6.5. Task

  1. Launch your test editor and create a new file.
  2. Add the relative locations of the key-store and trust-store files.
  3. Save the file as jboss-wsse-client.xml in the top level directory alongside your BPEL process and exit.

    Note

    For more information, see the secure_invoke_native quickstart.

6.19. Configure a BPEL Server End-Point to Provide a Secure Web Service

Procedure 6.6. Task

  1. Launch your test editor and create a new file.
  2. Add the relative locations of the key-store and trust-store files.
  3. Save the file as jboss-wsse-server.xml in the top level directory alongside your BPEL process and exit.

    Note

    For more information, see the secure_service_native quickstart.