Each SwitchYard application must include a configuration descriptor named switchyard.xml in the /META-INF directory of it's archive. The basic structure of this descriptor is:
-
A parent <switchyard> element which contains all other configuration.
-
Exactly one child <composite> element, which contains the SCA description of the application.
-
Zero or one <transforms> elements which can contain one or more transform definitions.
-
Zero or one <validates> elements which can contain one or more validate definitions.
Here's an example of what a SwitchYard descriptor looks like:
<switchyard xmlns="urn:switchyard-config:switchyard:1.0"
xmlns:sca="http://docs.oasis-open.org/ns/opencsa/sca/200912"
xmlns:bean="urn:switchyard-component-bean:config:1.0"
xmlns:soap="urn:switchyard-component-soap:config:1.0">
<sca:composite name="orders" targetNamespace="urn:switchyard-quickstart-demo:orders:0.1.0">
<sca:service name="OrderService" promote="OrderService">
<soap:binding.soap>
<soap:socketAddr>:18001</soap:socketAddr>
<soap:wsdl>wsdl/OrderService.wsdl</soap:wsdl>
</soap:binding.soap>
</sca:service>
<sca:component name="InventoryService">
<bean:implementation.bean class="org.switchyard.quickstarts.demos.orders.InventoryServiceBean"/>
<sca:service name="InventoryService">
<sca:interface.java interface="org.switchyard.quickstarts.demos.orders.InventoryService"/>
</sca:service>
</sca:component>
<sca:component name="OrderService">
<bean:implementation.bean class="org.switchyard.quickstarts.demos.orders.OrderServiceBean"/>
<sca:service name="OrderService">
<sca:interface.java interface="org.switchyard.quickstarts.demos.orders.OrderService"/>
</sca:service>
<sca:reference name="InventoryService">
<sca:interface.java interface="org.switchyard.quickstarts.demos.orders.InventoryService"/>
</sca:reference>
</sca:component>
</sca:composite>
<transforms xmlns="urn:switchyard-config:transform:1.0">
<transform.java bean="Transformers"
from="{urn:switchyard-quickstart-demo:orders:1.0}submitOrder"
to="java:org.switchyard.quickstarts.demos.orders.Order"/>
<transform.java bean="Transformers"
from="java:org.switchyard.quickstarts.demos.orders.OrderAck"
to="{urn:switchyard-quickstart-demo:orders:1.0}submitOrderResponse"/>
</transforms>
<validates>
<validate.java bean="Validators"
name="java:org.switchyard.quickstarts.demos.orders.Order"/>
<validate.java bean="Validators"
name="java:org.switchyard.quickstarts.demos.orders.OrderAck"/>
</validates>
</switchyard>
Luckily, SwitchYard can generate the bulk of the above description based off of annotations in your application code, so you won't have to muck with this XML directly. For the portions that can't be generated, Forge tooling fills the gap nicely. While you certainly can play with the XML directly, we try to do what we can to protect you from those pointy angle brackets.
Composite
The composition of a SwitchYard application is defined using the Service Component Architecture Assembly Model, an open specification undergoing standardization in OASIS. For the nitty gritty details of the assembly model, please consult the SCA specification. This section provides a brief overview of the important elements:
-
<composite> : single, top-level application element which defines a set of services, the relationships and dependencies of those services, and the linkage (if any) to services available outside the application.
-
<component> : contains the implementation of a service and the dependencies of that service
-
<service> : defines the name and interface for a service. This element is used inside a component definition to declare a service and can also appear inside a composite definition to indicate that a service is visible to outside applications.
-
<interface.XXX> : the contract for a service. The type of the interface replaces 'XXX' in the definition. Supported interface types at this point are "java", "wsdl", and "esb".
-
<binding.XXX> : the binding of a service. The type of the binding replaces 'XXX' in the definition. Example bindings include "binding.soap" and "binding.camel".
-
<implementation.XXX> : the implementation of a service. The type of the implementation replaces 'XXX' in the definition. Example implementations include 'implementation.bean" and "implementation.camel".
Validates
The <validates> section of SwitchYard configuration is used to define validators local to your application. Similar to transformers, each validator definition includes a type stuff in it's definition (e.g. validate.java, validate.xml). The name definition on each validator corresponds to the message type used on a service and/or reference interface used within SwitchYard. See the Validator section of the User Guide for more information on individual validator types.
Generated Configuration
As mentioned earlier, SwitchYard is capable of generating configuration off of annotations in your application code so that you don't have to hand edit XML configuration. The generated configuration is packaged up with your application as part of the Maven build lifecycle and placed in
target/classes/META-INF/switchyard.xml
Your application project can also include a descriptor in
src/main/resources/META-INF/switchyard.xml
This version of the configuration can be edited by the user directly and is also used by Forge tooling to specify configuration in response to SwitchYard forge commands. During the build process, the user-editable switchyard.xml is merged with any generated configuration to produce the final switchyard.xml in the target/ directory.