Welcome to the SwitchYard User Guide. This document provides a detailed explanation of the moving parts in SwitchYard. If you are looking for a way to get up and running quickly, be sure to check out the Getting Started guide.
What is a SwitchYard?
SwitchYard provides an environment for easily applying SOA (Service Oriented Architecture) concepts to integration applications. A SwitchYard application is comprised of one or more components which may provide a service and/or consume service references , where a service is simply a named interface and a reference is simply a named interface that resolves to a service. These are more narrowly classified as component services and component references . A component may be implemented using a variety of technologies including: Java, a Camel route definition, a BPMN2 process, a Drools rule (DRL file), BPEL.
A component service may be promoted to a composite service , which allows the service to be accessed by other applications. Like a component service, a composite service is a named interface. However, instead of being associated with an implementation (i.e. a component), a composite service is associated with one or more bindings . A binding describes an endpoint through which other applications can communicate with the service being promoted (e.g. a JMS queue, a directory on a file system, a REST URL, etc.).
A component reference may resolve to a component service within the application or may be promoted to a composite reference . Like a component reference, a composite reference is a named interface. However, in addition to describing the characteristics of a required service it also describes the location of the service through one or more bindings (e.g. a JMS queue, SOAP over HTTP, etc.). A composite reference may also be conceptualized as an external service required by the application.
The following screenshot illustrates how each of these are manifest in the SwitchYard editor in Eclipse.
Working With Messages
Conceptually, the diagram above represents a left-to-right message flow: messages enter the system through the composite service on the left, are processed by components in the middle and exit the system through the composite reference on the right. Service interfaces are used to describe the operations available including the input, output and fault types for each operation. Interfaces in SwitchYard are constrained to those that describe operations with a single input, optional output and optional fault. This aligns well with the message in/message out paradigm prevalent in integration applications.
SwitchYard provides three different ways to define interfaces: Java interface, WSDL port types, and generic ESB. Java interfaces and WSDL port types allow users to define interfaces with one or more operations (although those operations are constrained to having a single parameter, an optional return and an optional fault), whereas an ESB interface declares the input, output and fault type for a single, unnamed operation.
Types are names which identify the structure of the message. Java interfaces support working with Java types. WSDL port types support working with XML types. ESB interfaces support working with blobs (although Java and WSDL interfaces can also support blob types, e.g. by using a CDATA in XML or by adding @OperationTypes to a Java method).
Transformers are used when a message is passed to a service whose input type differs from the type specified on the source (e.g. from a composite service (source) to its promoted component service (target), or from a component reference (source) to the resolved service (target)) . (For interfaces containing multiple operations, it is required that the target interface includes all operations named in the source interface.) SwitchYard automatically detects that a transformation is required and looks for a transformer that is capable of converting the source type (i.e. parameter type on the source or return/fault type on the target) to its target type (i.e. parameter type on the target or return/fault type on the source). The transformer is invoked and the resulting content is forwarded to/from the target service. If a transformer cannot be found, an exception is thrown and the invocation fails.