Installation

Please refer to Installing Eclipse Tooling for details on installing the SwitchYard Eclipse tooling.

Features

The SwitchYard Eclipse tooling provides the following features:

• Creation of SwitchYard projects.

• Adding SwitchYard capabilities to existing Maven based Eclipse projects.

• Configuration of SwitchYard capabilities (i.e. runtime component dependencies; e.g. SOAP, BPM, Camel, etc.).

• A graphical editor for editing SwitchYard application configuration (i.e. switchyard.xml), which provides the following features:

  • Creation and configuration of components, services and references.

  • Component service/reference promotion and configuration of gateway bindings.

  • Creation of implementation skeletons for new service components (e.g. bean classes, BPMN2 files, DRL files, etc.).

  • Creation of unit test skeletons for services.

  • Configuration of message transformers, including creation of implementation skeletons for message transformers (e.g. XSL, Java, etc.).

  • Creation of Artifact references.

• Java2WSDL

• WSDL2Java

• XML catalog entries for SwitchYard configuration schema.

• m2eclipse integration supporting the SwitchYard Maven plugin (org.switchyard:switchyard-plugin).

• Support for workspace deployment of SwitchYard projects.

Tutorial

A basic tutorial can be found on the Tutorial page.

SwitchYard Projects

A SwitchYard project is a Maven based project with the following characteristics:

• a switchyard.xml file in the project's META-INF folder

• one or more SwitchYard runtime dependencies declared in the pom.xml file

• org.switchyard:switchyard-plugin mojo configured in the pom.xml file

A SwitchYard project may also contain a variety of other resources used to implement the application, for example: Java, BPMN2, DRL, BPEL, WSDL, XSD, and XML files.

The Eclipse tooling supports the creation of new SwitchYard projects.  The tooling also allows users to add SwitchYard capabilities to existing Maven projects.

Unit Testing

The SwitchYard tooling provides support for stubbing out test classes for services.

@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(mixins = CDIMixIn.class, config = SwitchYardTestCaseConfig.SWITCHYARD_XML)
public class SomeServiceTest {

    private SwitchYardTestKit testKit;
    private CDIMixIn cdiMixIn;
    @ServiceOperation("ExampleService")
    private Invoker service;

    @Test
    public void testSomeInOnlyOperation() throws Exception {
        // TODO Auto-generated method stub
        // initialize your test message
        Object message = null;
        service.operation("someInOnlyOperation").sendInOnly(message);

        // validate the results
        Assert.assertTrue("Implement me", false);
    }

    @Test
    public void testSomeInOutOperation() throws Exception {
        // TODO Auto-generated method stub
        // initialize your test message
        Object message = null;
        String result = service.operation("someInOutOperation")
                .sendInOut(message).getContent(String.class);

        // validate the results
        Assert.assertTrue("Implement me", false);
    }

}

Runtime Support

TBD: document SwitchYard runtime support

Workspace Deployment

All SwitchYard projects are configured as some type of JEE module by the tooling.  This allows the user to deploy the project to any JEE server defined in the workspace.

Creating a Project

The first thing you'll want to do with Forge is create a new project.  This can be done inside the Forge shell using the new-project command.

switchyard$ forge
    _____                    
   |  ___|__  _ __ __ _  ___ 
   | |_ / _ \| `__/ _` |/ _ \  \\
   |  _| (_) | | | (_| |  __/  //
   |_|  \___/|_|  \__, |\___| 
                   |___/      
 
[no project] switchyard $ new-project --named syApp --topLevelPackage org.switchyard.examples.forge
 ? Use [/private/tmp/switchyard/syApp] as project directory? [Y/n] 
***SUCCESS*** Created project [syApp] in new working directory [/private/tmp/switchyard/syApp]

At this point, you have an empty application with a few Maven facets installed.  What's a facet you ask?  Read on ....

Facets

Facets add capabilities to an application and to the forge environment itself.  This allows SwitchYard to add dependencies to your application's pom based on the functionality you will be using, instead of sticking every possible SwitchYard dependency in the application by default.  Facets are also used to add commands specific to SwitchYard itself and components which you will be using in your application.  The following facets are currently available:

• switchyard - core set of commands and dependencies for the SwitchYard runtime

• switchyard.bean - commands and dependencies for Bean component services

• switchyard.bpm - commands and dependencies for BPM component services

• switchyard.rules - commands and dependencies for Rules component services

• switchyard.soap - commands and dependencies for SOAP gateway bindings

• switchyard.camel - commands and dependencies for Camel services and gateway bindings

• switchyard.rest - commands and dependencies for RESTEasy gateway bindings

• switchyard.http - commands and dependencies for HTTP gateway bindings

Installing a facet can be done directly in the shell using the install-facet command.

[syapp] syapp $ project install-facet switchyard.soap
***SUCCESS*** Installed [switchyard.soap] successfully.
Wrote /tmp/syapp/pom.xml

Commands

The following SwitchYard commands are available in Forge (grouped by facet).

switchyard

• switchyard show-config : displays the current state of your application's configuration, including services, references, and bindings.

• switchyard promote-service : promotes an internal application-scoped service to be visible to other applications.

• switchyard promote-reference : promotes an internal application-scoped reference so that it can be mapped to services provided in other applications.

• switchyard create-service-test : create a new unit test for a service.

• switchyard get-version : returns the version of SwitchYard used by the application.

• switchyard trace-messages : enables message tracing at runtime - all messages will be logged.

• switchyard import-artifacts : add a dependency on a service artifact module to the application's configuration

• switchyard add-reference : adds a reference to a service implementation; particularly useful for service types which do not autogenerate references (Camel, BPM, BPEL).

switchyard.bean

• bean-service create : creates a new CDI Bean service, consisting of a service interface and implementation class.

switchyard.bpm

• bpm-service create : creates a new BPM service, consisting of a service interface and implementation class.

switchyard.rules

• rules-service create : creates a new Rules service, consisting of a service interface and implementation class.

switchyard.camel

• camel-service create : creates a new XML or Java DSL Camel route.

• camel-binding bind-service : binds a service using a Camel endpoint URI.

• camel-binding bind-reference : binds a reference using a Camel endpoint URI.

switchyard.soap

• soap-binding bind-service : binds a service to a SOAP endpoint.

• soap-binding bind-reference : binds a reference to a SOAP endpoint.

switchyard.rest

• rest-binding bind-service : binds a service to a RESTEasy endpoint.

• rest-binding bind-reference : binds a reference to a RESTEasy endpoint.

switchyard.http

• http-binding bind-service : binds a service to a HTTP endpoint.

• http-binding bind-reference : binds a reference to a HTTP endpoint.

Overview

The SwitchYard management console is integrated with the standard JBoss AS management console and provides the following:

• A view of the applications and services deployed on the server.

• A view of various execution metrics.

• A view of the SwitchYard subsystem configuration.

SwitchYard contributes views to the standard JBoss AS management console's Runtime and Profile pages.

Metrics Views

SwitchYard Message Metrics can be accessed on the Runtime page of the AS console under Status -> Subsystems -> SwitchYard.  This page provides a view of a comprehensive set of metrics aggregated at various levels within the system.

The following types of metrics are available:

• Message count: total, success, failed

• Processing time: total, min., avg., max.

Collected metrics can be viewed at the following levels:

• System : metrics for the entire SwitchYard runtime (all deployed applications)

• Service : metrics for a composite service in an application. Additional metric details are provided for the following:

  • Gateway: metrics for each binding on the service (e.g. FTP metrics for service "ABC")

  • Operation: metrics for each operation on the service

  • Service Reference : metrics for references invoked by the service

• Reference : metrics for a composite reference in an application.  Additional metric details are provided for the following

  • Gateway : metrics for each binding on the reference (e.g. FTP metrics for reference "ABC")

  • Operation : metrics for each operation on the reference

This page also provides the user with the ability to reset metrics at various levels.

Application Views

SwitchYard contributes a page to the Runtime Operations section which provides views detailing various aspects of SwitchYard applications running on the system.  These views may be accessed on the Runtime page of the AS console by selecting Runtime Operations -> SwitchYard.  The following views are provided:

• Applications: lists all SwitchYard applications deployed on the server

• Services: lists all Services provided by the applications deployed on the server

• References: lists all service References used by applications deployed on the server

• Artifacts: lists all artifacts referenced by applications deployed on the server

Subsystem Configuration View

SwitchYard contributes an additional view to the standard JBoss AS management console's Profile page, which can be accessed by selecting the Subsystems -> SwitchYard -> Runtime Details node.  This page displays details about to the SwitchYard subsystem configured in the AS configuration profile.

This page displays the version of the SwitchYard runtime, along with a list of installed components.  Selecting a component will populate the Component Details section below, which displays:

• Name: the component name, e.g. SOAP, Camel.

• Type: the component type, e.g. soap, camel.  (The type is the suffix used within switchyard.xml identifying component specific elements, e.g. binding.soap, implementation.camel.)

• A section providing component specific details.  For most components, this section lists any configurable properties and their current settings.

Logging configuration options

You need to explicitly enable history logging for a particular process through the 'deploy.xml' file and for the BPEL engine in general through the 'bpel.properties' file. In order to record history data, set the 'process-events' option for a particular process and make sure the 'org.jboss.soa.bpel.console.bpaf.BPAFLogAdapter' is enabled.

Process configuration example (deploy.xml):

<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
	xmlns:bpl="http://www.jboss.org/bpel/examples"
	xmlns:intf="http://www.jboss.org/bpel/examples/wsdl">

	<process name="bpl:HelloGoodbye">
		<active>true</active>
        <process-events generate="all"/>
		<provide partnerLink="helloGoodbyePartnerLink">
			<service name="intf:HelloGoodbyeService" port="HelloGoodbyePort"/>
		</provide>
	</process>
</deploy>