This section of the guide provides basic details on how to install the SwitchYard distribution on your system.
SwitchYard is available pre-installed in JBoss Application Server (AS) or as a separate download for install in an existing JBoss AS installation. The following SwitchYard distributions are available:
- switchyard-as7 : includes SwitchYard and JBoss AS version 7.1.1 Final of the JBoss Application Server.
- switchyard-installer : includes SwitchYard runtime and an installation script to install SwitchYard into a JBoss AS7 of your choice.
- switchyard-tools : contains the SwitchYard administration console web application and Forge plugins.
All versions of SwitchYard can be downloaded from JBoss.
SwitchYard is low on prerequisites. The only things you need check are:
- You are running on a Java 6 JDK.
- You have a configured instance of Maven 3 for building the SwitchYard Quickstarts.
Download the SwitchYard Distribution Zip file and simply unzip it into a suitable location on your file system.
|It is not mandatory to configure $JBOSS_HOME on your system, but if you already have it configured you will need to reset it to point to the root of the unzipped SwitchYard AS7 distribution.|
To start the SwitchYard AS instance simply open a command terminal, change directory into the distribution bin directory and execute the "standalone" command script (standalone.sh on Unix/Linux/MacOS and standalone.bat on Windows).
The easiest way to get started with testing an application on SwitchYard is to take one of the distribution's Quickstart examples and run it. All of the example applications in our Quickstarts repository are included in quickstarts/ directory of your installation.
The Quickstarts provided in the distribution are source only i.e. they are not pre-built. Building them is very easy. You just need to make sure you have Maven 3 configured on your system and then simply execute mvn clean install in the root of the quickstarts folder.
For the purpose of testing your SwitchYard distribution and simply getting something running quickly, the following quickstart applications are a good jumping off point:
- bean-service : implementing a service using a CDI bean and exposing that over a SOAP gateway
- bpm-service : using BPMN 2 to provide and consume SwitchYard services
- camel-service : basic routing example using XML and Java DSL Camel routes
- camel-jms-binding : demonstrates how a Camel component can be used as a SwitchYard gateway
- demos/orders : web application which invokes a SwitchYard service from a JSF
These quickstarts are just a small sample of the available example applications. Check out the other apps for examples of other features in SwitchYard.
Running the Quickstarts in Eclipse
The SwitchYard quickstarts can also be easily run in Eclipse.
To do this, you have to first modify the default Eclipse configuration to avoid XML cosmetic errors:
- Configure XML Validation to Avoid Cosmetic Errors
- Navigate to: Window->Preferences->XML->XML Files->Validation
- Uncheck "Honour all XML schema locations"
To import a SwitchYard quickstart into Eclipse:
- Import a SwitchYard Quickstart
- Navigate to: File->Import->Maven->Existing Maven Projects
- Select the quickstart that you want to import from the SwitchYard Quickstart directory (e.g., /local/opt/switchyard/switchyard-as7-0.6/quickstarts/bean-service)
Once the quickstart is imported, you then deploy it to a SwitchYard enabled server and execute the quickstart's client class as a JUnit test.
For more information on installing and using SwitchYard tooling in Eclipse, see: https://docs.jboss.org/author/display/SWITCHYARD/Eclipse
Forge is a rapid-application development tool focused on a shell-based interface with application developers. The SwitchYard project has a set of plugins for Forge which dramatically decrease the amount of time needed to create a new application. If you plan to develop SwitchYard applications, we highly recommend using the Forge or Eclipse tooling (or both!).
The first step is to install Forge itself, which is covered nicely in the Forge documentation. Please be sure to download Forge 1.0.2 Final, which can be found here. As part of installation, be sure to setup the $FORGE_HOME environment variable.
Once Forge is installed it's time to install the SwitchYard extensions to Forge. The easiest way to install them is to download the SwitchYard Installer and run:
The installer will ask if you want to install other pieces of the distribution aside from the Forge tooling. Just answer 'no' to any pieces that you don't want to install.
For more details on using the Forge tooling for SwitchYard, please see the User Guide.
The easiest way to get started with the SwitchYard (SY) tooling is to install the latest version of JBDS (https://devstudio.jboss.com/download/) first, then install the SY tooling from the offline installation update site.
|SwitchYard 0.7 tooling requires JBDS 6. Please make sure you add the update sites listed in step 3 before trying to install the SwitchYard plugins or the installation will fail.|
|Please make sure to disable Honour all XML schema locations in preferences, XML→XML Files→Validation after installation. This will prevent erroneous XML validation errors from appearing on switchyard.xml files.|
- Download and install the latest version of JBDS (https://devstudio.jboss.com/download/).
- Download a release version of the offline update site ZIP (switchyard-site-assembly) from the SwitchYard Downloads page.
As an alternative, you may install directly from the update site here: http://download.jboss.org/jbosstools/updates/stable/juno/soa-tooling/switchyard/
- Select Window→Preferences from the main menu bar, go to Install/Update→Available Software Sites, and Add... the following sites:
- Select Help-->Install New Software... from the main menu bar.
- Press the Add... button to add the SwitchYard tooling software site zip. Click the Archive... button and specify the location of the downloaded zip.
- Once the software site has been configured, SwitchYard Tools should be displayed in the list of available software. Check the box, press Next and proceed through the rest of the wizard. (Refer to the Eclipse documentation for more information on software installation.)
- (When the installation is complete, you can also install the latest BPMN2 Modeler editor from Eclipse if you will be editing any BPM-related files. Repeat steps 3, 4, and 5, but specify the location of the repository as: http://download.eclipse.org/bpmn2-modeler/site/0.1.0/.)
Configure the following update sites in your Eclipse installation:
- For Juno (Eclipse 3.8/4.2):
- SwitchYard Tools: http://download.jboss.org/jbosstools/updates/integration/juno/soa-tooling/switchyard/
- JBoss Tools: http://download.jboss.org/jbosstools/updates/development/juno/
- Eclipse BPMN2 Modeler: http://download.eclipse.org/bpmn2-modeler/site/0.2.2/
- For Indigo (Eclipse 3.7):
- SwitchYard Tools: http://download.jboss.org/jbosstools/updates/development/indigo/soa-tooling/switchyard/0.6.0/
- JBoss Tools: http://download.jboss.org/jbosstools/updates/stable/indigo/
- Eclipse Graphiti: http://download.eclipse.org/graphiti/updates/0.9.0
- Eclipse BPMN2 Modeler: http://download.eclipse.org/bpmn2-modeler/site/0.1.0/
|All of these sites need to be defined, even if you don't plan on installing any features from them as they provide dependencies required by the SwitchYard tools.|
|Make sure you reference the correct update site for JBoss Tools, especially if you are installing SwitchYard into an instance of Eclipse Indigo as using a newer update site (e.g. nightly) may cause platform instability. The JBoss Tools update site listed above will work fine for Indigo based installs.|
|SwitchYard 0.6 and earlier require a version of m2e-wtp which is incompatible with the version used by JBT 4.0. This means SY <= 0.6 and earlier can only be installed with JBT 3.3 and SY > 0.6 can only be installed with JBT 4.0.|
|THE FOLLOWING IS NOT SUPPORTED, but provided for those who cannot use Juno, but want to give SwitchYard a try. Newer, Juno based SwitchYard tools may be installed on an Indigo platform by following the instructions for installing on Indigo with the following changes: use the SwitchYard update site URL that is listed in the Juno instructions; add the following update site URL prior to installation. Please note this will make your install incompatible with other m2e features provided by JBoss Tools and possibly other JBT features as well (i.e. this will make your Indigo install incompatible with JBoss Tools). Here's the extra update site URL: http://download.eclipse.org/m2e-wtp/releases/|
Best results may be obtained by installing the following features:
- Eclipse IDE for Java EE Developers (required): http://www.eclipse.org/downloads/
- SwitchYard Tooling (required):
- SwitchYard Tools - The core tooling.
- SwitchYard Editor - The SwitchYard configuration editor and BPMN2 modeler custom task support.
- JBoss Tools (optional):
- JBoss Maven Support (at a minimum, JBoss Maven Integration) - provides additional m2e support for JEE.
- JBoss AS Tools (under Abridged JBoss Tools or JBoss Web and Java EE Development) - provides support for workspace deployment.
- Eclipse BPMN2 Modeler (optional):
If you'd rather not install all of JBDS, you can also install the SwitchYard tooling on top of 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 minimum 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 plug-ins to support specific Maven plug-in 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 plug-ins 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/
You may also wish to install the latest version of the BPMN2 Modeler from Eclipse if you will be editing any BPMN2-related files. That update site is located here: http://download.eclipse.org/bpmn2-modeler/site/
If you decide to install using the offline update site for SwitchYard tooling, be aware you will need to also install some functionality from JBoss Tools for more Maven support. To satisfy this extra dependency, you can install just the "JBoss Maven Support" from the JBoss Tools 3.3 site - http://download.jboss.org/jbosstools/updates/stable/indigo/
- The SwitchYard Eclipse plug-ins may be installed by launching Eclipse and selecting Help-->Install New Software... from the main menu bar.
- Press the Add... button to add the SwitchYard tooling software site:
- Specify a name for the site (e.g. JBoss SOA Tools - Nightly). For the location, specify http://download.jboss.org/jbosstools/updates/nightly/soa-tooling/3.3.x/
For offline installation, a ZIP of the software site may be downloaded from http://hudson.jboss.org/hudson/job/SwitchYard-Tools/lastSuccessfulBuild/artifact/sources/eclipse/site/target/site_assembly.zip. Once downloaded, specify the location of the ZIP in the "Add Repository" dialog (press Archive...).
Once the software site has been configured, SwitchYard Tools should be displayed in the list of available software. Check the box, press Next and proceed through the rest of the wizard. (Refer to the Eclipse documentation for more information on software installation.)