Overview

This page documents installation and use of Seam Forge to create SwitchYard applications.  If you have not heard of Seam Forge, check out the project page for some background.  In a nutshell, Forge is a rapid application development tool that allows you to quickly create, scaffold, configure, and build application projects.  The nice thing about Forge is that it bridges the gap between the initial creation of the project (typically handled via Maven archetypes) and implementation of services.  You can get a lot done with Forge, quickly, without using the IDE.

Installation

The first step is to install Forge itself, which is covered nicely in the Forge documentation.  Make sure you setup the FORGE_HOME environment variable.

Next, you need to download and install a SwitchYard distribution and add the SwitchYard plugins to your Forge environment.  All of this is covered in the Getting Started guide, btw.

Projects

Forge allows you to create new, Maven-based projects with the new-project command:

$ forge
   ____                          _____                   
  / ___|  ___  __ _ _ __ ___    |  ___|__  _ __ __ _  ___
  \___ \ / _ \/ _` | '_ ` _ \   | |_ / _ \| '__/ _` |/ _ \  \\
   ___) |  __/ (_| | | | | | |  |  _| (_) | | | (_| |  __/  //
  |____/ \___|\__,_|_| |_| |_|  |_|  \___/|_|  \__, |\___|
                                                |___/     

[no project] tmp $ new-project --named syApp --topLevelPackage org.switchyard.examples.forge
Use [/private/tmp/syApp] as project directory? [Y/n]
Wrote /private/tmp/syApp/src/main/resources/META-INF/forge.xml
***SUCCESS*** Created project [syApp] in new working directory [/private/tmp/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 allow capabilities to be added to an application and to the forge environment itself.  We use facets in SwitchYard to add dependencies to you Maven 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 for SwitchYard itself and components which you will be using in your application.  At present, we have the following facets 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 "project install-facet <facet name>".

Building an App

This section serves as a quick and dirty walkthrough for creating a SwitchYard application with forge.  It is assumed that you have already created a new project as described above.

First step is to install the core SwitchYard facet.  Be sure to choose the 0.1.0 version for all SwitchYard facets!

[syApp] syApp $ project install-facet switchyard
Please select a version to install:

  1 - [org.switchyard:switchyard-api:0.1.0-M1]
  2 - [org.switchyard:switchyard-api:0.1.0]

Choose an option by typing the number of the selection: 2
Application name (e.g. myApp) syApp
***SUCCESS*** Installed [switchyard] successfully.

Now it's time to add a service.  Let's implement a service using CDI, shall we? First we need to install the switchyard.bean facet, then issue a command to create our bean service.

[syApp] syApp $ project install-facet switchyard.bean
Please select a version to install:

  1 - [org.switchyard.components:switchyard-component-bean:0.1.0-M1]
  2 - [org.switchyard.components:switchyard-component-bean:0.1.0]

Choose an option by typing the number of the selection: 2
Wrote /private/tmp/syApp/src/main/resources/META-INF/beans.xml
***SUCCESS*** Installed [switchyard.bean] successfully.

[syApp] syApp $ bean-service create --serviceName ExampleService
Java package for service interface and implementation: org.examples.switchyard
Wrote /private/tmp/syApp/src/main/java/org/examples/switchyard/ExampleService.java
Wrote /private/tmp/syApp/src/main/java/org/examples/switchyard/ExampleServiceBean.java
Created service interface [ExampleService]
Created service implementation [ExampleServiceBean]
NOTE: Run 'mvn package' to make ExampleService visible to SwitchYard shell.

Go ahead and run the "mvn package" command and then list the project's services to see what shows up.  NOTE: the mvn command is required because we automatically generate SwitchYard configuration off of the CDI classes in our Maven plugin.  You only have to do this once.

[syApp] syApp $ mvn package
.... [lots of output] ....

[syApp] syApp $ switchyard show-config
[Public]

[Private]
component: ExampleService
   service: ExampleService
      interface: org.switchyard.examples.forge.ExampleService

Now we would like to make this service public so that other applications can consume it.  That's a simple matter of promoting it.

[syApp] syApp $ switchyard promote-service --serviceName ExampleService
Promoted service ExampleService

[syApp] syApp $ switchyard show-config

[Public]
service: ExampleService
   interface: inherited

[Private]
component: ExampleService
   service: ExampleService
      interface: org.switchyard.examples.forge.ExampleService

Our last step is to add a SOAP binding to our promoted service so that external clients can invoke it.

[syApp] syApp $ project install-facet switchyard.soap
Please select a version to install:

  1 - [org.switchyard.components:switchyard-component-soap:0.1.0-M1]
  2 - [org.switchyard.components:switchyard-component-soap:0.1.0]

Choose an option by typing the number of the selection: 2
***SUCCESS*** Installed [switchyard.soap] successfully.

[syApp] syApp $ soap-binding bind-service --serviceName ExampleService --wsdl wsdl/exampleService.wsdl
Added binding.soap to service ExampleService

[syApp] syApp $ switchyard show-config

[Public]
service: ExampleService
   interface: inherited
   binding: soap

[Private]
component: ExampleService
   service: ExampleService
      interface: org.switchyard.examples.forge.ExampleService

Now we're cooking.  At this point, your work with Forge is done and the following work remains:

• Customize your Bean service interface and implementation based on your service's requirements
• Create exampleService.wsdl and drop it into the wsdl/ directory of the application

After that, you are ready to deploy.  To get an idea of the work that Forge has done for us, let's take a look at the SwitchYard deployment descriptor that will be deployed along with the app:

<switchyard xmlns="urn:switchyard-config:switchyard:1.0">
    <composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912" name="syApp">
        <service name="ExampleService" promote="ExampleService">
            <binding.soap xmlns="urn:switchyard-component-soap:config:1.0">
                <wsdl>wsdl/exampleService.wsdl</wsdl>
            </binding.soap>
        </service>
        <component name="ExampleService">
            <service name="ExampleService">
                <interface.java xmlns="urn:switchyard-component-bean:config:1.0" interface="org.examples.switchyard.ExampleService"/>
            </service>
            <implementation.bean xmlns="urn:switchyard-component-bean:config:1.0" class="org.examples.switchyard.ExampleServiceBean"/>
        </component>
    </composite>
</switchyard>

Writing that by hand would have sucked. Thanks Seam Forge!