此内容没有您所选择的语言版本。
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.
See Also:
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:
orhttp:
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
- Define a Policy within your WSDL and reference it with a PolicyReference inside your binding.
- Configure your <soap.binding> with an <endpointConfig> to ensure that JBossWS-CXF is configured appropriately.
- Configure your <soap.binding> with an <inInterceptors> section, including the appropriate JBossWS-CXF <interceptor> to handle incoming SOAP requests.
- 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:
- The Policy in your WSDL must reflect the added requirements. See Section 9.2.1.4.3.1, “Sample Endpoint Configurations”, Section 9.2.1.4.3.2, “Sample Client Configurations”, and Section 9.2.1.4.3.3, “Endpoint Serving Multiple Clients”.
- Configure your <soap.binding> with an <endpointConfig> to ensure JBossWS-CXF is configured appropriately.
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:
- 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!"; } }
- 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); } }
- 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>
NoteIf you are deploying the endpoint archive to JBoss Application Server 7, add a dependency toorg.apache.ws.security
module in theMANIFEST.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.jksThe 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.xml
file.
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 thejavax.jms.MessageListener
and when you use CCIEndpoint, specify thejavax.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 namelyorg.switchyard.component.jca.endpoint.JMSEndpoint
andorg.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 oforg.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 forjavax.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
andorg.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 oforg.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.
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
- connectionTimeoutYou 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
- disconnectYou 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&initialDelay=50&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">