Overview

This tutorial takes you through the steps required to create, implement, test and deploy a SwitchYard application using the Eclipse tooling.  The application created provides a greeter service, implemented as a Java bean and accessible via a SOAP HTTP gateway.  This tutorial illustrates how to perform the following tasks:

• Create a SwitchYard project

• Create a Java service interface

• Create a bean component implementation

• Create and execute a unit test for the service

• Create a WSDL service interface

• Add a SOAP gateway for accessing the service

• Create a transformer

• Create and execute a unit test for the transformer

• Create and execute a unit test for the SOAP gateway

• Deploy the application to a server

• Test the deployed application

Install SwitchYard

Before beginning you will need the SwitchYard tooling and a SwitchYard runtime.

Install the SwitchYard tooling for Eclipse.  Instructions can be found here.

Install the SwitchYard runtime.  Instructions can be found here.

Create a Server

This step describes how to create a server definition for your SwitchYard runtime.  You will deploy your project to this server in a later step.  The server references a runtime definition which will be used when creating your SwitchYard project.

Open the Servers view in Eclipse.

Create a new server (right-click, New→Server).

Select JBoss Enterprise Application Platform 6.1 from the JBoss Enterprise Middleware category.  In this example, the Name field has been changed from its default value.

Press Next.

Specify the details for your server's runtime.  Specify the path to your SwitchYard runtime installation in the Home Directory field.

Press Finish.

Create a Project

This step describes how to create a project for the application.

From the new menu, select SwitchYard Project.  (See SwitchYard Projects for more details.)

The first page in the wizard is used for specifying the project name and location.

The next page is used for specifying various project details, including which SwitchYard components are required by the project.  In this example, the default package has been modified and the Bean and SOAP components have been selected.

Upon completion, a new project is created and the SwitchYard configuration will be open in the editor.

Create a Bean Component

This step describes how to create a bean component using the SwitchYard editor.  Upon completion of this step, you will have a component, providing a service (described by a Java interface), implemented by a bean.  The following resources will be created during this step:

• ExampleService.java describing the Java interface for the component's service.

• ExampleServiceBean.java providing the implementation for the component.

• component, component service and implementation elements in the SwitchYard configuration (i.e. the switchyard.xml file)

In the SwitchYard editor, drag the Bean tool from the Components section of the palette onto the canvas.  This opens a wizard prompting for details about the component.

Create a new interface by clicking the Interface link.  This opens the standard Eclipse New Interface wizard.  Specify a name for the interface (e.g. ExampleService), any other details and press Finish.

The service name field is initialized based on the type name used for the interface (e.g. ExampleService) and the class name field is initialized based on the service name (e.g. ExampleServiceBean).  Look over the fields and press Finish.

A new component shape should be added to the canvas.

Save the changes to the switchyard.xml file.

Flesh Out the Service Interface

This step describes how to flesh out the interface for the service.  The Java interface created in the previous step contained no methods, so you will add them here.  You will have a complete interface describing the service at the end of this step.

In the SwitchYard editor, double-click the service icon on the component (the green arrow on the left side of the component).  This opens the file describing the interface (ExampleService.java).

Add a method to the interface, for example:

package com.example.switchyard.example;

public interface ExampleService {

	public String sayHello(String name);

}

Implement the Bean

This step implements the service logic in the bean class.  There are compiler errors in the bean class because it does not implement the method you added to the interface in the previous step.  The errors are resolved by creating the missing methods in the bean class.  The project should have no errors at the end of this step.

In the SwitchYard editor, double-click the component (ExampleServiceBean) in the diagram.  This opens the file used to implement the component (ExampleServiceBean.java).

The file contains errors, since it does not implement required methods.

Add an implementation for the missing method.  (Using quick-fix, click the error icon and select, Add unimplemented methods.)

Update the implementation of the sayHello() method so it matches the following:

package com.example.switchyard.example;

import org.switchyard.component.bean.Service;

@Service(ExampleService.class)
public class ExampleServiceBean implements ExampleService {

	@Override
	public String sayHello(String name) {
		return "Hello, " + name;
	}

}

Create a Unit Test for the Service

This step describes how to create a unit test to verify the implementation of the service.  At the end of this step, you will have a unit test which sends a message to the service and verifies its output.  You will also execute the test using the native Eclipse JUnit support.  The following resources will be created during this step:

• ExampleServiceTest.java

In the SwitchYard editor, right-click the service icon on the component (the green arrow on the left side of the component) and select New Service Test Class.  This will open a wizard, which should be defaulted appropriately.  Look the fields over and press Finish.

Modify the testSayHello() method to properly exercise the service.  Initialize the message variable to "Bob" and update the Assert statement to verify the return value from the service is, "Hello, Bob"

package com.example.switchyard.example;

import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.switchyard.component.test.mixins.cdi.CDIMixIn;
import org.switchyard.test.Invoker;
import org.switchyard.test.ServiceOperation;
import org.switchyard.test.SwitchYardRunner;
import org.switchyard.test.SwitchYardTestCaseConfig;
import org.switchyard.test.SwitchYardTestKit;

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

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

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

        // validate the results
        Assert.assertTrue("Hello, Bob".equals(result));
    }

}

Run the tests by selecting Run As→JUnit Test.

Promote the Service

This step describes how to promote a component service to a composite service so the service can be accessed by external clients.  The promoted composite service will be described using a WSDL interface.  You will create the WSDL file using the Java-to-WSDL capabilities in the tooling.  Because the composite service exposes a different interface than the component service, you will need to create a couple of transformers to convert the between the different types (i.e. between the Java and WSDL types).  The following resources will be created during this step:

• ExampleService.wsdl describing the composite service interface

• ExampleServiceTransformers.java providing transformation logic for converting between ExampleService.java and ExampleService.wsdl

• composite service element in the SwitchYard configuration

In the SwitchYard editor, right-click the service icon on the component and select Promote Component Service.  This opens a wizard allowing you to specify the interface that will be exposed by the promoted service.  By default, the interface specified matches the interface used to describe the component service.

Change the interface type from Java to WSDL.  This blanks out the interface and name fields.

Press the Interface link to create a new WSDL file.  This opens the Java2WSDL wizard.

The first page of the Java2WSDL wizard is used for specifying the name and location for the WSDL file.  The default values should be appropriate.  Look them over and press Next.

The next page is used for specifying details about the generated WSDL.  The default values should be appropriate  Look the values over and press Finish.

The WSDL file is created and you are back on the Promote Component Service wizard.  The fields have been updated with details from the new WSDL file.  Notice that the Create required transformers button is checked and press Next.

The next page is the New Transformers page allowing you to create the required transformers.  Notice the two transformer type pairs checked in the table correspond to the input and output types declared on the two interfaces.  Ensure both pairs are checked and Java Transformer is selected as the Transformer Type and press Next.

The next page collects information for a new Java class that will be used to implement the transformers.  Specify ExampleServiceTransformers for the name and leave org.w3c.dom.Element selected as the Java type to be used to represent XML/ESB types in the transformer class.  Press Finish.

A new composite service promoting the component service should have been added to the SwitchYard configuration.  Save the editor.

Select the main shape in the SwitchYard editor and review the contents of the Transforms tab in the Properties view.  The newly added transformers should be listed.

	@Test
	public void testSayHelloTransform() throws Exception {
		final QName inputType = QName
				.valueOf("{urn:com.example.switchyard:switchyard-example:1.0}sayHello");
		final QName outputType = QName
				.valueOf("{urn:com.example.switchyard:switchyard-example:1.0}sayHelloResponse");
		// initialize your test message
		Object message = "<sayHello xmlns=\"urn:com.example.switchyard:switchyard-example:1.0\"><string>Bob</string></sayHello>";
		String result = service.operation("sayHello").inputType(inputType)
				.expectedOutputType(outputType).sendInOut(message)
				.getContent(String.class);

		// validate the results
		String control = "<sayHelloResponse xmlns=\"urn:com.example.switchyard:switchyard-example:1.0\"><string>Hello, Bob</string></sayHelloResponse>";
		Assert.assertTrue("Unexpected result: " + result,
				XMLUnit.compareXML(control, result).identical());
	}

	@Transformer(to = "{urn:com.example.switchyard:switchyard-example:1.0}sayHelloResponse")
	public String transformStringToSayHelloResponse(String from) {
		// TODO: properly escape the input string
		return "<sayHelloResponse xmlns=\"urn:com.example.switchyard:switchyard-example:1.0\"><string>"
				+ from + "</string></sayHelloResponse>";
	}

	@Transformer(from = "{urn:com.example.switchyard:switchyard-example:1.0}sayHello")
	public String transformSayHelloToString(Element from) {
		return from.getTextContent();
	}

Test the Deployed Service

This step describes how to test the service using a SOAP HTTP clients.  You will use the web services tester that ships with Eclipse, but you could use the web services test/debug tool you are most familiar with.

Right-click the WSDL file (ExampleService.wsdl) and select Web Services→Test with Web Services Explorer.  Exercise the service using the tester.

View Details in the Management Console

Right-click the server in the Servers view and select Show In→Web Management Console.  Refer to the SwitchYard management console documentation for details.