Chapter 7. SwitchYard Contracts

7.1. SwitchYard Contracts

SwitchYard uses a component service to expose the functionality of an implementation. All component services and implementations have service contracts. You can define a contract depending on Component Implementation and Service Binding.
A simple service has following contracts:

Component Contracts

  • Component Service
  • Component Reference

Composite Contracts

  • Composite Service
  • Composite Reference

Binding Contracts

  • Service Binding
  • Reference Binding
Report a bug

7.2. Component Contracts

Component Contract can be either a Component Service or a Component Reference. A Component Service is used to expose the functionality of an implementation as a service. A Component Reference allows a component to consume other services. A component contract can be defined in three 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 is used).
A component contract in SwitchYard has the following characteristics. All are optional:
  • argument: If used, this is the message content. It is optional as there can be operations that don’t expect a message (for example, REST GET, Scheduled operations​). Used in Exchanges of type IN_ONLY and IN_OUT.
  • return type: If used, this is the message content for the response. Used only in Exchanges of type IN_OUT.
  • exceptions: If used, this is the message content for the response in case of an Exception. Used in Exchanges of type IN_ONLY and IN_OUT.

Note

Contracts in Camel can be defined with empty parameters, and users can still work with the message content.
Java contract

A Java contract is defined by a Java Interface.

Note

Java components require Java contracts.
WSDL contract

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

ESB contract

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

Note

ESB contract may be used in components with one single operation.
Report a bug

7.3. Transformations between Contracts

Transformation between contracts is necessary when a message flows in SwitchYard, and there are different types in the contracts on both ends of the channel. Implicit or explicit transformations happen wherever necessary. The extension points define how the transformation between types in contracts must happen.
Composite Service Binding and Composite Service / Composite Reference and Composite Reference Binding

Contract differences are handled in the ServiceHandlers when composing and decomposing the SwitchYard message. Any difference in contracts is handled in the Message composer.

Note

Camel and HttpMessageComposers carry out Camel Implicit Transformations if required. If target type is JAXB, the class must have @XMLRootElement annotation.
Composite Service and Component Service / Component Reference and Composite Reference

Contract differences are handled by transformers defined in the composite application, which are applied by the ExchangeHandler chain during the execution of the Exchange. The transformers usually map from an origin type to a destination type.

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 type of 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 type of the component reference.

Note

Some implicit transformations happen (without declaring a transformer) if SwitchYard supports automatic transformation between both types, as declared by Camel Transformer.
Component Service and Component Reference

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

Important

  • If a Composite Service does not declare a contract, it uses the contract defined by the promoted Component Service.
  • Every Component can have one Service.
  • Binding name can be null. In this case, a binding name is automatically generated with "ServiceName+BindingType+i".
  • When the input parameter of a service contract is empty, the message does not change, it is in its original form (e.g. java.io.Reader for streaming bindings like http, File,…​)
Report a bug