Chapter 10. Gateways

10.1. What is a Gateway

Gateway is a network point that enables the SwitchYard applications to interact with services outside the application. They provide connectivity to/from external systems

10.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.

10.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.

10.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 10.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>

10.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 10.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>
10.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 10.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>
10.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 10.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>

10.2.1.3. WS-Security

10.2.1.3.1. Enable WS-Security

Procedure 10.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.
10.2.1.3.2. Sample WS-Security Configurations
JBoss Fuse Service Works 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.
10.2.1.3.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
10.2.1.3.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
10.2.1.3.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.
10.2.1.3.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.
10.2.1.3.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
    

10.2.1.4. Attachments

10.2.1.4.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.
10.2.1.4.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 10.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>

10.2.1.5. 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>

10.2.2. HTTP

10.2.2.1. HTTP Component

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

10.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.

10.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>

10.2.3. RESTEasy

10.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.

10.2.3.2. RESTEasy Component

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

10.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.

10.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>

10.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 10.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>

10.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 10.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>

10.2.4. JCA

10.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.

10.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.

10.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.

10.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 10.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>
			

10.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>			

10.2.5. JMS

10.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.

10.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>				
	

10.2.6. File

10.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.

10.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

10.2.7. FTP FTPS SFTP

10.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.

10.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.

10.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

10.2.8. TCP UDP

10.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.

10.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>				
	

10.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

10.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

10.2.9. JPA

10.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.

10.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

10.2.10. SQL

10.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.

10.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>			
	

10.2.11. Mail

10.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.

10.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

10.2.12. Quartz

10.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.

10.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>			
	

10.2.13. Timer

10.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.

10.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>						
	

10.2.14. SEDA

10.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.

10.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>
	

10.2.15. Camel URI

10.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.

10.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>			

10.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.

10.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.

10.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.

10.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">

10.3. Message Composition

10.3.1. Message Composers

A MessageComposer composes or decomposes a native binding message to or from SwitchYard's canonical message. It does so in three steps:
  1. Construct a new target message instance.
  2. Copy the content of the message.
  3. Delegate the header/property mapping to a ContextMapper.
A SOAPMessageComposer and CamelMessageComposer are included with SwitchYard. These implementations are used by their associated bindings but you can override these with your own implementations.

10.3.2. Create a Custom Message Composer

Procedure 10.2. Create a Custom Message Composer

  1. Implement the org.switchyard.component.common.composer.MessageComposer interface:
    public interface MessageComposer<T> {
        ContextMapper<T> getContextMapper();
        MessageComposer<T> setContextMapper(ContextMapper<T> contextMapper);
        Message compose(T source, Exchange exchange, boolean create) throws Exception;
        public T decompose(Exchange exchange, T target) throws Exception;
    }		
    
  2. Specify your implementation in your switchyard.xml file:
    <binding.xyz ...>
        <messageComposer class="com.example.MyMessageComposer"/>
    </binding.xyz>
    

10.3.3. Custom Message Composer Properties

  • The getContextMapper() and setContextMapper() methods are bean properties. If you extend BaseMessageComposer, both properties are implemented for you.
  • Your compose() method needs to take the data from the passed-in source native message and compose a SwitchYard Message based on the specified Exchange. The create parameter determines whether or not we ask the Exchange to create a new Message, or use the existing one.
  • Your decompose() method needs to take the data from the SwitchYard Message in the specified Exchange and "decompose it" into the target native message.

10.4. Operation Selectors

10.4.1. Operation Selector

Use the OperationSelector to determine which service operation should be invoked for the message exchange.

10.4.2. Types of Operation Selectors

SwitchYard provides the following options for Operation Selectors.

Important

Operation selectors are used in combination with a service binding to help SwitchYard determine the target operation for a service invocation. When a service only has a single operation, an operation selector should not be used. If an operation selector is used for a service with a single operation, failure to assign an operation in the operation selector will not result in an error. If an operation selector fails to assign an operation for a service with multiple operations an error is reported.
Static Operation Selector
You can specify an operation name in the configuration. Here is what a Static Operation Selector configuration looks like:
<hornetq:binding.hornetq>
    <swyd:operationSelector operationName="greet" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</hornetq:binding.hornetq>
	
XPath Operation Selector
You can specify an XPath location which contains an operation name to be invoked in the message contents. Here is what an XPath Operation Selector configuration looks like:
<jca:binding.jca>
    <swyd:operationSelector.xpath expression="//person/language" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</jca:binding.jca>
	
For this configuration, if you specify the following message content, then the operation spanish() is invoked:
<person>
    <name>Fernando</name>
    <language>spanish</language>
</person>
	
Regex Operation Selector
You can specify a regular expression to find an operation name to be invoked in the message contents. Here is what a Regex Operation Selector configuration looks like:
<http:binding.http>
    <swyd:operationSelector.regex expression="[a-zA-Z]*Operation" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</http:binding.http>
	
For this configuration, if you specify the following message content, then the operation regexOperation() is invoked:
xxx yyy zzz regexOperation aaa bbb ccc
	
Java Operation Selector
You can specify a Java class which is able to determine the operation to be invoked. Here is what a Java Operation Selector configuration looks like:
<jca:binding.jca>
    <swyd:operationSelector.java class="org.switchyard.example.MyOperationSelectorImpl" xmlns:swyd="urn:switchyard-config:switchyard:1.0"/>
(... snip ...)
</jca:binding.jca>
	
Here, the org.switchyard.example.MyOperationSelectorImpl has to implement org.switchyard.selector.OperationSelector or be a subclass of concrete OperationSelector classes for each service bindings. You can override the selectOperation() method as you like.
Following are the default OperationSelector implementation for each service bindings:
  • Camel : org.switchyard.component.camel.selector.CamelOperationSelector
  • JCA/JMS : org.switchyard.component.jca.selector.JMSOperationSelector
  • JCA/CCI : org.switchyard.component.jca.selector.CCIOperationSelector
  • HTTP : org.switchyard.component.http.selector.HttpOperationSelector

10.5. Throttling

SwitchYard provides support for message throttling. Throttling is configured on a composite service and applies to all requests received through all gateways configured on the service. If you have multiple bindings on a composite service, they share the same throttling configuration. If you want a given service to have two different throttling settings (one per binding), then promote the service twice and provide a unique setting for each composite service.
SwitchYard provides the following throttling options:
  • timePeriod : (optional; defaults to 1000) The time period, in milliseconds, over which requests are counted. The message count is reset at the beginning of each period.
    The setting for the time period is static - it can not change at runtime.
  • maxRequests : The maximum number of requests that can be processed within a specified timePeriod. Processing is delayed until the start of the next period for any messages received after the limit is reached.
    The setting for the number of messages is dynamic - it can change at runtime.

Note

Throttling of individual gateways is not supported.

10.5.1. Example

Here's an example configuration, restricting the OrderService to handle at most one request every ten seconds. Note that the sy:throttling element is located within an sca:extensions element.
<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:extensions>
            <sy:throttling maxRequests="1" timePeriod="10000"/>
        </sca:extensions>
    </sca:service>
</sca:composite>
You can specify the same configuration using the SwitchYard editor as well.