As Keith mentioned in his postSwitchYard Plugin for Eclipse, we have some initial Eclipse based tooling for SwitchYard (prototype may be a better word as the tooling is likely to evolve rapidly in the next few months).
Prerequisites
The tooling may be installed atop any standard Eclipse IDE for JEE distribution version 3.6 or later. You may use another type of distribution, but you will need to figure out which features need to be installed; at a minumum you will need XML tools and JEE project facets.
In addition to the basic Eclipse platform, you will also need to install m2eclipse version 1.0 or later. (Note, for those of you using an older version of m2eclipse, this version is more tightly integrated and may require you to install additional Eclipse plugins to support specific Maven plugin executions. If you're not already using m2eclipse 1.0, you may want to use a separate Eclipse install until you are sure the latest version supports all the Maven plugins you are using.) If an update site for m2eclipse is not already configured in your Eclipse install, here's the URL: http://download.eclipse.org/technology/m2e/releases/
Installation
Keith did a great job describing the installation steps, so I won't rehash them here.
** The SwitchYard tooling is now available from the JBoss SOA Tools update site: http://download.jboss.org/jbosstools/updates/nightly/soa-tooling/trunk/
Features
This initial version of the tooling provides the following features:
- Creation of SwitchYard projects.
- Creation of SwitchYard bean service classes.
- Creation of SwitchYard service unit test classes.
- XML catalog entries for all SwitchYard project schema.
- m2eclipse support for the SwitchYard Maven plugin.
- Support for workspace deployment of SwitchYard projects.
New Wizards
All SwitchYard wizards are accessible from the SwitchYard category in the standard Eclipse new wizard:
New SwitchYard Project Wizard
The new project wizard creates a new maven project in your workspace whose pom contains the basic SwitchYard dependencies and build configuration. To create a new SwitchYard project, select SwitchYard Project.
The first screen is a basic new project screen, allowing you to specify the name and location of the new project:
The second page allows you to specify some basic project details, including the SwitchYard runtime version:
Press Finish and you'll have a new project ready for you to create some services.
New Bean Service Wizard
This wizard creates a new Java class with SwitchYard annotations that mark it as a bean service. In addition to creating the class, the pom may be updated to ensure the necessary dependencies are included in the project definition and to ensure that the SwitchYard Maven plugin is configured to scan for bean services.
Before opening the wizard, you should create a Java interface on which your service will be based. For best results, open the new wizard by right-clicking the interface file. selecting New, Other..., then select Bean Service under the SwitchYard category. The first page looks similar to the standard new class wizard. The main differences are the Service Interface field, which allows you to specify the interface on which the implementation will be based, and the Create test class option, which allows you to create a service test class, in addition to the implementation class. Here's a screenshot:
Press Finish and you should have a new Java class with a @Service annotation ready for coding. If you selected Create test class, you will also have a unit test ready to be implemented as well.
New Service Test Wizard
This wizard creates a new service test class. The class is created from Java interface used to define a service interface. The class that is created contains stub methods for each operation in the interface. The method stubs include code for passing a message to the operation and processing the result. You only need to initialize the message data and validate the results. The following illustrates the stubs that are created by the wizard:
@RunWith(SwitchYardRunner.class)
@SwitchYardTestCaseConfig(mixins = CDIMixIn.class, config = SwitchYardTestCaseConfig.SWITCHYARD_XML)
public class ExampleServiceTest {
@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);
}
}
As with the new bean service wizard, best results are obtained by opening the wizard via a right-click on the interface file. The wizard is a slimmed down version of the standard new class wizard, which only allows you to specify the service interface which you are testing. Here's a screenshot:
The Browse... button will allow you to browse all Java interfaces used by any SwitchYard services within the project. Here's a screenshot:
Press Finish on the wizard and you've got a unit test ready to be implemented. Just initialize the test messages and add some validation and you're off!
XSD Catalog
The tooling provides an XML catalog for resolving all namespaces declared within SwitchYard. For best results, uncheck Honour all XML schema locations in the XML file validation preferences. If you're seeing bizarre XML validation errors, you probably haven't unchecked this option. Here's a screenshot to help:
m2eclipse Support
The tools provide support for using the SwitchYard Maven plugin within Eclipse. The SwitchYard plugin will be invoked during an Eclipse build and supports auto/incremental builds. (Note, incremental builds may produce a switchyard.xml file that contains phantom elements. If you remove or rename services, i.e. @Service, you should run a clean build for best results.)
Workspace Deployment
The tools provide very crude support for workspace deployments. SwitchYard projects created through the new wizard are created as faceted projects, configured as Utility Modules. This will allow you to mark the project for deployment to a JEE server. That said, it's up to you to ensure the server configured to deploy and run SwitchYard applications. At some point, we will have proper integration with the Eclipse Servers, allowing deployment only to servers supporting SwitchYard deployments.
Gotchas
Here's a list of issues you should be aware of:
- If you do not have the JBoss Maven repository configured in your workspace, you may not get a list of SwitchYard runtime versions in the new project wizard. The tools now configure a custom repository pointing to JBoss public. This will not alter the behavior of project poms, but will allow the JBoss repository to be scanned by tooling components.
- The generated switchyard.xml file may contain phantom elements. Perform a clean build, Project, Clean..., to completely regenerate the fiile. (See m2eclipse Support above.) This has been fixed as part of
- Make sure you disable Honour all XML schema locations in the XML validation preferences. (See XSD Catalog above.)
- There is currently an NPE in the new bean service wizard. The workaround is to make sure Create test class is checked in the wizard (luckily, that's the default). Hopefully, this is fixed by the time you read this. This has been addressed.http://https://issues.jboss.org/browse/SWITCHYARD-471
- There is a bug in the new Service Test wizard that prevents its use when installed atop Eclipse 3.6. Make sure you uncheck "Create test class" in the new Bean Service wizard until this is fixed. (This is not an issue when using Eclipse 3.7.) https://issues.jboss.org/browse/SWITCHYARD-593
As with anything, if you find a bug or have a feature request, please file a JIRA: https://issues.jboss.org/browse/SWITCHYARD
Rob has created an initial version of a SwitchYard plugin for Eclipse. Please note the emphasis on initial, since this thing is just getting started. That said, I think it's already super valuable for SwitchYard developers because it wires us into the Eclipse build cycle via m2eclipse. This means auto-builds and unit tests can be run directly inside of Eclipse and you still get the benefit our our service scanners and config generation (which are implemented as Maven plugins). This feature alone is worth your time to install another plugin. Read on if you want to give it a try ....
The plugin is currently available through the SwitchYard-Tools Jenkins build here : goo.gl/cIxYH . From this link you can download the offline site archive (site_assembly.zip) or you can point directly at the following URL as an Eclipse update site:
That looks a little something like the following:
Rob has added a couple more features beyond the build lifecycle integration, so hopefully this will serve as bait for him to discuss them in greater detail. :-) Between Forge and JBDS, I think we have the foundation for a great tooling story in SwitchYard. Stay tuned.
