Title Text

Switchyard

Primer

Application Basics

Move Right for the next Topic
Move Down for the current Topic

https://docs.jboss.org/author/display/SWITCHYARD/Application+Basics

Building Blocks in Detail

  • Composite
  • Component
  • Implementation
  • Component Service
  • Composite Service
  • Component Reference
  • Composite Reference

Composite

Move Right for the next Topic
Move Down for the current Topic

A composite is displayed as a light blue rectangle and represents the boundary between what's inside your application and what's outside your application. A SwitchYard application consists of exactly one composite that has a name and a targetNamespace. The targetNamespace value is important as it allows names defined locally in the application (e.g. service names) to be qualified and unique within a SwitchYard runtime.

<sca:composite name="example" targetNamespace="urn:example:switchyard:1.0">
</sca:composite>

Component

Move Right for the next Topic
Move Down for the current Topic

A component is a modular container for application logic and consists of the following:

  • 0 or 1 component service definitions
  • 0 to many component reference definitions
  • 1 implementation

Services and references allow a component to interact with other components, while the implementation provides the actual logic for providing and/or consuming services.

<sca:component name="Routing">
</sca:component>

Implementation

An implementation acts as the 'brain' of a service component and it is how implement your application logic. The following implementation options are available:

  • Bean : allows a CDI Bean to consume or provide services using annotations.
  • Camel : EIP-style routing and service composition using the XML or Java DSL in Apache Camel.
  • BPMN 2 : service orchestration and human task integration expressed as BPMN 2 and executed using jBPM
  • BPEL Process : web service orchestration using the OASIS Business Process Execution Language
  • Rules : decision services based on Drools

Implementations are private to a component, which means external consumers and providers are not aware of the details of a component's implementation (implementation-hiding).  All interactions with other components within an application and with external services are handled through component services and references.

<sca:component name="Routing">
   <camel:implementation.camel>
    <camel:xml path="RoutingService.xml"/>
   </camel:implementation.camel>
</sca:component>

Move Right for the next Topic
Move Down for the current Topic

Component Service

A component service is used to expose the functionality of an implementation as a service. All component services have a contract, which can be a Java interface, WSDL portType definition, or a set of named data types (interface.esb). Component services are private to an application, which means a component service can only be invoked by other components in the same application. In order to expose a component service to consumers external to the application, a component service can be 'promoted' to a composite service. A component service can be promoted multiple times to create different composite services.

<sca:component name="Routing">
   <camel:implementation.camel>
      <camel:xml path="route.xml"/>
   </camel:implementation.camel>
   <sca:service name="ServiceA">
      <sca:interface.java interface="org.example.ServiceA"/>
   </sca:service>
</sca:component>

Move Right for the next Topic
Move Down for the current Topic

Composite Service

A composite service represents an application service which is visible to other applications. A composite service can only be realized by promoting a component service within the application. The name and the interface of the composite service can be different from the component service. If the interface, or contract, of the composite service is different from the component service, be aware that a transformation may be required to map between the types defined in each interface.

<sca:composite name="example" targetNamespace="urn:example:switchyard:1.0">
   <sca:service name="ServiceA" promote="Routing/ServiceA">
      <sca:interface.wsdl interface="ServiceA.wsdl#wsdl.porttype(ServiceAPortType)"/>
   </sca:service>
</sca:composite>

Move Right for the next Topic
Move Down for the current Topic

Service Binding

A service binding is used to define an access method for a composite service. Composite services can have multiple bindings, which allows a single service to be accessed in different ways. In most cases, a service binding represents a protocol/transport adapter (e.g. SOAP, JMS, REST).

<sca:composite name="example" targetNamespace="urn:example:switchyard:1.0">
   <sca:service name="ServiceA" promote="Routing/ServiceA">
      <sca:interface.wsdl interface="ServiceA.wsdl#wsdl.porttype(ServiceAPortType)"/>
      <soap:binding.soap>
        <soap:wsdl>ServiceA.wsdl</soap:wsdl>
      </soap:binding.soap>
   </sca:service>
</sca:composite>

Move Right for the next Topic
Move Down for the current Topic

Component Reference

A component reference allows a component to consume other services. A component reference can be wired to a service offered by another component in the same application or it can be wired to services outside the application via a composite reference. Similar to component services, all component references have a contract with allows a component to invoke services without knowing implementation or binding details.

<sca:component name="Routing">
    <camel:implementation.camel>
        <camel:xml path="route.xml"/>
    </camel:implementation.camel>
   <sca:service name="ServiceA">
      <sca:interface.java interface="org.example.ServiceA"/>
   </sca:service>
   <sca:reference name="ServiceC">
      <sca:interface.java interface="org.example.ServiceC"/>
   </sca:reference>
</sca:component>

Move Right for the next Topic
Move Down for the current Topic

Composite Reference

Move Right for the next Topic
Move Down for the current Topic

A composite reference allows a component reference to be wired to a service outside the application. Similar to composite services, bindings are used with composite references to specify the communication method for invoking the external service.

<sca:composite name="example" targetNamespace="urn:example:switchyard:1.0">
   <sca:reference name="ReferenceB" multiplicity="0..1" promote="Routing/ServiceB">
      <sca:interface.java interface="org.example.ServiceB"/>
   </sca:reference>
</sca:composite>

Reference Bindings

A reference binding is used to define an access method for an external service via a composite reference. Unlike service bindings, there can only be one binding for each composite reference. The set of bindings available for references is identical to the set of bindings available for services, although the configuration values for a given binding may be different depending on whether it's used as a service binding or a reference binding.

Move Right for the next Topic
Move Down for the current Topic

<sca:composite name="example" targetNamespace="urn:example:switchyard:1.0">
   <sca:reference name="ReferenceB" multiplicity="0..1" promote="Routing/ServiceB">
      <sca:interface.java interface="org.example.ServiceB"/>
         <jms:binding.jms>
         <jms:queue>MyQueue</jms:queue>
         <jms:connectionFactory>#ConnectionFactory</jms:connectionFactory>
      </jms:binding.jms>
   </sca:reference>
</sca:composite>

Contracts 

Move Right for the next Topic
Move Down for the current Topic

When working with SwitchYard we have to define the contracts for our services as well as for our component implementations. In order to define our contracts there is different ways, and different points, depending on:

  • Component implementation

  • Service binding

http://unpoucode.blogspot.com.es/2014/10/switchyard-contracts.html

Contract Type

Move Right for the next Topic
Move Down for the current Topic

As we can see in the picture, in a simple service we can find, at least, the following contracts:

1. Component contracts

  • Component service
  • Component reference

2. Composite contracts

  • Composite service
  • Composite reference

3. Binding contracts

  • Service Binding
  • Reference Binding

Component Contracts

Move Right for the next Topic
Move Down for the current Topic

This is the contract a component exposes or uses, depending on whether it is a service or reference contract. A component contract can be defined in 3 different ways in SwitchYard:

  • Java. Using a Java interface.

  • WSDL. Using a port type in a wsdl file.

  • ESB. Using a virtual interface definition. (No real file will be used).

Move Right for the next Topic
Move Down for the current Topic

Component Contracts

A component contract in SwitchYard has the following characteristics:

  • 0..1 argument. If used, this will be the message content. It is optional as there can be operations that don’t expect a message (REST GET, Scheduled operations,…​). Used in Exchanges of type IN_ONLY and IN_OUT.

  • 0..1 return type. If used, this will be the message content for the response. Used only in Exchanges of type IN_OUT.

  • 0..1 exceptions. If used, this will be the message content for the response if there is an Exception. Used in Exchanges of type IN_ONLY and IN_OUT.

Java Contracts

Move Right for the next Topic
Move Down for the current Topic

A Java contract is defined by a Java Interface.

WSDL Contract

Move Right for the next Topic
Move Down for the current Topic

A WSDL contract is defined by a port type in a wsdl file.

ESB Contract

Move Right for the next Topic
Move Down for the current Topic

An ESB contract is a virtual contract (no file required) that declares the types of the input, output and exception types.

This contract can only be used in components with one single operation.

Transformations Between Contracts

Move Right for the next Topic
Move Down for the current Topic

When a message flows in SwitchYard, and there is different types in the contracts on both ends of the "channel", a transformation must be done.

 

There can be implicit or explicit transformations happening, depending on where they have to happen, and there are extension points to define how the transformation between types in contracts must happen.

Composite Service Binding and Composite Service / Composite Reference and Composite Reference Binding

Move Right for the next Topic
Move Down for the current Topic

Contract differences are handled in the ServiceHandlers when composing and decomposing the SwitchYard message.

 

Any difference in contracts must be handled in the Message composer.

 

Camel and Http MessageComposers will do Camel Implicit Transformations if required. If target type is JAXB, the class needs to have @XMLRootElement annotation.

Composite Service and Component Service / Component Reference and Composite Reference

Move Right for the next Topic
Move Down for the current Topic

Contract differences are handled by transformers defined in the composite application, which are applied by theExchangeHandler chain during the execution of the Exchange.

 

The transformers usually map from an origin type to a destination type.

Composite Service and Component Service / Component Reference and Composite Reference

Move Right for the next Topic
Move Down for the current Topic

When the Exchange is between a composite service and a component service:

  • In the IN phase, from is the argument’s type of the composite service and the to is the type in the component service.

  • In the OUT phase, from is the return/exception type of the component service and the to is the return/exception typein the composite service.

When the Exchange is between a component reference and a composite reference:

  • In the IN phase, from is the argument’s type of the component reference and the to is the type in the composite reference.

  • In the OUT phase, from is the return/exception type of the composite reference and the to is the return/exception typein the component reference.

Component Service and Component Reference

Move Right for the next Topic
Move Down for the current Topic

Contract differences are handled in the component implementation, and has to be explicitly transformed.

Special Notes

Move Right for the next Topic
Move Down for the current Topic

  • If a Composite Service does not declare an interface, it will use the interface defined by the promoted Component Service

  • Every Component can have one Service

  • Binding name can be null. In this case, a binding name will be automatically generated with "ServiceName+BindingType+i"

  • When the input parameter of a service contract is empty, the message will not be change, it will be in it’s original form (e.g. java.io.Reader for streaming bindings like HTTP, File,…​)

Switchyard Primer

By Kenneth Peeples

Switchyard Primer

  • 3,947
Loading comments...

More from Kenneth Peeples