Red Hat Training

A Red Hat training course is available for Red Hat Fuse

9.2. Bindings

The Service Component Architecture (SCA) binding provides a means by which SwitchYard services and SwitchYard-aware clients communicate with one another. It facilitates inter-application communication within a SwitchYard runtime and provides clustering of SwitchYard services in two or more SwitchYard instances.
This section provides details on the out of the box gateway bindings provided with the SwitchYard application.

9.2.1. SOAP

The SOAP component in SwitchYard provides SOAP-based web service binding support for services and references.
Note
More information about incorporating WS-Security is available in this guide.

9.2.1.1. Binding Services with SOAP

You can expose composite-level services as a SOAP-based web service using the
<binding.soap>
binding definition. The following configuration options are available:
wsdl
This is the location of the WSDL used to describe the web service endpoint. A relative path can be used if the WSDL is included in the deployed application. If the WSDL is located outside the application, then you can use a file: or http: URL.
socketAddr
This is the IP Socket Address to be used. The value can be in the form of hostName/ipAddress:portNumber, hostName/ipAddress or :portNumber.
wsdlPort
This is the port name in the WSDL to use. If you leave it unspecified, the first port definition in the WSDL is used for the service endpoint.
contextPath
This is an additional context path for the SOAP endpoint. (The default is none.)
Note
By default, the JBossWS-CXF stack is enabled on JBoss EAP, so the socketAddr parameter is ignored. However, this parameter can be used for standalone usage.

Example 9.1. Sample SOAP Service Binding

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:service name="OrderService" promote="OrderService">
        <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:socketAddr>:9000</soap:socketAddr>        
         </soap:binding.soap>
    </sca:service>
</sca:composite>

9.2.1.2. Binding References with SOAP

You can bind references with SOAP to make SOAP-based web services available to SwitchYard services. The following configuration options are available:
wsdl
This is the location of the WSDL used to describe the web service endpoint. A relative path can be used if the WSDL is included in the deployed application. (If the WSDL is located outside the application, then you can use a file: or http: URL.)
wsdlPort
This is the port name in the WSDL to use. If you leave it unspecified, the first port definition in the WSDL is used for the service endpoint.
endpointAddress
This SOAP endpoint address overrides the address specified in the WSDL. This is an optional property. If you do not specify it, the endpoint address specified in the WSDL is used instead.
timeout
This is the requests timeout value in milliseconds.
proxy
This is the HTTP Proxy settings for the endpoint.
basic/ntlm
This is the authentication configuration for the endpoint.

Example 9.2. Sample SOAP Reference Binding

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
         <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:endpointAddress></soap:endpointAddress>
         </soap:binding.soap>
    </sca:reference>
</sca:composite>
9.2.1.2.1. Proxy Configuration
If you need the SOAP reference to pass through a proxy server, then provide the proxy server configuration using the proxy element. The following configuration options are available:
  • type : The proxy type. This can be HTTP or SOCKS. The default is HTTP.
  • host : The proxy host.
  • port : The proxy port (optional).
  • user : The proxy user (optional).
  • password : The proxy password (optional).

Example 9.3. Sample SOAP Proxy Configuration

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
        <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:endpointAddress>[</soap:endpointAddress>
            <soap:proxy>
                <soap:type>HTTP</soap:type>
                <soap:host>192.168.1.2</soap:host>
                <soap:port>9090</soap:port>
                <soap:user>user</soap:user>
                <soap:password>password</soap:password>
            </soap:proxy>
        </soap:binding.soap>
    </sca:reference>
</sca:composite>
9.2.1.2.2. Authentication Configuration
If the SOAP reference endpoint is secured using BASIC or NTLM, then you can provide the authentication configuration using the BASIC or NTLM elements. The following configuration options are available:
  • user : The user name.
  • password : The password.
  • host : The authentication host (optional).
  • port : The authentication port (optional).
  • realm : The authentication realm (optional, applicable only for BASIC).
  • domain: The Windows domain for authentication (optional, applicable only for NTLM).

Example 9.4. Sample NTLM Authentication Configuration

<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
        <soap:binding.soap>
            <soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
            <soap:endpointAddress>[</soap:endpointAddress>
            <soap:ntlm>
                <soap:user>user</soap:user>
                <soap:password>password</soap:password>
                <soap:domain>domain</soap:domain>
            </soap:ntlm>
        </soap:binding.soap>
    </sca:reference>
</sca:composite>

9.2.1.3. Enabling SOAP Message Logging for SOAP Binding

To log inbound and outbound SOAP messages on SOAP binding, turn on DEBUG level logging for switchyard.component.soap.InboundHandler and switchyard.component.soap.OutboundHandler.
  • Add the following to EAP_HOME/standalone/configuration/standalone.xml:
    <logger category="org.switchyard.component.soap.InboundHandler">
        <level name="DEBUG" />
    </logger>
    <logger category="org.switchyard.component.soap.OutboundHandler">
        <level name="DEBUG" />
    </logger>

9.2.1.4. WS-Security

9.2.1.4.1. Enable WS-Security

Procedure 9.1. Enable WS-Security

  1. Define a Policy within your WSDL and reference it with a PolicyReference inside your binding.
  2. Configure your <soap.binding> with an <endpointConfig> to ensure that JBossWS-CXF is configured appropriately.
  3. Configure your <soap.binding> with an <inInterceptors> section, including the appropriate JBossWS-CXF <interceptor> to handle incoming SOAP requests.
  4. Include a WEB-INF/jboss-web.xml file in your application with a <security-domain> specified, so that JBossWS-CXF knows which modules to use for authentication and role mapping.
9.2.1.4.2. Sample WS-Security Configurations
JBoss Fuse provides the policy-security-wss-username quickstart application as an example. The following are the pertinent sections:
  • META-INF/WorkService.wsdl:
    <binding name="WorkServiceBinding" type="tns:WorkService">
      <wsp:PolicyReference URI="#WorkServicePolicy"/>
      ...
    </binding>
    <wsp:Policy wsu:Id="WorkServicePolicy">
      <wsp:ExactlyOne>
        <wsp:All>
          <sp:SupportingTokens xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
            <wsp:Policy>
              <sp:UsernameToken sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                <wsp:Policy>
                  <sp:WssUsernameToken10/>
                </wsp:Policy>
              </sp:UsernameToken>
            </wsp:Policy>
          </sp:SupportingTokens>
        </wsp:All>
      </wsp:ExactlyOne>
    </wsp:Policy>
  • META-INF/switchyard.xml:
    <binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
      <wsdl>META-INF/WorkService.wsdl</wsdl>
      <contextPath>policy-security-wss-username</contextPath>
      <endpointConfig configFile="META-INF/jaxws-endpoint-config.xml" configName="SwitchYard-Endpoint-Config"/>
      <inInterceptors>
        <interceptor class="org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingPolicyInterceptor"/>
      </inInterceptors>
    </binding.soap>
  • META-INF/jaxws-endpoint-config.xml:
    <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
      <endpoint-config>
        <config-name>SwitchYard-Endpoint-Config</config-name>
        <property>
            <property-name>ws-security.validate.token</property-name>
            <property-value>false</property-value>
        </property>
      </endpoint-config>
    </jaxws-config>
  • WEB-INF/jboss-web.xml:
    <jboss-web>
        <security-domain>java:/jaas/other</security-domain>
    </jboss-web>
With these in place, JBossWS-CXF intercepts incoming SOAP requests, extract the UsernameToken, attempt to authenticate it against the LoginModule(s) configured in the application server's "other" security domain, and provide any authorized roles. If successful, the request is handed over to SwitchYard, which processes it further, including enforcing your own policies. In the case of WS-Security, SwitchYard does not attempt a second clientAuthentication, but instead respects the outcome from JBossWS-CXF.
Note
If the original clientAuthentication fails, this is a "fail-fast" scenario, and the request is not channeled into SwitchYard.
9.2.1.4.3. Signature and Encryption Support
To setup WS-Security encryption, ensure the following:
For example:
META-INF/switchyard.xml
<binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
  <wsdl>META-INF/WorkService.wsdl</wsdl>
  <contextPath>policy-security-wss-username</contextPath>
  <endpointConfig configFile="META-INF/jaxws-endpoint-config.xml" configName="SwitchYard-Endpoint-Config">
</binding.soap>
META-INF/jaxws-endpoint-config.xml
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:javaee="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>SwitchYard-Endpoint-Config</config-name>
    <property>
      <property-name>ws-security.callback-handler</property-name>
      <property-value>org.switchyard.quickstarts.demo.policy.security.wss.signencrypt.WorkServiceCallbackHandler</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.properties</property-name>
      <property-value>META-INF/bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.encryption.username</property-name>
      <property-value>alice</property-value>
    </property>
    <property>
      <property-name>ws-security.signature.properties</property-name>
      <property-value>META-INF/bob.properties</property-value>
    </property>
    <property>
      <property-name>ws-security.signature.username</property-name>
      <property-value>bob</property-value>
    </property>
  </endpoint-config>
</jaxws-config>
META-INF/bob.properties
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.alias=bob
org.apache.ws.security.crypto.merlin.file=META-INF/bob.jks
9.2.1.4.3.1. Sample Endpoint Configurations
An endpoint declares all the abstract methods that are exposed to the client. You can use endpoint configurations to include property declarations. The endpoint implementations can be associated with a given endpoint configuration using the @EndpointConfig annotation. The following steps describe a sample endpoint configuration:
  1. Create the web service endpoint using JAX-WS. Use a contract-first approach when using WS-Security as the policies declared in the WSDL are parsed by the Apache CXF engine on both server and client sides. Here is an example of WSDL contract enforcing signature and encryption using X 509 certificates:
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <definitions targetNamespace="http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy" name="SecurityService"
            xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
            xmlns="http://schemas.xmlsoap.org/wsdl/"
            xmlns:wsp="http://www.w3.org/ns/ws-policy"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            xmlns:wsaws="http://www.w3.org/2005/08/addressing"
            xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
      <types>
        <xsd:schema>
          <xsd:import namespace="http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy" schemaLocation="SecurityService_schema1.xsd"/>
        </xsd:schema>
      </types>
      <message name="sayHello">
        <part name="parameters" element="tns:sayHello"/>
      </message>
      <message name="sayHelloResponse">
        <part name="parameters" element="tns:sayHelloResponse"/>
      </message>
      <portType name="ServiceIface">
        <operation name="sayHello">
          <input message="tns:sayHello"/>
          <output message="tns:sayHelloResponse"/>
        </operation>
      </portType>
      <binding name="SecurityServicePortBinding" type="tns:ServiceIface">
        <wsp:PolicyReference URI="#SecurityServiceSignThenEncryptPolicy"/>
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
        <operation name="sayHello">
          <soap:operation soapAction=""/>
          <input>
            <soap:body use="literal"/>
          </input>
          <output>
            <soap:body use="literal"/>
          </output>
        </operation>
      </binding>
      <service name="SecurityService">
        <port name="SecurityServicePort" binding="tns:SecurityServicePortBinding">
          <soap:address location="http://localhost:8080/jaxws-samples-wssePolicy-sign-encrypt"/>
        </port>
      </service>
     
      <wsp:Policy wsu:Id="SecurityServiceSignThenEncryptPolicy" xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:ExactlyOne>
          <wsp:All>
            <sp:AsymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
              <wsp:Policy>
                <sp:InitiatorToken>
                  <wsp:Policy>
                    <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
                      <wsp:Policy>
                        <sp:WssX509V1Token11/>
                      </wsp:Policy>
                      </sp:X509Token>
                  </wsp:Policy>
                </sp:InitiatorToken>
                <sp:RecipientToken>
                  <wsp:Policy>
                    <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
                      <wsp:Policy>
                        <sp:WssX509V1Token11/>
                      </wsp:Policy>
                    </sp:X509Token>
                  </wsp:Policy>
                </sp:RecipientToken>
                <sp:AlgorithmSuite>
                  <wsp:Policy>
                    <sp-cxf:Basic128GCM xmlns:sp-cxf="http://cxf.apache.org/custom/security-policy"/>
                  </wsp:Policy>
                </sp:AlgorithmSuite>
                <sp:Layout>
                  <wsp:Policy>
                    <sp:Lax/>
                  </wsp:Policy>
                </sp:Layout>
                <sp:IncludeTimestamp/>
                <sp:EncryptSignature/>
                <sp:OnlySignEntireHeadersAndBody/>
                <sp:SignBeforeEncrypting/>
              </wsp:Policy>
            </sp:AsymmetricBinding>
            <sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
              <sp:Body/>
            </sp:SignedParts>
            <sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
              <sp:Body/>
            </sp:EncryptedParts>
            <sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
              <wsp:Policy>
                <sp:MustSupportRefIssuerSerial/>
              </wsp:Policy>
            </sp:Wss10>
          </wsp:All>
        </wsp:ExactlyOne>
      </wsp:Policy>
    </definitions>
    
    
    You can generate the service endpoint using the wsconsume tool and then use a @EndpointConfig annotation as shown below:
    
    package org.jboss.test.ws.jaxws.samples.wsse.policy.basic;
     
    import javax.jws.WebService;
    import org.jboss.ws.api.annotation.EndpointConfig;
     
    @WebService
    (
       portName = "SecurityServicePort",
       serviceName = "SecurityService",
       wsdlLocation = "WEB-INF/wsdl/SecurityService.wsdl",
       targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy",
       endpointInterface = "org.jboss.test.ws.jaxws.samples.wsse.policy.basic.ServiceIface"
    )
    @EndpointConfig(configFile = "WEB-INF/jaxws-endpoint-config.xml", configName = "Custom WS-Security Endpoint")
    public class ServiceImpl implements ServiceIface
    {
       public String sayHello()
       {
          return "Secure Hello World!";
       }
    }
    
    
  2. Use the referenced jaxws-endpoint-config.xml descriptor to provide a custom endpoint configuration with the required server side configuration properties as shown below. This tells the engine which certificate or key to use for signature, signature verification, encryption, and decryption.
    
    <?xml version="1.0" encoding="UTF-8"?>
    <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:javaee="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
      <endpoint-config>
        <config-name>Custom WS-Security Endpoint</config-name>
        <property>
          <property-name>ws-security.signature.properties</property-name>
          <property-value>bob.properties</property-value>
        </property>
        <property>
          <property-name>ws-security.encryption.properties</property-name>
          <property-value>bob.properties</property-value>
        </property>
        <property>
          <property-name>ws-security.signature.username</property-name>
          <property-value>bob</property-value>
        </property>
        <property>
          <property-name>ws-security.encryption.username</property-name>
          <property-value>alice</property-value>
        </property>
        <property>
          <property-name>ws-security.callback-handler</property-name>
          <property-value>org.jboss.test.ws.jaxws.samples.wsse.policy.basic.KeystorePasswordCallback</property-value>
        </property>
      </endpoint-config>
    </jaxws-config>
    
    
    Here,
    • The bob.properties configuration file includes the WSS4J Crypto properties which in turn links to the keystore file, type, alias, and password for accessing it. For example:
      
      org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
      org.apache.ws.security.crypto.merlin.keystore.type=jks
      org.apache.ws.security.crypto.merlin.keystore.password=password
      org.apache.ws.security.crypto.merlin.keystore.alias=bob
      org.apache.ws.security.crypto.merlin.keystore.file=bob.jks
      
      
    • The callback handler enables Apache CXF to access the keystore. For example:
      
      package org.jboss.test.ws.jaxws.samples.wsse.policy.basic;
       
      import java.io.IOException;
      import java.util.HashMap;
      import java.util.Map;
      import javax.security.auth.callback.Callback;
      import javax.security.auth.callback.CallbackHandler;
      import javax.security.auth.callback.UnsupportedCallbackException;
      import org.apache.ws.security.WSPasswordCallback;
       
      public class KeystorePasswordCallback implements CallbackHandler {
         private Map<String, String> passwords = new HashMap<String, String>();
       
         public KeystorePasswordCallback() {
            passwords.put("alice", "password");
            passwords.put("bob", "password");
         }
       
         /**
          * It attempts to get the password from the private
          * alias/passwords map.
          */
         public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
            for (int i = 0; i < callbacks.length; i++) {
               WSPasswordCallback pc = (WSPasswordCallback)callbacks[i];
       
               String pass = passwords.get(pc.getIdentifier());
               if (pass != null) {
                  pc.setPassword(pass);
                  return;
               }
            }
         }
       
         /**
          * Add an alias/password pair to the callback mechanism.
          */
         public void setAliasPassword(String alias, String password) {
            passwords.put(alias, password);
         }
      }
      
      
  3. Assuming the bob.jks keystore is properly generated and contains the server Bob's full key as well as the client Alice's public key, you can proceed to packaging the endpoint. Here is the expected content:
     /dati/jbossws/stack/cxf/trunk $ jar -tvf ./modules/testsuite/cxf-tests/target/test-libs/jaxws-samples-wsse-policy-sign-encrypt.war
         0 Thu Jun 16 18:50:48 CEST 2011 META-INF/
       140 Thu Jun 16 18:50:46 CEST 2011 META-INF/MANIFEST.MF
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/
       586 Thu Jun 16 18:50:44 CEST 2011 WEB-INF/web.xml
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/basic/
      1687 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/basic/KeystorePasswordCallback.class
       383 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/basic/ServiceIface.class
      1070 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/basic/ServiceImpl.class
         0 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/jaxws/
       705 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/jaxws/SayHello.class
      1069 Thu Jun 16 18:50:48 CEST 2011 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/policy/jaxws/SayHelloResponse.class
      1225 Thu Jun 16 18:50:44 CEST 2011 WEB-INF/jaxws-endpoint-config.xml
         0 Thu Jun 16 18:50:44 CEST 2011 WEB-INF/wsdl/
      4086 Thu Jun 16 18:50:44 CEST 2011 WEB-INF/wsdl/SecurityService.wsdl
       653 Thu Jun 16 18:50:44 CEST 2011 WEB-INF/wsdl/SecurityService_schema1.xsd
      1820 Thu Jun 16 18:50:44 CEST 2011 WEB-INF/classes/bob.jks
       311 Thu Jun 16 18:50:44 CEST 2011 WEB-INF/classes/bob.properties
    Here, the jaxws classes generated by the tools and a basic web.xml referencing the endpoint bean are also included:
    
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app
       version="2.5" 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 http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
       <servlet>
          <servlet-name>TestService</servlet-name>
          <servlet-class>org.jboss.test.ws.jaxws.samples.wsse.policy.basic.ServiceImpl</servlet-class>
       </servlet>
       <servlet-mapping>
          <servlet-name>TestService</servlet-name>
          <url-pattern>/*</url-pattern>
       </servlet-mapping>
    </web-app>
    
    
    Note
    If you are deploying the endpoint archive to JBoss Application Server 7, add a dependency to org.apache.ws.security module in the MANIFEST.MF file:
    Manifest-Version: 1.0
    Ant-Version: Apache Ant 1.7.1
    Created-By: 17.0-b16 (Sun Microsystems Inc.)
    Dependencies: org.apache.ws.security
9.2.1.4.3.2. Sample Client Configurations
On the client side, use the wsconsume tool to consume the published WSDL and then invoke the endpoint as a standard JAX-WS one as shown below:

QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wssecuritypolicy", "SecurityService");
URL wsdlURL = new URL(serviceURL + "?wsdl");
Service service = Service.create(wsdlURL, serviceName);
ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class);
 
((BindingProvider)proxy).getRequestContext().put(SecurityConstants.CALLBACK_HANDLER, new KeystorePasswordCallback());
((BindingProvider)proxy).getRequestContext().put(SecurityConstants.SIGNATURE_PROPERTIES,
     Thread.currentThread().getContextClassLoader().getResource("META-INF/alice.properties"));
((BindingProvider)proxy).getRequestContext().put(SecurityConstants.ENCRYPT_PROPERTIES,
     Thread.currentThread().getContextClassLoader().getResource("META-INF/alice.properties"));
((BindingProvider)proxy).getRequestContext().put(SecurityConstants.SIGNATURE_USERNAME, "alice");
((BindingProvider)proxy).getRequestContext().put(SecurityConstants.ENCRYPT_USERNAME, "bob");
 
proxy.sayHello();


The WS-Security properties are set in the request context. Here, the KeystorePasswordCallback is same as that on the server side. The alice.properties file is the client side equivalent of the server side bob.properties file and references the alice.jks keystore file, which has been populated with client Alice's full key as well as server Bob's public key:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.alias=alice
org.apache.ws.security.crypto.merlin.keystore.file=META-INF/alice.jks

The Apache CXF WS-Policy engine consumes the security requirements in the contract and ensures that a valid secure communication is in place for interacting with the server endpoint.
9.2.1.4.3.3. Endpoint Serving Multiple Clients
n the endpoint and client configuration examples, the server side configuration implies that the endpoint is configured for serving a given client which a service agreement is established for. In real world scenarios, a server should be able to decrypt and encrypt messages coming from and being sent to multiple clients. Apache CXF supports that through the useReqSigCert value for the ws-security.encryption.username configuration parameter. The referenced server side keystore then needs to contain the public key of all the clients that are expected to be served.
9.2.1.4.4. Sample CXF Interceptor Configurations
For adding a CXF Interceptor, perform the following configuration settings:
  • META-INF/switchyard.xml
    
    <binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
      <wsdl>META-INF/WorkService.wsdl</wsdl>
      <contextPath>policy-security-wss-username</contextPath>
      <inInterceptors>
        <interceptor class="com.example.MyInterceptor"/>
      </inInterceptors>
    </binding.soap>
    
    
  • com/example/MyInterceptor.java
    
    public class MyInterceptor extends WSS4JInterceptor {
      private static final PROPS;
      static {
        Map<String,String> props = new HashMap<String,String>();
        props.put("action", "Signature Encryption");
        props.put("signaturePropFile", "META-INF/bob.properties");
        props.put("decryptionPropFile", "META-INF/bob.properties");
        props.put("passwordCallbackClass", "com.example.MyCallbackHandler");
        PROPS = props;
      }
      public MyInterceptor() {
        super(PROPS);
      }
    }
    
    
  • META-INF/bob.properties
    
    org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
    org.apache.ws.security.crypto.merlin.keystore.type=jks
    org.apache.ws.security.crypto.merlin.keystore.password=password
    org.apache.ws.security.crypto.merlin.keystore.alias=bob
    org.apache.ws.security.crypto.merlin.file=META-INF/bob.jks
    
    

9.2.1.5. Attachments

9.2.1.5.1. SOAP with Attachments
By default, any attachment sent with a SOAP Envelope is passed around in a SwitchYard Message as an attachment. The default SOAPMessageComposer handles this.
9.2.1.5.2. SOAP with MTOM/XOP
To support Message Transmission Optimization Mechanism (MTOM), the underlying stack sends and receives attachments as MIME multipart messages. One additional configuration in SwitchYard that allows you to expand an xop:include's SOAP Message is mtom. When the corresponding xopExpand attribute is set to true, the xop:include element is replaced with the contents from the MIME attachment.

Example 9.5. 

<soap:binding.soap xmlns:soap="urn:switchyard-component-soap:config:1.0">
    <soap:wsdl>Foo.wsdl</soap:wsdl>
    <soap:endpointAddress></soap:endpointAddress>
    <soap:mtom enabled="true" xopExpand="true"/>
</soap:binding.soap>
You can enable MTOM by overriding as shown above, or by using WSDL policy as shown below:
<definitions targetNamespace="urn:switchyard-component-soap:test-ws:1.0" name="ImageService"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="urn:switchyard-component-soap:test-ws:1.0"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
    xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
    xmlns:wsoma="http://www.w3.org/2007/08/soap12-mtom-policy"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
...
    <wsp:Policy wsu:Id="ImageServicePortBinding_policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsoma:MTOM/>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
...
  <binding name="ImageServicePortBinding" type="tns:ImageService">
    <wsp:PolicyReference URI="#ImageServicePortBinding_policy"/>
    <soap:binding transport="http://www.w3.org/2003/05/soap/bindings/HTTP/" style="document"/>
    <operation name="resize">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

9.2.1.6. WS-Addressing

SwitchYard runtime provides support for WS-A (WS-Addressing) through the underlying SOAP stack. To enable WS-A, you can either set a policy or use the UseAdrressing element in the WSDL as shown below:
<definitions targetNamespace="urn:switchyard-component-soap:test-ws:1.0" name="HelloAddressingService"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="urn:switchyard-component-soap:test-ws:1.0"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
...
    <wsp:Policy wsu:Id="HelloSOAPAddressingServicePortBinding_policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsam:Addressing wsdl:required="false">
                    <wsp:Policy/>
                </wsam:Addressing>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
...
  <binding name="HelloSOAPAddressingServicePortBinding" type="tns:HelloAddressingService">
    <wsp:PolicyReference URI="#HelloSOAPAddressingServicePortBinding_policy"/>
    <soap:binding transport="http://www.w3.org/2003/05/soap/bindings/HTTP/" style="document"/>
    <operation name="sayHello">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
...
  <binding name="HelloSOAPAddressingServicePortBinding2" type="tns:HelloAddressingService2">
    <wsaw:UsingAddressing required="true" />
    <soap:binding transport="http://www.w3.org/2003/05/soap/bindings/HTTP/" style="document"/>
    <operation name="sayHello">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

9.2.2. HTTP

9.2.2.1. HTTP Component

The HTTP component in SwitchYard provides HTTP-based binding support for services and references in SwitchYard.

9.2.2.2. Binding Services with HTTP

To expose composite-level services as an HTTP-based service, use the
<binding.http>
binding definition. You can use these configuration options:
operationSelector
This is the specification of the operation to use for the message exchange.
contextPath
This is the context path for the HTTP endpoint.
Here is an example HTTP service binding:
<sca:service name="QuoteService" promote="StockService/QuoteService">
    <http:binding.http>
        <selector:operationSelector operationName="getPrice"/>
        <http:contextPath>http-binding/quote</http:contextPath>
    </http:binding.http>
</sca:service>
Note
Do not edit the SwitchYard.xml file directly. Red Hat recommends using the JBoss Developer Studio SwitchYard Editor to edit the SwitchYard.xmlfile.

9.2.2.3. Binding References with HTTP

When you bind a reference with HTTP, it makes HTTP-based services available to SwitchYard services.
The following configuration options are available to you for binding.http when binding references:
address
This is a URL that points to an HTTP endpoint. It is optional and if you do not specify it, it defaults to http://127.0.0.1:8080/.
method
This is the HTTP method used for invoking the endpoint. (The default is GET.)
contentType
This is the HTTP content type header that must be set on the request.
Here is an example HTTP reference binding:
<sca:reference name="Symbol" promote="StockService/SymbolService" multiplicity="1..1">
    <http:binding.http>
        <http:address>http://localhost:8080/http-binding/symbol</http:address>
        <http:method>POST</http:method>
        <http:contentType>text/plain</http:contentType>
    </http:binding.http>
</sca:reference>

9.2.3. RESTEasy

9.2.3.1. About RESTEasy

RESTEasy is a portable implementation of the JAX-RS Java API. It also provides additional features, including a client side framework (the RESTEasy JAX-RS Client Framework) for mapping outgoing requests to remote servers, allowing JAX-RS to operate as a client or server-side specification.

9.2.3.2. RESTEasy Component

The RESTEasy component provides REST-based binding support for services and references in SwitchYard.

9.2.3.3. Binding Services with RESTEasy

To expose composite-level services as a REST-based service, use the
<binding.rest>
binding definition. The following configuration options are available for binding.rest when you are binding services:
interfaces
This is a comma separated list of interfaces or empty classes with JAX-RS annotations.
contextPath
This is an additional context path for the REST endpoint. (The default is setting is none.)
Here is an example REST service binding:
<sca:service name="OrderService" promote="OrderService/OrderService">
    <rest:binding.rest>
        <rest:interfaces>org.switchyard.quickstarts.rest.binding.OrderResource,org.switchyard.quickstarts.rest.binding.TestResource</rest:interfaces>
        <rest:contextPath>rest-binding</rest:contextPath>
    </rest:binding.rest>
</sca:service>
For more information on RESTEasy Component's REST binding features, refer to the rest-binding quickstart.

9.2.3.4. Binding References with RESTEasy

When you bind a reference with RESTEasy, it makes REST-based services available to SwitchYard services.
The following configuration options are available to you for binding.rest when binding references:
address
This is a URL that points to the root path of resources. This is only applicable for Reference bindings. It is optional and if you do not specify it, it defaults to http://127.0.0.1:8080/.
interfaces
This is a comma-separated list of interfaces or abstract or empty classes with JAX-RS annotations.
contextPath
This is an additional context path for the REST endpoint. (The default is none.)
Here is an example HTTP reference binding. Note the resource URLs start from http://localhost:8080/rest-binding:
<sca:reference name="Warehouse" promote="OrderService/Warehouse" multiplicity="1..1">
    <rest:binding.rest>
        <rest:interfaces>org.switchyard.quickstarts.rest.binding.WarehouseResource</rest:interfaces> 
        <rest:address>http://localhost:8080</rest:address>
        <rest:contextPath>rest-binding</rest:contextPath>
    </rest:binding.rest>
</sca:reference>

9.2.3.5. Proxy Configuration

If the REST reference needs to pass through a proxy server then the proxy server configuration can be provided using the proxy element. The following configuration options are available:
  • host : The proxy host.
  • port : The proxy port (optional).
  • user : The proxy user (optional).
  • password : The proxy password (optional).

Example 9.6. 

<sca:reference name="Warehouse" promote="OrderService/Warehouse" multiplicity="1..1">
    <rest:binding.rest>
        <rest:interfaces>org.switchyard.quickstarts.rest.binding.WarehouseResource</rest:interfaces> 
        <rest:address></rest:address>
        <rest:proxy>
            <rest:host>host</rest:host>
            <rest:port>8090</rest:port>
            <rest:user>Beal</rest:user>
            <rest:password>conjecture</rest:password>
        </rest:proxy>
    </rest:binding.rest>
</sca:reference>

9.2.3.6. Authentication Configuration

If the REST reference endpoint is secured using BASIC/NTLM, then the authentication configuration can be provided using the basic or ntlm elements. The following configuration options are available:
  • user : The authentication user.
    password : The authentication password.
    realm/domain : The authentication realm or the Windows domain.

Example 9.7. Sample NTLM Authentication Configuration

<sca:reference name="Warehouse" promote="OrderService/Warehouse" multiplicity="1..1">
    <rest:binding.rest>
        <rest:interfaces>org.switchyard.quickstarts.rest.binding.WarehouseResource</rest:interfaces> 
        <rest:address></rest:address>
        <rest:ntlm>
            <rest:user>user</rest:user>
            <rest:password>password</rest:password>
            <rest:domain>domain</rest:domain>
        </rest:ntlm>
    </rest:binding.rest>
</sca:reference>

9.2.4. JCA

9.2.4.1. Java Connector Architecture (JCA) Transport

The Java Connector Architecture (JCA) Transport is a Java-based piece of architecture that works as a service integrator. It is a connector that links application servers and enterprise information systems.

9.2.4.2. JCA Adapter

A JCA Adapter provides outbound and inbound connectivity between Enterprise Information Systems (for example, mainframe transaction processing and database systems), application servers, and enterprise applications. It controls the inflow of messages to Message-Driven Beans (MDBs) and the outflow of messages sent from other Java EE components. It also provides a variety of options to fine tune your messaging applications.

9.2.4.3. JCA Gateway

The JCA gateway allows you to send and receive messages to and from EIS by means of the JCA ResourceAdapter.

9.2.4.4. Binding Services with JCA Message Inflow

You can bind composite-level services to an EIS with JCA message inflow using the <binding.jca> binding definition. You require the following configuration options for binding.jca
  • operationSelector: Specification of the service operation used for invoking the message exchange. For more details, see Section 9.4.2, “Types of Operation Selectors”.
  • inboundConnection
    • resourceAdapter
      • @name: Name of the ResourceAdapter archive. Ensure that the resource adapter is deployed on the JBoss application server before you deploy the SwitchYard application which has JCA binding.
    • activationSpec
      • property: Properties for injecting into the ActivationSpec instance. Provide properties that are specific to the ResourceAdapter implementation.
  • inboundInteraction
    • listener: A fully qualified name (FQN) of the listener interface. When you use JMSEndpoint, specify the javax.jms.MessageListener and when you use CCIEndpoint, specify the javax.resource.cci.MessageListener. Otherwise, you may need to specify EIS specific listener interface according to its ResourceAdapter. Also ensure that the endpoint class implements this listener interface.
    • endpoint
      • @type: An FQN of the endpoint implementation class. There are two built-in endpoints namely org.switchyard.component.jca.endpoint.JMSEndpoint and org.switchyard.component.jca.endpoint.CCIEndpoint. These two endpoints have corresponding listeners. If neither JMSEndpoint nor CCIEndpoint is applicable for the EIS you are binding to, then you need to implement its own Endpoint class according to the ResourceAdapter implementation. The endpoint class should be a subclass of org.switchyard.component.jca.endpoint.AbstractInflowEndpoint.
      • property: Properties for injecting into the endpoint class. The JMSEndpoint does not require a property. The CCIEndpoint requires connectionFactoryJNDIName property.
    • transacted: The boolean value to indicate whether the endpoint needs a transaction or not. Its value is true by default.
    • batchCommit: If you define this element, multiple incoming messages are processed in one transaction. The transaction is committed when the number of processed messages reach to batchSize, or batchTimeout milliseconds pass since the start of the transaction. Transaction reaper thread watches the inflight transaction, and once batch timeout occurs the transaction reaper thread commits it.
      • @batchSize: The number of messages to be processed in one transaction.
      • @batchTimeout:The batch timeout in milliseconds.
Here is an example that binds a service to HornetQ:
<sca:composite name="JCAInflowExample" targetNamespace="urn:userguide:jca-example-service:0.1.0">
    <sca:service name="JCAService" promote="SomeService">
        <jca:binding.jca>
            <selector:operationSelector operationName="onMessage"/>
            <jca:inboundConnection>
                <jca:resourceAdapter name="hornetq-ra.rar"/>
                <jca:activationSpec>
                    <jca:property name="destinationType" value="javax.jms.Queue"/>
                    <jca:property name="destination" value="ServiceQueue"/>
                </jca:activationSpec>
            </jca:inboundConnection>
            <jca:inboundInteraction>
                <jca:listener>javax.jms.MessageListener</jca:listener>
                <jca:endpoint type="org.switchyard.component.jca.endpoint.JMSEndpoint"/>
                <jca:transacted>true</jca:transacted>
                <jca:batchCommit batchSize="10" batchTimeout="5000"/>
            </jca:inboundInteraction>
        </jca:binding.jca>
    </service>
    <!-- sca:component definition omitted -->
</sca:composite>

9.2.4.5. Binding References with JCA Outbound

Composite-level references can be bound to a EIS with JCA outbound using the binding.jca binding definition. The following configuration options are required for binding.jca:
  • outboundConnection
    • resourceAdapter
      • @name: Name of the ResourceAdapter archive. Ensure that the resource adapter is deployed on the JBoss application server before you deploy the SwitchYard application which has the JCA binding.
    • connection
      • @jndiName: JNDI name to which the ConnectionFactory is bound.
  • outboundInteraction
    • connectionSpec: This is the configuration for javax.resource.cci.ConnectionSpec. Note that the JMSProcessor does not use this option.
      • @type:This is the FQN of the ConnectionSpec implementation class.
      • property: These are the properties to be injected into ConnectionSpec instance.
    • interactionSpec: This is the configuration for the _javax.resource.cci.InteractionSpec. Note that the JMSProcessor does not use this option.
      • @type:This is the FQN of the InteractionSpec implementation class.
      • property: These are the properties to be injected into InteractionSpec instance.
    • processor
      • @type: This is the FQN of the class which processes outbound delivery. There are two built-in processors, org.switchyard.component.jca.processor.JMSProcessor and org.switchyard.component.jca.processor.CCIProcessor. If neither JMSProcessor nor CCIProcessor is applicable for the EIS to which you have to bind, then you need to implement the EIS' own processor class according to the ResourceAdapter implementation. Note that this class should be a subclass of org.switchyard.component.jca.processor.AbstractOutboundProcessor.
      • property: These are the properties to be injected into processor instance. JMSProcessor needs destination property to specify target destination. CCIProcessor needs recordClassName property to specify record type to be used to interact with EIS. If you use CCIProcessor with the record type other than MappedRecord and IndexedRecord, you need to implement the corresponding RecordHandler.
    Here is an example of a JCA reference binding to HornetQ:
<sca:composite name="JCAReferenceExample" targetNamespace="urn:userguide:jca-example-reference:0.1.0">
    <sca:reference name="JCAReference" promote="SomeComponent/SomeReference" multiplicity="1..1">
        <jca:binding.jca>
            <jca:outboundConnection>
                <jca:resourceAdapter name="hornetq-ra.rar"/>
                <jca:connection jndiName="java:/JmsXA"/>
            </jca:outboundConnection>
            <jca:outboundInteraction>
                <jca:processor type="org.switchyard.component.jca.processor.JMSProcessor">
                    <jca:property name="destination" value="ReferenceQueue"/>
                </jca:processor>
            </jca:outboundInteraction>
        </jca:binding.jca>
    </sca:reference>
</sca:composite>

9.2.5. JMS

9.2.5.1. SwitchYard JMS Binding

The Java Message Service binding in SwitchYard provides support for asynchronous communication with messaging providers for services and references. The JMS binding is built on top of camel-jms and supports most of options for this endpoint.

9.2.5.2. Generic JMS Options

You can apply these options to <binding.jms>
  • queue or topic: this is the destination name from which resources are consumed or to which they shall be sent.
  • connectionFactory: this is the name of the connection factory instance to use.
  • username
  • password
  • clientId
  • durableSubscriptionName
  • concurrentConsumers
  • maxConcurrentConsumers
  • disableReplyTo
  • preserveMessageQos
  • deliveryPersistent
  • priority
  • explicitQosEnabled
  • replyTo
  • replyToType
  • requestTimeout
  • selector
  • timeToLive
  • transacted
  • transactionManager
Here is what a JMS service binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.jms>
            <camel:queue>INCOMING_GREETS</camel:queue>
            <camel:connectionFactory>#connectionFactory</camel:connectionFactory>
            <camel:username>esb</camel:username>
            <camel:password>rox</camel:password>
            <camel:selector>RECEIVER='ESB' AND SENDER='ERP'<camel:selector>
        </camel:binding.jms>
    </sca:service>
</sca:composite>
Here is what a JMS reference binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.jms>
            <camel:topic>GREETINGS_NOTIFICATION</camel:topic>
            <camel:connectionFactory>#connectionFactory</camel:connectionFactory>
            <camel:priority>8</camel:priority>
        <camel:binding.jms>
    </sca:reference>
</sca:composite>

9.2.6. File

9.2.6.1. File Binding

The file binding in SwitchYard provides filesystem level support for services and references. The file binding is built on top of camel-file and supports the endpoint options listed in the following sections.

9.2.6.2. Generic File Options

You can apply these options to <binding.file>:
  • directory: directory name for consuming and producing files
  • autoCreate: automatically creates directory if a directory does not exist
  • bufferSize: write buffer size
  • fileName: file name filter for consumer or file name pattern for producer
  • flatten: skip path and just use file name
  • charset: charset used for reading or writing file
Here is what a File service binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.file>
            <camel:directory>target/input</camel:directory>
            <camel:fileName>test.txt</camel:fileName>
            <camel:consume>
               <camel:initialDelay>50</camel:initialDelay>
               <camel:delete>true</camel:delete>
            </camel:consume>
        </camel:binding.file>
    </sca:service>
</sca:composite>
Supported options for binding services with files are:
  • delete
  • recursive
  • noop
  • preMove
  • move
  • moveFailed
  • include
  • exclude
  • idempotent
  • idempotentRepository
  • inProgressRepository
  • filter
  • inProgressRepository
  • sorter
  • sortBy
  • readLock
  • readLockTimeout
  • readLockCheckInterval
  • readLockTimeout
  • exclusiveReadLockStrategy
  • processStrategy
  • startingDirectoryMustExist
  • directoryMustExist
  • doneFileName
Here is what a File reference binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.file>
            <camel:directory>target/output</camel:directory>
            <camel:autoCreate>false</camel:autoCreate>
            <camel:produce>
                <camel:fileExist>Override</camel:fileExist>
            </camel:produce>
        <camel:binding.file>
    </sca:reference>
</sca:composite>
Supported options for binding references with files are:
  • fileExist
  • tempPrefix
  • tempFileName
  • keepLastModified
  • eagerDeleteTargetFile
  • doneFileName

9.2.7. FTP FTPS SFTP

9.2.7.1. FTP Binding

SwitchYard provides support for remote file systems on both service and reference. The ftp binding is built on top of camel-ftp and supports the endpoint options listed in the following sections.

9.2.7.2. Generic FTP FTPS SFTP Options

You can apply these options to <binding.ftp>,<binding.ftps>, and <binding.sftp>:
  • host
  • port
  • username
  • password
  • binary
  • connectTimeout
  • disconnect
  • maximumReconnectAttempts
  • reconnectDelay
  • separator
  • stepwise
  • throwExceptionOnConnectFailed
Here is what a FTP service binding and FTP reference binding looks like.
cat switchyard.xml 
<xml version="1.0" encoding="UTF-8"><switchyard xmlns="urn:switchyard-config:switchyard:1.0">
<composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912" name="camel-ftp-binding" targetNamespace="urn:switchyard-quickstart:camel-ftp-binding:0.1.0">
<service name="GreetingService" promote="GreetingService/GreetingService">
<ftp:binding.ftp xmlns:ftp="urn:switchyard-component-camel-ftp:config:1.0">
<ftp:directory>/</ftp:directory>
<ftp:host>localhost</ftp:host>
<ftp:port>2222</ftp:port>
<ftp:username>camel</ftp:username>
<ftp:password>isMyFriend</ftp:password>
<ftp:consume>
<ftp:initialDelay>50</ftp:initialDelay>
<ftp:delay>50</ftp:delay>
</ftp:consume>
</ftp:binding.ftp>
</service>
<component name="GreetingService">
<implementation.bean xmlns="urn:switchyard-component-bean:config:1.0" class="org.switchyard.quickstarts.camel.ftp.binding.GreetingServiceBean"/>
<service name="GreetingService">
<interface.java interface="org.switchyard.quickstarts.camel.ftp.binding.GreetingService"/>
</service>
</component>
</composite>
</switchyard>
The supported options for a FTP service are same as that for file. However, binding a reference with file can be used to store outcome of service on remote server. All File reference properties are supported in FTP reference binding.

9.2.7.3. Specific FTP FTPS SFTP Options

You can apply these options to <binding.ftp>:
  • passiveMode
  • timeout
  • soTimeout
  • siteCommand
You can apply these options to <binding.ftps>:
  • securityProtocol
  • isImplicit
  • execPbsz
  • execProt
  • disableSecureDataChannelDefaults
You can apply these options to <binding.sftp>:
  • knownHostsFile
  • privateKeyFile
  • privateKeyFilePassphrase

9.2.8. TCP UDP

9.2.8.1. TCP UDP Binding

SwitchYard provides support for network level integration with TCP and UPD protocols. The TCP and UDP binding is built on top of camel-netty and supports most of options for this endpoint.
Important
The camel-netty component is deprecated since JBoss Fuse 6.3 and will be replaced by the camel-netty4 component in a future release of JBoss Fuse.

9.2.8.2. Generic TCP UDP Options

You can apply these options to <binding.tcp> and <binding.udp>:
  • host
  • port
  • receiveBufferSize
  • sendBufferSize
  • reuseAddress
  • encoders
  • decoders
  • allowDefaultCodec
  • workerCount
  • sync
  • disconnect
Here is what a TCP/UDP service binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.tcp>
            <camel:host>localhost</camel:host>
            <camel:port>3939</camel:port>
            <camel:allowDefaultCodec>false</camel:allowDefaultCodec>
            <camel:sync>false</camel:sync>
        </camel:binding.tcp>
        <camel:binding.udp>
            <camel:host>localhost</camel:host>
            <camel:port>3940</camel:port>
            <camel:allowDefaultCodec>false</camel:allowDefaultCodec>
            <camel:sync>false</camel:sync>
        </camel:binding.udp>
    </sca:service>
</sca:composite>

9.2.8.3. Specific TCP UDP Options

You can apply these options to <binding.tcp>:
  • textline
  • tcpNoDelay
  • keepAlive
You can apply these options to <binding.udp>:
  • broadcast

9.2.8.4. SSL Configuration Options

This endpoint supports SSL. You can use the following parameters to configure it:
  • ssl: turn on SSL
  • sslHandler: custom SSL Handler to use
  • passphrase: bean reference to String instance used to open KeyStore
  • securityProvider: name of Java security provider
  • keyStoreFormat
  • keyStoreFile: reference to File instance which is loaded into java KeyStore
  • trustStoreFile: reference to File instance
  • sslContextParametersRef: if this parameter is specified, it must be an bean reference to an instance of org.apache.camel.util.jsse.SSLContextParameters where you may specify all necessary parameters at once

9.2.9. JPA

9.2.9.1. JPA Binding

The JPA binding in SwitchYard provides support for consuming and storing JPA entities. It supports both service binding for entity consumption and reference for entity storing. The JPA binding is built on top of camel-jpa and supports most of options for this endpoint.

9.2.9.2. Generic JPA Options

You can apply these options to <binding.jpa>
  • entityClassName
  • persistenceUnit
  • transactionManager
Here is what a JPA service binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.jpa>
            <camel:entityClassName>org.switchyard.quickstarts.camel.jpa.binding.domain.Greet</camel:entityClassName>
            <camel:persistenceUnit>JpaEvents</camel:persistenceUnit>
            <camel:transactionManager>#jtaTransactionManager</camel:transactionManager>
            <camel:consume>
                <camel:consumeLockEntity>false</camel:consumeLockEntity>
                <camel:consumer.transacted>true</camel:consumer.transacted>
            </camel:consume>
        </camel:binding.jpa>
    </sca:service>
</sca:composite>
Supported options for binding services with JPA are:
  • consumeDelete
  • consumeLockEntity
  • maximumResults
  • consumer.query
  • consumer.namedQuery
  • consumer.nativeQuery
  • consumer.resultClass
  • consumer.transacted
Here is what a JPA reference binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.jpa>
            <camel:entityClassName>org.switchyard.quickstarts.camel.jpa.binding.domain.Greet</camel:entityClassName>
            <camel:persistenceUnit>JpaEvents</camel:persistenceUnit>
            <camel:produce>
                <camel:flushOnSend>false</camel:flushOnSend>
            </camel:produce>
        </camel:binding.jpa>
    </sca:reference>
</sca:composite>
Supported options for binding references with JPA are:
  • flushOnSend
  • usePersist

9.2.10. SQL

9.2.10.1. SQL Binding

The SQL binding in SwitchYard provides database read/write support for references in SwitchYard. This binding is built on top of camel-sql.

9.2.10.2. Generic SQL Options

You can apply these options to <binding.sql>:
query
SQL query to execute
dataSourceRef
Data Source name
batch
Turn on JDBC batching
placeholder
A placeholder sign used to replace parameters in query
You may use the following two additional attributes for binding.sql element when used with service reference:
  • period
  • initialDelay
Here is what a SQL service binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.sql period="10s">
            <camel:query>SELECT * FROM greetings</camel:query>
            <camel:dataSourceRef>java:jboss/datasources/GreetDS</camel:dataSourceRef>
        </camel:binding.sql>
    </sca:service>
</sca:composite>
Here is what a SQL reference binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingDatabaseStore" promote="camel-binding/GreetingDatabaseStore" multiplicity="1..1">
        <camel:binding.sql>
            <camel:query>INSERT INTO greetings (name) VALUES (#)</camel:query>
            <camel:dataSourceRef>java:jboss/datasources/GreetDS</camel:dataSourceRef>
        <camel:binding.sql>
    </sca:reference>
</sca:composite>

9.2.11. Mail

9.2.11.1. Mail Binding

The Mail binding in SwitchYard provides support for consuming and sending mail messages. It supports both service binding for mail consumption and reference for message sending. The Mail binding is built on top of camel-mail and supports most of options for this endpoint.

9.2.11.2. Generic Mail Options

You can apply these options to <binding.mail>:
  • host
  • port
  • username
  • password
  • connectionTimeout
    You may also use the secure attribute to identify usage of secured connection (pop3s/imaps/smtps).
Here is what a Mail service binding looks like:

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.mail>
            <camel:host>localhost</camel:host>
            <camel:username>camel</camel:username>
            <camel:consume accountType="pop3">
                <camel:copyTo>after-processing</camel:copyTo>
            </camel:consume>
        </camel:binding.mail>
    </sca:service>
</sca:composite>
Supported options for binding services with Mail are:
  • folderName
  • fetchSize
  • unseen
  • delete
  • copyTo
  • disconnect
    You may specify additional attribute accountType to choose mail protocol. The possible values for this attribute are pop3 or imap. Default is imap.
Here is what a Mail reference binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:reference name="GreetingService" promote="camel-binding/GreetingService" multiplicity="1..1">
        <camel:binding.mail>
            <camel:host>localhost</camel:host>
            <camel:username>camel</camel:username>
            <camel:produce>
                <camel:subject>Forwarded message</camel:subject>
                <camel:from>camel@localhost</camel:from>
                <camel:to>rider@camel</camel:to>
            </camel:produce>
        </camel:binding.mail>
    </sca:reference>
</sca:composite>
Supported options for binding references with Mail are:
  • subject
  • from
  • to
  • CC
  • BCC
  • replyTo

9.2.12. Quartz

9.2.12.1. Quartz Binding

The Quartz binding in SwitchYard provides support for triggering services with a given cron expression. The Quartz binding is built on top of camel-quartz.

9.2.12.2. Generic Quartz Options

You can apply these options to <binding.quartz>:
  • name: name of the job
  • cron: execution expression
Here is what a Quartz service binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.quartz>
            <camel:name>GreetingJob</camel:name>
            <camel:cron>0 0/5 * * * ?</camel:cron>
        </camel:binding.quartz>
    </sca:service>
</sca:composite>

9.2.13. Timer

9.2.13.1. Timer Binding

The Timer binding in SwitchYard provides support for triggering services with fixed timer. It is a lightweight alternative for Quartz. The file binding is built on top of camel-timer.

9.2.13.2. Generic Timer Options

You can apply these options to <binding.timer>:
  • name: name of the timer
  • time
  • pattern
  • period
  • delay
  • fixedRate
  • daemon
Here is what a Timer service binding looks like:

<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.timer>
            <camel:name>GreetingTimer</camel:name>
            <camel:time>2012-01-01T12:00:00</camel:time>
            <camel:pattern>yyyy-MM-dd'T'HH:mm:ss</camel:pattern>
            <camel:delay>1000</camel:delay>
            <camel:fixedRate>true</camel:fixedRate>
        </camel:binding.timer>
    </sca:service>
</sca:composite>

9.2.14. SEDA

9.2.14.1. SEDA Binding

The SEDA binding in SwitchYard provides asynchronous service binding between camel route and SwitchYard service. This binding is built on top of camel-seda.
Note
The SEDA queue is not persistent.

9.2.14.2. Generic SEDA Options

You can apply these options to <binding.seda>:
  • name: name of the queue
  • size: the maximum capacity of the SEDA queue (the number of messages it can hold)
  • concurrentConsumers
  • waitForTaskToComplete
  • timeout
  • multipleConsumers
  • limitConcurrentConsumers
Here is what a SEDA service binding looks like:
<sca:composite name="camel-binding" targetNamespace="urn:switchyard-quickstart:camel-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService">
        <camel:binding.seda>
            <camel:name>GreetingQueue</camel:name>
            <camel:size>6</camel:size>
            <camel:concurrentConsumers>2</camel:concurrentConsumers>
        </camel:binding.seda>
    </sca:service>
</sca:composite>

9.2.15. Camel URI

9.2.15.1. Camel Binding

Camel binding support in SwitchYard allows Camel components to be used as gateway bindings for services and references within an application.

9.2.15.2. Generic Camel Options

Every Camel component binding supported by SwitchYard has its own configuration name-space with one exception. Bindings for Direct, SEDA, Timer and Mock share the same name-space: urn:switchyard-component-camel-core:config:1.0.
Composite-level services can be bound to a Camel component using the <binding.uri> binding definition. The following configuration options are available for binding.uri:
configURI
This contains the Camel endpoint URI used to configure a Camel component instance.
operationSelector
This is the specification of the operation to use for the message exchange. (This setting is not used for CXFRSconfigurations. )
Note
binding.uri is not linked with any specific component. It allows usage of 3rd party camel components which are not part of distribution.
Here is a sample service binding that uses a Camel component:
    
<sca:composite name="SimpleCamelService" targetNamespace="urn:userguide:simple-camel-service:0.1.0">
    <sca:service name="SimpleCamelService" promote="SimpleComponent/SimpleCamelService">
        <camel:binding.uri configURI="file://target/input?fileName=test.txt&amp;initialDelay=50&amp;delete=true">
            <selector:operationSelector operationName="print"/>
        </camel:binding.uri>
    </sca:service>
    <!-- sca:component definition omitted -->
</sca:composite>            

Binding a reference with Camel is very similar to binding a service. The only significant difference is that specification of the operationSelector is not required on reference bindings. Logically reference elements points to outgoing communication (which may, for example, be a service called by SwitchYard):
    
<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
    <sca:reference name="WarehouseService" promote="OrderComponent/WarehouseService" multiplicity="1..1">
        <camel:binding.uri configURI="file://target/output"/>
    </sca:reference>
</sca:composite>
</sca:composite>            

9.2.16. SCA

The SCA binding provides a means by which SwitchYard services and SwitchYard-aware clients can communicate with one another. There are three basic use cases for the SCA binding:
  • Facilitate inter-application communication within a SwitchYard runtime. The SCA binding can be used to link a composite reference in one application to a composite service in another application.
  • Provide a remote invocation endpoint for external clients using RemoteInvoker. This allows a stand-alone client to communicate with a SY application.
  • Allow clustering of SwitchYard services in two or more SwitchYard instances.

9.2.16.1. SCA Service Bindings

An SCA binding can be added to composite-level services to make that service available to other applications and remote clients through a SwitchYard internal communication protocol.
There is only one configuration option available for SCA bindings:
  • clustered : when enabled, the service is published in the distributed SY runtime registry so that other cluster instances can discover and consume the service.
Regardless of the clustering setting, all services with an SCA binding are invokable through the SwitchYard remote invoker endpoint. The default URL for this endpoint is http://localhost:8080/switchyard-remote. The hostname and port for this endpoint are based on the default HTTP listener defined in AS 7.

9.2.16.2. SCA Reference Bindings

An SCA binding can be added to a composite-level reference to invoke services provided in other SwitchYard applications deployed locally or in a cluster.
The following configuration parameters can be used with an SCA reference binding:
  • clustered : if enabled, the reference binding discovers remote SY service endpoints in a cluster.
  • load balancing : the name of a load balancing strategy to be used with clustering. Two out of the box options available are "RoundRobinStrategy" and "RandomStrategy". You can also specify a custom load balance strategy by implementing LoadBalanceStrategy.
  • target service : allows you to override the name of the service being invoked in the case where the target application uses a service name different from the reference name (default is that reference and service name match).
  • target namespace : allows you to override the namespace of the service being invoked. By default, all applications in SwitchYard use a different namespace, so keep this setting in mind when invocations occur across application boundaries.

9.2.16.3. Remote Transaction Propagation

If you invoke remote SwitchYard service through SCA binding under the active JTA transaction, SwitchYard runtime propagates its transaction context. Let's say we have ServiceA and ServiceB, where ServiceA is deployed on NodeA and ServiceB is on NodeB. ServiceA invokes ServiceB through SCA reference binding besides. If ServiceA is processing under the active JTA transaction, SwitchYard runtime embeds its transaction context into the remote invocation message when ServiceA invokes ServiceB. Then ServiceB extracts that transaction context and create subordinate JTA transaction, which means ServiceB is processed under the subordinate transaction of ServiceA's transaction, so those transactions could synchronize. Please note that transaction policy must allow this behavior on both sides of ServiceA and ServiceB.
In order to achieve this remote transaction propagation, XTS must be enabled in AS 7 configuration. Following changes must be applied:
--- standalone-ha.xml    2013-10-09 22:09:32.085300978 +0900
+++ standalone-ha-xts.xml    2013-10-16 11:40:57.198147545 +0900
@@ -25,6 +25,7 @@
         <extension module="org.jboss.as.webservices"/>
         <extension module="org.jboss.as.weld"/>
         <extension module="org.switchyard"/>
+        <extension module="org.jboss.as.xts"/>
 </extensions>
 <management>
    <security-realms>
@@ -405,6 +406,9 @@
    <extension identifier="org.apache.camel.soap"/>
    </extensions>
 </subsystem>
+<subsystem xmlns="urn:jboss:domain:xts:1.0">
+   <xts-environment url="http://${jboss.bind.address:127.0.0.1}:8080/ws-c11/ActivationService"/>
+</subsystem>
 </profile>
     <interfaces>
         <interface name="management">

9.2.17. MQTT

The MQTT binding in SwitchYard provides support for asynchronous communication with MQTT messaging providers. It supports both sides - service and reference. The MQTT binding is built on top of camel-mqtt (http://camel.apache.org/mqtt.html) and supports most options for this endpoint.

9.2.17.1. Generic options

You can apply the following options to the <binding.mqtt> definition:
  • host : The host that you want to connect to.
  • localAddress : The local address.
  • connectAttemptsMax : The maximum number of connect attempts.
  • reconnectAttemptsMax : The maximum number of reconnect attempts.
  • reconnectDelay : The time in milliseconds between reconnect attempts.
  • reconnectBackOffMultiplier : The multiplier to use to the delay between connection attempts.
  • reconnectDelayMax : The maximum time in milliseconds between reconnect attempts.
  • userName : user name
  • password : password
  • qualityOfService : The MQTT Quality of Service. Possible values are: AtMostOnce, AtLeastOnce, or ExactlyOnce.
  • byDefaultRetain : The default retain policy.
  • mqttTopicPropertyName : The property name for the MQTT topic.
  • mqttRetainPropertyName : The property name for the MQTT Retain policy.
  • mqttQosPropertyName : The property name for the MQTT Quality of Service.
  • connectWaitInSeconds : Delay in seconds to wait before establishing the connection.
  • disconnectWaitInSeconds : Delay in seconds to wait before disconnecting the connection.
  • sendWaitInSeconds : Delay in seconds to wait before sending the message.

9.2.17.2. Binding Services with MQTT

You can specify the MQTT Topic name with the subscribeTopicName option.

Example 9.8. Example MQTT service binding

<sca:composite name="camel-mqtt-binding" targetNamespace="urn:switchyard-quickstart:camel-mqtt-binding:0.1.0">
    <sca:service name="GreetingService" promote="GreetingService/GreetingService">
        <mqtt:binding.mqtt name="Greet">
            <mqtt:userName>karaf</mqtt:userName>
            <mqtt:password>karaf</mqtt:password>
            <mqtt:subscribeTopicName>camel/mqtt/test/input</mqtt:subscribeTopicName>
        </mqtt:binding.mqtt>
    </sca:service>
</sca:composite>

9.2.17.3. Binding References with MQTT

You can specify the MQTT Topic name to publish with the publishTopicName option.

Example 9.9. Example MQTT reference binding

<sca:composite name="camel-mqtt-binding" targetNamespace="urn:switchyard-quickstart:camel-mqtt-binding:0.1.0">
    <sca:reference name="StoreReference" multiplicity="0..1" promote="GreetingService/StoreReference">
        <mqtt:binding.mqtt name="Store">
            <mqtt:userName>karaf</mqtt:userName>
            <mqtt:password>karaf</mqtt:password>
            <mqtt:publishTopicName>camel/mqtt/test/output</mqtt:publishTopicName>
        </mqtt:binding.mqtt>
    </sca:reference>
</sca:composite>