Red Hat JBoss Fuse Tooling

Tooling User Guide

Developing and Debugging Applications

Red Hat

Version 6.3

Copyright © 2011-2015 Red Hat, Inc. and/or its affiliates.

Trademark Disclaimer

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Apache, ServiceMix, Camel, CXF, and ActiveMQ are trademarks of Apache Software Foundation. Any other names contained herein may be trademarks of their respective owners.

06 Dec 2016

Abstract

This guide describes how to use the Red Hat JBoss Fuse Tooling, which provides developer tools designed to increase your productivity when designing, developing, testing, and debugging your integration applications.

About Red Hat JBoss Fuse Tooling

Red Hat JBoss Fuse Tooling provides a set of developer tools that enable you to work with Fuse versions of Apache ActiveMQ, Apache Camel, and Apache CXF within Red Hat JBoss Development Studio. You can connect and configure Enterprise Integration Patterns to build routes, browse endpoints and routes, drag and drop messages onto running routes, trace message flows, edit running routes, browse and visualize runtime processes via JMX, debug routes, and deploy your project's code to both Red Hat JBoss Fuse and Red Hat JBoss EAP containers.

Using Red Hat JBoss Fuse Tooling simplifies and streamlines the process of developing integration applications by providing tooling that is specifically designed to work with:

Red Hat JBoss Fuse

Red Hat JBoss EAP

Red Hat JBoss A-MQ

Apache Camel

Apache CXF

Apache Karaf

Note

You can also develop Fuse projects using Maven (for details, see Getting Started with Developing).

Using the Red Hat JBoss Fuse Tooling streamlines the process at all stages of application development:

Create a Maven project for your application.

The tooling loads all of the relevant Maven archetypes for creating integration projects using the Red Hat supported Apache projects.

Add new pieces of logic and functionality to an application.

The tooling has a wizard for creating Apache Camel context files.

Edit the integration logic.

The tooling has a visual route editor that makes editing Apache Camel routes as easy as dragging and dropping routing components.

Debug your local Camel context.

The tooling includes a full-featured Camel debugger for debugging locally running Camel contexts.

Test the application.

The tooling includes testing tools that provide the full gamut of testing capabilities including:

creating and using JUnit test cases on Apache Camel routes

using JMX to analyze running components

tracing messages through Apache Camel routes

Deploy the application.

The tooling can deploy applications to a number of containers.

Note

See the Red Hat JBoss Fuse Tooling Tutorials for step-by-step instructions on:

Creating a Route

Running a Route

Adding a Content-Based Router

Adding Another Route to the CBR Routing Context

Debugging a Routing Context

Tracing a Message Through a Route

Testing a Route with JUnit

Publishing a Fuse Project to Red Hat JBoss Fuse

Part I. Introducing the Fuse Tooling User Interface

Red Hat JBoss Fuse Tooling is an Eclipse-based IDE for creating and testing small- and large-scale integration applications. Its key features are a graphical routing editor, a full-featured Camel debugger for debugging locally running routing contexts, and an integrated testing platform that uses JMX to communicate with the containers in a small-scale test environment.

The tooling provides two main perspectives. You use Chapter 1, Fuse Integration Perspective to design, test and publish your Fuse Integration projects. You use Chapter 2, Debug Perspective to debug your routing context files.

Chapter 1. Fuse Integration Perspective

Overview

The Fuse Integration perspective, shown in Figure 1.1, provides access to all of the tooling for designing, monitoring, testing, and publishing your integration application.

Figure 1.1. Fuse Integration perspective

Note

You can open Fuse Integration perspective in two ways:

Have the tooling switch to Fuse Integration perspective when you create a new Fuse Integration project (see the section called “Setting advanced project options”).

Click Fuse Integration perspective on the right side of the JBoss Developer Studio tool bar. If the Fuse Integration perspective icon is not available on the tool bar, click Fuse Integration perspective and then select Fuse Integration from the list of available perspectives.

Fuse Integration perspective consists of nine main areas:

Project Explorer—displays all of the projects known to the tooling. You can view all of the artifacts that make up each project. Project Explorer also displays all of the routing context .xml. files for a project under its Camel Contexts node. This makes it easy for you to find and open a routing context file included in a project. Under each routing context .xml file, it displays all routes defined within the context. For multiroute contexts, this makes it easy for you to switch your focus to a specific route on the canvas.

The route editor—The route editor provides the main design-time tooling and consists of three views:

Design view—Displays a large grid area on which routes are constructed and a palette from which Enterprise Integration Patterns (EIPs) and Camel components are selected and then connected on the canvas to form routes.

The canvas is the route editor's workbench and where you do most of your work. It displays a graphical representation of one or more routes, which are made up of connected EIPs and Camel components (called nodes once they are placed on the canvas).

Selecting a node on the canvas populates the Properties editor with the properties that apply to the selected node, so you can edit them.

The Palette contains all of the patterns and Camel components needed to construct a route and groups them according to function—Components, Routing, Control Flow, Transformation, and Miscellaneous.

Source view—Displays the .xml configuration corresponding to the routes constructed on the route editor's canvas

You can edit the routing context in Source view as well as in Design view.

Configurations view—Provides an easy way to add shared configuration (global endpoints and data formats) to a multiroute, routing context. For details see the section called “Adding global endpoints and data formats”.

Properties editor—displays the properties of the node selected on the canvas.

JMX Navigator—lists the JMX servers and the infrastructure they monitor. It enables you to browse JMX servers and the pocesses they are monitoring. It also identifies instances of Red Hat processes.

JMX Navigator drives all monitoring and testing activities in Fuse Integration perspective. It determines which routes are displayed in Diagram View, the Properties viewer, and Messages View. It is also provides menu commands for activating route tracing, adding and deleting JMS destinations, and starting and suspending routes. It is also the target for dragging and dropping messages onto a route.

By default, JMX Navigator shows all of the Java processes running on your local machine. You can add JMX servers as needed to view infrastructure on other machines.

Diagram view—displays a graphical tree representing the node selected in JMX Navigator. When you select a process, server, endpoint, or other node, Diagram view shows the selected node as the root with branches down to its children and grandchildren.

When you select a broker, Diagram View displays up to three children: connections, topics, and queues. It also shows configured connections and destinations as grandchildren.

When you select a route, Diagram view displays all of the nodes in the route and shows the different paths that messages can take through it. It also displays timing metrics for each processing step in the route when route tracing is enabled.

Messages view—lists the messages that have passed through the selected JMS destination or through Apache Camel endpoints when route tracing is enabled.

When a JMS destination is selected in JMX Navigator, the view lists all of the messages sitting in the destination.

When route tracing is enabled, Messages View lists all of the messages that passed through the nodes in the route since tracing started. You can configure Messages View to display only the data in which you are interested and in your preferred sequence.

When a message trace in Messages View is selected, its details (message body and all message headers) are displayed in the Properties viewer. In Diagram View, the step in the route associated with the selected message trace is also highlighted.

Servers view—displays a list of servers managed by the tooling. It displays their runtime status and provides controls for adding, starting and stopping them and for publishing projects to them.

Terminal view—Displays the command console of the connected container. You can control the container by entering commands in Terminal view.

Console view— displays the console output for recently executed actions.

Related topics

Part II, “Developing Applications”

Part IV, “Monitoring and Testing Applications”

Part V, “Publishing Applications to a Container”

chapter "To Create a New Route" in "Tooling Tutorials"

Chapter 2. Debug Perspective

Overview

The Debug perspective, shown in Figure 2.1, provides access to all of the Camel debugger's functions. It contains all of the views used to monitor and debug a running routing context.

Figure 2.1. Debug perspective

Debug view

For the running routing context, Debug view displays the debug stack.

You can switch between breakpoints within the same message flow, listed under the Camel Context at service:jmx:rmi://jndi/rmi://localhost:1099/jmxrmi/camel entry, to review and compare variable values in Variables view.

Messages flows are identified by their unique breadcrumb ID, and the breadcrumb ID of each subsequent message flow is incremented by 2. For example, in Figure 2.1, “Debug perspective”, the breadcrumb ID for the first message flow is ID-janemurpheysmbp-home-54620-1470949590275-0-1, so the breadcrumbID for the second message flow would be ID-janemurpheysmbp-home-54620-1470949590275-0-3.

Variables view

For each node in the routing context that has a breakpoint set, Variables view displays the value of the available variables when the breakpoint is hit. Each variable who's value changed since the preceding breakpoint is highlighted in yellow.

You can change the value of editable variables to check whether such changes produce the expected results and to test the robustness of your routing context.

You can also add variables to the watch list, so you can quickly and easily see whether their values change as expected at the expected point in the message flow.

Breakpoints view

Displays a list of the breakpoints set in the routing context, and shows whether they are enabled or disabled. You can enable and disable individual breakpoints by checking (enabling) or unchecking (disabling) them. This enables you to temporarily focus on nodes in your routing context that are behaving problematically.

The Debug perspective button skips over disabled breakpoints to jump to the next active breakpoint in the routing context. In contrast, the Debug perspective button jumps to the next node of execution in the routing context, regardless of breakpoints.

camel Context.xml view

Displays the running routing context file in graphical mode. For nodes set with breakpoints, it shows the type of breakpoint set and whether the breakpoint is enabled or disabled. When a breakpoint is hit, its corresponding node on the canvas is outlined in red.

To check a node's configuration, open Properties view and then select the node on the canvas in camel Context.xml view.

Console view

Displays the log output generated by the Camel debugger as it executes the routing context.

Properties view

Displays the properties set for the node selected on the canvas in CamelContext.xml view.

Related topics

Part III, “Debugging Routing Contexts”

chapter "To Debug a Routing Context" in "Tooling Tutorials"

Part II. Developing Applications

Note

You can also develop Fuse projects using Maven. For details, see Getting Started with Developing.

Chapter 3. Creating a New Fuse Integration Project

Overview

Creating a new Fuse Integration project involves three steps.

Configuring project basics

Creating a new target runtime or selecting an existing target runtime or Camel version on which to base the project

Setting the advanced project options

Once the project has been configured, the tooling configures all of the required Maven dependencies and creates the POM file needed to run and publish the project. The preconfigured templates, based on common use cases, also provide sample code and data to get you started quickly.

Configuring project basics

Select File → New → Other → JBoss Fuse → Fuse Integration Project to open the New Fuse Integration Project wizard:

The wizard opens with the Use default workspace location option selected in the Location pane.

In Project Name, enter a name for the new project.

Specify the workspace location where the data for the project will be stored.

To use the default workspace leave Use default workspace location enabled.

To use an alternative location clear Use default workspace location and specify a new location in the Path field.

Click Browse button to quickly find and select the alternate workspace.

Click Next to open the Select a Target Runtime page:

You can base you new Fuse Integration project on either a target runtime or on a specific version of Camel.

Target Runtime—Specify the runtime to which you want to publish the new project.

You can either select an existing configured runtime from the drop-down menu, or create a new one.

In either case, the Camel Version pane displays the Camel version associated with the runtime once it is selected.

Camel Version—You can specify the Camel version on which to base the new project, without creating or selecting a target runtime. The tooling supports only the options available from the drop-down list.

Important

If you select an existing, configured target runtime or a specific Camel version on which to base your new Fuse Integration project, you need only set the project's advanced options (See the section called “Setting advanced project options”. Otherwise, you need to create a new target runtime before you set the project's advanced options (see the section called “Creating a new target runtime”).

Creating a new target runtime

With the Select a Target Runtime page open:

In the Target Runtime pane, click the New button to open the New server runtime environment page:

Scroll up to and expand the JBoss Fuse folder, and then select a JBoss Fuse runtime environment (for example JBoss Fuse 6.3).

Leave the Create a new local server option disabled. You can create the local server later when you are ready to publish your project to it (for details, seethe section called “Adding a Server”).

Note

If you click the Create a new local server option, the New Fuse Integration Project wizard walks you through additional steps to define and configure the new JBoss Fuse 6.3 server runtime (as described in the section called “Adding a Server”). Then, when it builds the project, it also adds the server runtime to the Servers panel in Fuse Integration perspective.

Click Next to open the server's Runtime Definition page:

Specify the Name, Home Directory, and Execution Environment of the server runtime:

Name—accept the default, or enter a new name for the runtime environment

Home Directory—click the Browse button to locate and select the server runtime's installation directory

Note

If the server is not already installed on your machine, you can install it now by clicking the link Download and install runtime... and following the site's download instructions. Depending on the site, you may be required to provide valid credentials before you can continue the download process.

Execution Environment—accept the default, or select another JavaSE version from the drop-down menu

If the version you want does not appear on the list, click the Environments button and select the version from that list. The JRE version you select must be installed on your machine.

Note

JBoss Fuse 6.3 requires either JRE version 1.8 (recommended) or 1.7.

Alternate JRE—Leave as is

Important

If you need to modify the configuration of an existing target runtime, you do so by selecting, from the menu bar, JBoss Developer Studio → Preferences → JBoss Fuse → Server → Runtime Environments to open the Server Runtime Environments page. (On Linux and Windows machines, you access Preferences through the Windows menu.) In the Name pane, select the runtime you want to modify, and click Edit to open the server's Runtime Definition page. You can change the Name of the target runtime, its Home Directory, and its Execution Environment.

Click Finish to return to the Select a Target Runtime page:

The newly configured target runtime appears in the Target Runtime pane's drop-down menu, and the Camel version supported by the runtime appears in the Camel Version pane, grayed out.

To finish, set the advanced project options as described in the section called “Setting advanced project options”.

Setting advanced project options

With the completed Select a Target Runtime page open:

Click Next to open the Advanced Project Setup page.

You can create an empty project, which creates a skeleton Camel context routing file based on one of the three supported Domain Specific Languages (DSLs), or you can use a predefined template, each of which is based on a common use case. Individual templates may not support all DSL options.

Note

For Java DSL, the tooling generates a CamelRoute.java file that you can edit in the tooling's Java editor, but it does not generate a graphical representation of it in Diagram view.

Start with an empty project:

For an empty project, all DSL options are available.

Use a predefined template:

The options are:

ActiveMQ—Provides a sample Camel route that reads messages from a specific location and routes them to a message queue. Another route, implementing a content-based router, pulls the messages off the queue and routes each to its target destination, according to message content.

Note

Before you can deploy this project, you must create, in your Red Hat JBoss Fuse installation, a pid file that configures the ActiveMQ connection properties. For details, open the ReadMe.txt file, listed under the project root in Project Explorer.

This template creates a project that runs on Red Hat JBoss Fuse servers, and it supports the Blueprint and Spring DSLs only.

Content Based Router—Provides a sample Camel route that reads messages from a specific location and routes them to different output folders according to message content.

This template creates a project that runs on Red Hat JBoss Fuse servers, and it supports all three of the supported DSLs.

CXF code first—Provides a sample Camel route that is started by a CXF web service call.

This template creates a project that runs on Red Hat JBoss Fuse servers, and it supports the Spring and Java DSLs only.

Spring on EAP—Provides a sample Camel route that calls into a bean service to say Hello.

This template creates a project that runs on Red Hat EAP 6.4 servers, and it supports the Spring DSL only.

Select one of the project setup options and a DSL (as available), and then click Finish.

The tooling starts building the project, adding it to Project Explorer.

If you are not already in Fuse Integration perspective, the tooling asks whether you want to switch to it now:

Click Yes to open the new project in Fuse Integration perspective:

In this example, the CBRroute project appears in Project Explorer. CBRroute would have been the name entered in the Project Name field in Step 2.

Click the Source tab at the bottom of the canvas to see the generated Camel context file:

Resolving Maven dependency errors

You may encounter Maven dependency errors after you create a new Fuse Integration project.

Though it can happen at other times, it more typically occurs when a project build is canceled before the process has finished. Interrupting the process in this way often prevents all of the project's dependencies from downloading from the Maven repositories, which can take some time.

You can often resolve these dependency errors by updating Maven dependencies this way:

In Project Explorer, select the root project just created.

Right-click it to open the context menu.

Select Maven → Update Project...

In the Update Maven Project wizard:

Select the project you want to update, if more than one appears in the wizard's list.

Click the Force Update of Snapshots/Releases option to enable it.

Click OK.

In the bottom, right corner of the workbench, you may see the progress status bar churning as missing dependencies are downloaded from the Maven repositories.

Related topics

chapter "To Create a New Route" in "Tooling Tutorials"

Chapter 4. Creating a New Camel XML file

Overview

Apache Camel stores routes in an XML file that contains a camelContext element. The tooling includes a wizard that simplifies adding an Apache Camel context file to your project. It creates a new XML file that has all of the required namespaces preconfigured and a template camelContext element.

Procedure

To add a new Apache Camel context file to your project:

Select File → New → Other... → JBoss Fuse → Camel XML File from the main menu to open the Camel XML File wizard, as shown in Figure 4.1, “Camel XML File wizard”.

Figure 4.1. Camel XML File wizard

In RouteContainer, enter the location for the new file, or accept the default.

You can click Browse... button to search for an appropriate location.

Important

The Spring framework and the OSGi Blueprint framework require that all Apache Camel files be placed in specific locations under the project's META-INF or OSGI-INF folder:

Spring—projectName /src/main/resources/META-INF/spring/

OSGi Blueprint—projectName /src/main/resources/OSGI-INF/blueprint/

In File Name, enter a name for the new context file, or accept the default (camelContext.xml).

The file's name cannot contain spaces or special characters, and it must be unique within the JVM.

In Framework, accept the default, or select which framework the routes will use:

Spring—[default] for routes that will be deployed in Spring containers, non-OSGi containers, or as standalone applications

OSGi Blueprint—for routes that will be deployed in OSGi containers

Routes—for routes that you can load and add into existing camelContexts

Click Finish.

The new context file is added to the project and opened in the route editor.

Chapter 5. Editing a routing context in the route editor

Developing an Apache Camel application typically consists of the following tasks:

Adding one or more routes to the routing context.

Adding a starting point pattern to a route.

Adding one or more endpoint patterns to a route.

Adding one or more processor patterns that represent how messages will be transformed and routed between the starting point and endpoints.

Connecting the patterns (referred to as nodes once they are placed on the canvas).

Configuring the details for each of the endpoints and processors that make up the route.

Adding any configuration beans or shared global components/data formats to the context.

Adding routes to the routing context

Overview

The camelContext element within an XML context file creates a routing context. The camelContext element can contain one or more routes, and each route, displayed on the canvas as a Route container node, maps to a route element in the generated camelContext element.

When you create a new Fuse Integration Project, the tooling creates an example camelContext.xml (Spring) or blueprint.xml (Blueprint) routing context file. You can view and edit the contents of the routing context file in the route editor's Source view. In Design view, the route editor displays a Route container node, which represents the empty route element. You can drag patterns from the Palette and drop them into the Route container node on the canvas to create a route. The Camel tooling updates the empty route element with XML code generated from the patterns you dropped into the Route container node on the canvas.

The tooling provides two methods for adding a new route:

In Design view, by dragging a Route pattern from the Palette's Routing drawer and dropping it onto the canvas

In Source view, by adding a <route/> element to the existing list within the camelContext element

Procedure

To add another route to the camelContext: element

Select one of the methods for adding a route.

In Design view, the Properties editor displays the list of the new route's properties for you to edit.

In the Properties editor, enter :

An ID (for example, Route2) for the new route in the route's Id field

Note

The tooling automatically assigns an ID to EIP and component patterns dropped on the canvas. You can replace these autogenerated IDs with your own to distinguish the routes in your project.

A description of the route in the Description field

A value for any other property as needed

On the menu bar, select File → Save to save the changes you made to the routing context file.

Note

To switch between multiple routes, select the route you want to display on the canvas by clicking its entry under the project's Camel Contexts folder in Project Explorer.

When you click the context file entry in Project Explorer, the canvas displays all routes in the context, as space allows.

Related topics

chapter "To Add a Content-Based Router" in "Tooling Tutorials"

chapter "To Add Another Route to the CBR Routing Context" in "Tooling Tutorials"

Adding patterns to a route

Routes consist of a sequence of connected patterns, referred to as nodes once they are placed on the canvas inside a Route container node. To add a pattern to a route you drag it from the Palette and drop it into a Route container on the canvas.

When patterns are dropped into a Route container on the canvas, they take on a color that indicates the type of node they are:

Blue—Route containers, which correspond to route elements in the context file, and other container nodes, such as when and otherwise EIPs that contain other EIPs that complete their logic

Green—Consumer endpoints that input data entering routes

Orange—EIPs that route, transform, process, or control the flow of data transiting routes

Purple—Producer endpoints that output the data exiting routes

Procedure

To drag a pattern onto a route:

In the Palette, locate the pattern you want to add to the route.

Drag the pattern over the target Route container and drop it.

Alternatively, you can drop a pattern on an existing node that has no outgoing connection, or on a connection existing between two nodes, to have the tooling automatically wire the connections between all nodes involved.

The tooling checks whether the resulting connection is valid and then either allows or prevents you from dropping the pattern on the drop target. For valid connections, the tooling:

existing node—adds the new node to the target node's outgoing side (beneath or to the right of it depending on how the editor preferences are set) and automatically wires the connection between them

existing connection—inserts the new node between the two connected nodes and automatically rewires the connections between the three nodes

The new pattern appears on the canvas in the Route container and becomes the selected node. The Properties editor displays a list of the new node's properties for you to edit.

Note

Once you drop a pattern inside a Route container, you cannot drag the node to rearrange the layout. When you connect one node to another, the tooling updates the layout according to the route editor's layout preference. The default is Down.

To access the route editor 's layout preference:

On Linux and Windows machines, Windows → Preferences → Fuse Tooling → Editor → Choose the layout direction for the diagram editor

On OS X, JBoss Developer Studio → Preferences → Fuse Tooling → Editor → Choose the layout direction for the diagram editor

Related topics

the section called “Configuring a pattern”

the section called “Removing patterns from a route”

Connecting patterns to make a route

Overview

A complete route typically consists of a starting endpoint, a string of processing nodes, and one or more destination endpoints. The tooling saves routes in the context file regardless of whether they are complete.

Important

The tooling appends every new node added to Design view to its route element in the context file, and any that are not connected manually, using the connector arrows, are auto-connected when the context file is reopened, or when a route is reloaded in the route editor, by switching from Source to Design view.

Note

Not all nodes can be connected. When you try to connect a source node to an illegal target node, the tooling displays the Overview symbol attached to the mouse cursor, and the connector fails to stick to the target node.

Manually connecting nodes

Connecting two nodes in a Route container on the canvas is as simple as dragging a line from one to the other. Each node in a route has a connector arrow. Selecting a node and dragging its connector arrow to a target node establishes a connection between the two nodes.

To connect two nodes:

In the Route container on the canvas, select the source node to display its connector arrow.

Drag the source node's connector arrow ( Manually connecting nodes ) to the target node.

The direction of the connection represents the direction messages flow between the nodes in the route.

While hovering over the target node, release the mouse button to drop the connector on it.

The route editor updates the <route> element in the routing context file with the xml generated from the connection. You can view the xml in Source view.

When you are done, save your work by selecting File → Save from the menu bar.

Configuring a pattern

Overview

Most patterns require some explicit configuration. For example, an endpoint requires an explicitly entered URI.

The tooling's Properties editor provides a form that lists all of the configuration details a particular pattern supports. The Properties editor also provides the following convenience features:

validating that all required properties have values

validating that supplied values are the correct data type for the property

drop-down lists for properties that have a fixed set of values

drop-down lists that are populated with the available bean references from the Apache Camel Spring configuration

Procedure

To configure a pattern:

On the canvas, select the node you want to configure.

The Properties editor lists all of the selected node's properties for you to edit. For EIPs, the Details tab lists all of a pattern's properties. For components from the Components drawer, the Details tab lists the general properties and those that require a value, and the Advanced tab lists additional properties grouped according to function.

The Documentation tab describes the pattern and each of its properties.

Edit the fields in the Properties editor to configure the node.

When done, save your work by selecting File → Save from the menu bar.

Related topics

Removing patterns from a route

Overview

As you develop and update a route, you may need to remove one or more of the route's nodes. The node's Overview icon makes this easy to do. When you delete a node from the canvas, all of its connections with other nodes in the route are also deleted, and the node is removed from the corresponding route element in the context file.

Note

You can also remove a node by opening its context menu and selecting Remove.

Procedure

To remove a node from a route:

Select the node you want to delete.

Click its Procedure icon.

Click Yes when asked if you are sure you want to delete this element.

The node and all of its connections are deleted from the canvas, and the node is removed from its corresponding route element in the context file.

Related topics

the section called “Adding patterns to a route”

Disconnecting two patterns

Overview

As you develop and update a route, you may need to disconnect some nodes to insert additional patterns. The Remove option on the connector context menu makes this easy to do.

Important

If you leave a disconnected node unconnected, the tooling will reconnect it to a node when the route is reloaded in the route editor or when the context file is reopened, even if you saved the change before switching views or closing the routing context file.

Procedure

To disconnect two nodes:

Select the connector you want to delete.

Right-click it to open the context menu.

Select Remove.

The connector between the nodes is removed.

Related topics

the section called “Connecting patterns to make a route”

Deleting a route

Overview

In some cases you made need to delete an entire route from your routing context. The Route container's Overview icon makes this easy to do. When you delete a route, all of the nodes inside the Route container are also deleted, and the corresponding route element in the context file is removed.

Note

You can also remove a route using the Route container's context menu and selecting Remove.

Important

You cannot undo this operation.

Procedure

To delete a route:

If the routing context contains more than one route, first select the route you want to delete in Project Explorer view.

On the canvas, click the Route container's Procedure icon.

Click Yes when asked if you are sure you want to delete this element.

The route is removed from the canvas, from the context file, and from Project Explorer.

Adding beans and configuration

Overview

Many routing patterns rely on references to Java objects (beans) for configuration or for implementation details. You add the beans into the routing context file using the route editor's Source view.

Procedure

To add beans to your routing context file:

Open your routing context file in the route editor.

Click the Source tab at the bottom of the route editor's canvas to switch to Source view, so you can edit the XML that defines the route.

Enter the bean elements needed by your route before the camelContext element.

Note

Use the id attribute to identify the bean, not the name attribute.

For example:

<!-- Configure the Inbound SAP Connections -->
 <bean id="sap-configuration" class="org.fusesource.camel.component.sap.SapConnectionConfiguration" activation="eager">
     <property name="destinationDataStore">
         <map>
             <entry key="quickstartDest" value-ref="quickstartDestinationData" />
         </map>
     </property>
     <property name="serverDataStore">
         <map>
             <entry key="quickstartServer" value-ref="quickstartServerData" />
         </map
     </property>
 </bean>

...

 <camelContext trace="false" id="sap-srfc-destination-fuse-context" xmlns="http://camel.apache.org/schema/blueprint">
	 <route id="sap-srfc-destination-fuse-route">
	     <from uri="file:work/camel-sap/input"/>
	     <convertBodyTo type="java.lang.String"/>
	     <log message="${body}" loggingLevel="INFO"/>
	     <to uri="sap-srfc-destination:quickstartDest:BAPI_FLCUST_GETLIST"/>
	     <log message="${body}" loggingLevel="INFO"/>
      </route>
 </camelContext>

Save your changes by selecting File → Save on the menu bar.

Click the Design tab at the bottom of the route editor's canvas to return to Design view and the route diagram.

Related topics

Chapter 6, The Source View

the section called “Adding global endpoints and data formats”

Apache Camel Development Guide, Part IV Programming EIP Components

Adding global endpoints and data formats

Overview

Some routes may rely on shared configuration provided by global endpoints or data formats. You can add global endpoints and data formats to the project's routing context file using the route editor's Configurations view.

Accessing the global configurations options

To add global endpoints or data formats to your routing context file:

Open your routing context file in the route editor.

Click the Configurations tab at the bottom of the route editor's canvas to switch to Configurations view.

Click Add to open the Create a new global element dialog.

The options are:

Endpoint—For details on adding a global endpoint, see the section called “Adding an endpoint”

Data Format—For details on adding a global data format, see the section called “Adding a data format”

Adding an endpoint

In the Create a new global element dialog, select Endpoint.

Click OK to open the Select component dialog.

Note

By default, the Select component dialog opens with the Show only palette components option enabled. To see all available components, disable this option.

Note

The Grouped by categories option groups components by type.

In the Select component dialog, scroll through the list of Camel components to find and select the component you want to add to the context file, and then enter an ID for it in the Id field.

In this example, we selected the JMS component and entered myJMS in Id.

Click Finish.

If necessary, open the Properties editor to edit the component's properties as appropriate for your project.

The tooling autofills Id with the value you entered in the component's Id field in Step 3. It builds the uri (required field) starting with the component's schema (in this case, jms:), but you must specify the destinationName and the destinationType to complete the component's uri.

To complete the component's uri, click Advanced → Path.

In Destination Name, enter the name of the destination endpoint (for example, FOO.BAR). In Destination Type, enter the endpoint destination's type (for example, queue, topic), temp:queue, or temp:topic).

Note

For the JMS component, the destination type defaults to queue. This default value does not appear in the uri field on the Details page until you have entered a value in Destination Name (required field) .

The Properties editor's Details and Advanced pages provide access to all properties available for configuring a particular component.

For example, click the Consumer (advanced) tab.

Enable the properties Eager Loading Of Properties and Expose Listener Session.

Switch to Source view to see the code that the tooling added to the context file (in this example, a configured JMS endpoint), before the first route element.

When done, save your changes by selecting File → Save on the menu bar.

Adding a data format

In the Create a new global element dialog, select Data Format.

Click OK to open the Create a global Data Format dialog.

The data format defaults to avro, the format at the top of the list of those available.

Open the Data Format drop-down menu, and select the format you want from the list (for example, xmljson).

In Id, enter a name for the format (for example, myDataFormat).

Click Finish.

If necessary, open the Properties editor to display the data format's properties for editing.

In the Properties editor, set property values as appropriate for your project; for example:

Switch to Source view to see the code that the tooling added to the context file (in this example, a configured xmljson data format), before the first route element.

When done, save your changes by selecting File → Save on the menu bar.

Deleting a global endpoint or data format

The procedure is the same whether removing an endpoint or data format previously added to the routing context.

In Configurations view, select the global component—endpoint or data format—you want to delete.

For example, deleting the data format myDataFormat previously added in the section called “Adding a data format”:

Click Delete.

The global component myDataFormat disappears from Configurations view.

Switch to Source view to check that the tooling removed the XML code from the routing context.

When done, save your changes by selecting File → Save on the menu bar.

Editing a global endpoint or data format

The procedure is the same whether modifying the properties of an endpoint or data format previously added to the routing context.

In Configurations view, select the global component—endpoint or data format—you want to edit.

For example, editing the endpoint myJMS previously added in the section called “Adding an endpoint”:

Click Edit.

In the Properties editor, modify the component's properties according to your project's needs.

For example, open the Advanced → Consumer tab, and change the value of Concurrent Consumers to 2:

Switch to Source view and check that the tooling added the property concurrentConsumers=2 to the routing context:

When done, save your changes by selecting File → Save on the menu bar.

Related topics

the section called “Adding beans and configuration”

Configuring the route editor

Overview

Using JBoss Developer Studio's preference panel, you can specify aspects of the route editor's behavior when configuring Enterprise Integration Patterns:

The default language to use for expressions in EIPs

The method for labeling nodes on the canvas

The direction in which patterns flow on the canvas when creating routes

Whether the canvas displays a grid overlay

Procedure

To configure the route editor:

Click Windows → Preferences → Fuse Tooling → Editor on Linux and Windows machines, but JBoss Developer Studio → Preferences → Fuse Tooling → Editor on OS X, to open the Editor preferences dialog.

Select, from the drop-down list, the default language you want to use for expressions in EIP nodes. The default is Simple.

Click the checkbox next to If enabled the ID values will be use for labels if existing to enable or disable using node IDs as labels. The default is enabled.

Select, from the drop-down list, the direction in which you want the route editor to align the patterns in a route. The default is Down.

Click the checkbox next to Show diagram grid in Routes Editor to enable or disable displaying the grid overlay on the canvas. The default is enabled.

Click Apply to apply the changes to the Editor preferences.

When done, click OK to close the Preferences dialog.

You can restore the route editor's original defaults at any time by returning to the Editor preferences dialog and clicking Restore Defaults.

Related topics

Editor

Chapter 6. The Source View

The tooling's Source tab opens the route editor in Source view (Figure 6.1) to display the contents of a routing context .xml file.

Figure 6.1. Source view

The Source view is useful for editing and adding any configuration, comments, or beans to the routing context file. The Content Assist functionality helps you when working with configuration files. In the Source view, press Ctrl+Space to see a list of possible values that can be inserted into your project.

Chapter 7. Creating a new Apache Camel JUnit test case

Overview

A common way of testing routes is to use JUnit. The design time tooling includes a wizard that simplifies creating a JUnit test case for your routes. The wizard uses the endpoints you specify to generate the starting point code and configuration for the test.

Note

After you create the boilerplate JUnit test case, you need to modify it to add expectations and assertions specific to the route that you've created or modified, so the test is valid for the route.

Prerequisites

Before you create a new JUnit test case, you need to perform a preliminary task:

If you are replacing an existing JUnit test case, you need to delete it before you create a new one. See the section called “Deleting and existing JUnit test case”.

If you are creating a new JUnit test case in a project that hasn't one, you need to first create the project_root/src/test/java folder for the test case that is included in the build path. See the section called “Creating and adding the src/test/java folder to the build path”.

Deleting and existing JUnit test case

In Project Explorer, expand the project's root node to expose the <root_project>/src/test/java folder.

Locate the JUnit test case file in the /src/test/java folder.

Depending on which DSL the project is based on, the JUnit test case file is named BlueprintXmlTest.java or CamelContextXmlTest.java.

Right-click the JUnit test case .java file to open the context menu, and then select Delete.

The JUnit test case .java file disappears from Project Explorer.

You can now create a new JUnit test case.

Creating and adding the src/test/java folder to the build path

In Project Explorer, right-click the project's root to open the context menu.

Select New → Folder to open the Create a new folder resource wizard.

In the wizard's project tree pane, expand the project's root node and select the src folder.

Make sure <project_root>/src appears in the Enter or select the parent folder field.

In Folder name, enter /test/java. This folder will store the new JUnit test case you create.

Click Finish.

In Project Explorer, the new src/test/java folder appears under the src/main/resources folder. You can verify that this folder is on the class path by opening its context menu and selecting Build Path. If Remove from Build Path is a menu option, you know the src/test/java folder is on the class path.

You can now create a new JUnit test case.

Creating a JUnit test case

To create a new JUnit test case for your route:

In Project Explorer, select the routing context .xml file in your project.

Right-click it to open the context menu, and then select New → Camel Test Case to open the New Camel JUnit Test Case wizard, as shown in Figure 7.1, “New Camel JUnit Test Case wizard”.

Figure 7.1. New Camel JUnit Test Case wizard

Alternatively, you can open the wizard by selecting File → New → Other... → JBoss Fuse → Camel Test Case from the menu bar.

In Source folder, accept the default location of the source code for the test case, or enter another location.

You can click Browse button to search for a location.

In Package, accept the default package name for the generated test code, or enter another package name.

You can click Browse button to search for a package.

In Camel XML file under test, accept the default pathname of the routing context file that contains the route you want to test, or enter another pathname.

You can click Browse button to search for a context file.

In Name, accept the default name for the generated test class, or enter another name.

Select the method stubs you want to include in the generated code.

If you want to include the default generated comments in the generated code, check the Generate comments box.

Click Next button to open the Test Endpoints page. For example, Figure 7.2, “New Camel JUnit Test Case page” shows a route's input and output file endpoints selected.

Figure 7.2. New Camel JUnit Test Case page

Under Available endpoints, select the endpoints you want to test. Click the checkbox next to any selected endpoint to deselect it.

Click Finish button .

Note

If prompted, add JUnit to the build path.

The artifacts for the test are added to your project and appear in Project Explorer under src/test/java. The class implementing the test case opens in the Java editor.

Related topics

chapter "To Test a Route with JUnit" in "Tooling Tutorials"

Chapter 8. Running routes inside Red Hat JBoss Fuse Tooling

There are two ways to run your routes using the tooling:

As a local camel context (with or without tests)

Using Maven

Running routes as a local Camel context

Overview

The simplest way to run an Apache Camel route is as a Local Camel Context. This method enables you to launch the route directly from Project Explorer's context menu. When you run a route from the context menu, the tooling automatically creates a runtime profile for you. You can also create a custom runtime profile for running your route.

Your route runs as if it were invoked directly from the command line and uses Apache Camel's embedded Spring container. You can configure a number of the runtime parameters by editing the runtime profile.

Procedure

To run a route as a local Camel context:

In Project Explorer, select a routing context file.

Right-click it to open the context menu, and then select Run As → Local Camel Context.

Note

Selecting Local Camel Context (without tests) directs the tooling to run the project without performing validation tests, which may be faster.

Result

The Console view displays the output generated from running the route.

Related topics

the section called “Editing a Local Camel Context runtime profile”

chapter "To Run a Route" in "Tooling Tutorials"

Running routes using Maven

Overview

If the project containing your route is a Maven project, you can use the m2e plug-in to run your route. Using this option, you can execute any Maven goals, before the route runs.

Procedure

To run a route using Maven:

In Project Explorer, select the root of the project .

Right-click it to open the context menu, and then select Run As → Maven build.

The first time you run the project using Maven, the Edit Configuration and launch editor opens, so you can create a Maven runtime profile.

To create the runtime profile, on the Maven tab:

Make sure the route directory of your Apache Camel project appears in the Base directory: field.

For example on Linux the root of your project will be similar to ~/workspace/simple-router.

In the Goals: field, enter camel:run.

Important

If you created your project using the Java DSL, enter exec:java in the Goals: field.

Click Apply and then Run.

Subsequent Maven runs use this profile, unless you modify it between runs.

Results

The Console view displays the output from the Maven run.

Related topics

the section called “Editing a Maven runtime profile”

Working with runtime profiles

Red Hat JBoss Fuse Tooling stores information about the runtime environments for each project in runtime profiles. The runtime profiles keep track of such information as which Maven goals to call, the Java runtime environment to use, any system variables that need to be set, and so on. A project can have more than one runtime profile.

Editing a Local Camel Context runtime profile

Overview

A Local Camel Context runtime profile configures how Apache Camel is invoked to execute a route. A Local Camel Context runtime profile stores the name of the context file in which your routes are defined, the name of the main to invoke, the command line options passed into the JVM, the JRE to use, the classpath to use, any environment variables that need to be set, and a few other pieces of information.

The runtime configuration editor for a Local Camel Context runtime profile contains the following tabs:

Camel Context File—specifies the name of the new configuration and the full path of the routing context file that contains your routes.

JMX—specifies JMX connection details, including the JMX uri and the user name and password (optional) to use to access it.

Main—specifies the fully qualified name of the project's base directory, a few options for locating the base directory, any goals required to execute before running the route, and the version of the Maven runtime to use.

JRE—specifies the JRE and command line arguments to use when starting the JVM.

Refresh—specifies how Maven refreshes the project's resource files after a run terminates.

Environment—specifies any environment variables that need to be set.

Common—specifies how the profile is stored and the output displayed.

The first time an Apache Camel route is run as a Local Camel Context, Red Hat JBoss Fuse Tooling creates for the routing context file a default runtime profile, which should not require editing.

Accessing the Local Camel Context's runtime configuration editor

In Project Explorer, select the camelContext file for which you want to edit or create a custom runtime profile.

Right-click it to open the context menu, and then select Run As... → Run Configurations to open the Run Configurations dialog.

In the context selection pane, select Local Camel Context, and then click New profile icon at the top, left of the context selection pane.

In the Name field, enter a new name for your runtime profile.

Figure 8.1. Runtime configuration editor for Local Camel Context

Setting the camel context file

The Camel Context File tab has one field, Select Camel Context file.... Enter the full path to the routing context file that contains your route definitions.

The Browse... button accesses the Open Resource dialog, which facilitates locating the target routing context file. This dialog is preconfigured to search for files that contain Apache Camel routes.

Changing the command line options

By default the only command line option passed to the JVM is:

-fa context-file

If you are using a custom main class you may need to pass in different options. To do so, on the Main tab, click the Add button to enter a parameter's name and value. You can click the Add Parameter dialog's Variables... button to display a list of variables that you can select.

To add or modify JVM-specific arguments, edit the VM arguments field on the JRE tab.

Changing where output is sent

By default, the output generated from running the route is sent to the Console view. But you can redirect it to a file instead.

To redirect output to a file:

Select the Common tab.

In the Standard Input and Output pane, click the checkbox next to the Output File: field, and then enter the path to the file where you want to send the output.

The Workspace..., File System..., and Variables... buttons facilitate building the path to the output file.

Related topics

the section called “Running routes as a local Camel context”

Editing a Maven runtime profile

Overview

A Maven runtime profile configures how Maven invokes Apache Camel. A Maven runtime profile stores the Maven goals to execute, any Maven profiles to use, the version of Maven to use, the JRE to use, the classpath to use, any environment variables that need to be set, and a few other pieces of information.

Important

The first time an Apache Camel route is run using Maven, you must create a default runtime profile for it.

The runtime configuration editor for a Fuse runtime profile contains the following tabs:

Main—specifies the name of the new configuration, the fully qualified name of the project's base directory, a few options for locating the base directory, any goals required to execute before running the route, and the version of the Maven runtime to use.

JRE—specifies the JRE and command line arguments to use when starting the JVM.

Refresh—specifies how Maven refreshes the project's resource files after a run terminates.

Source—specifies the location of any additional sources that the project requires.

Environment—specifies any environment variables that need to be set.

Common—specifies how the profile is stored and the output displayed.

Accessing the Maven runtime configuration editor

In Project Explorer, select the root of the project for which you want to edit or create a custom runtime profile.

Right-click it to open the context menu, and then select Run As... → Run Configurations to open the Run Configurations dialog.

In the context selection pane, select Maven Build, and then click New profile icon at the top, left of the context selection pane.

Figure 8.2. Runtime configuration editor for Maven

Changing the Maven goal

The most commonly used goal when running a route is camel:run. It loads the routes into a Spring container running in its own JVM.

The Apache Camel plug-in also supports a camel:embedded goal that loads the Spring container into the same JVM used by Maven. The advantage of this is that the routes should bootstrap faster.

Projects based on Java DSL use the exec:java goal.

If your POM contains other goals, you can change the Maven goal used by clicking the Configure... button next to the Maven Runtime field on the Main tab. On the Installations dialog, you edit the Global settings for <selected_runtime> installation field.

Changing the version of Maven

By default, Red Hat JBoss Fuse Tooling for Eclipse uses m2e, which is embedded in Eclipse. If you want to use a different version of Maven or have a newer version installed on your development machine, you can select it from the Maven Runtime drop-down menu on the Main tab.

Changing where the output is sent

By default, the output from the route execution is sent to the Console view. But you can redirect it to a file instead.

To redirect output to a file:

Select the Common tab.

Click the checkbox next to the Output File: field, and then enter the path to the file where you want to send the output.

The Workspace..., File System..., and Variables... buttons facilitate building the path to the output file.

Related topics

the section called “Running routes using Maven”

Chapter 9. Using the JBoss Fuse SAP Tool Suite

Abstract

The JBoss Fuse SAP Tool Suite makes it possible to integrate your Camel routes with a remote SAP Application Server. A variety of SAP components are provided to support Remote Function Calls (RFC) and the sending and receiving of Intermediate Documents (IDocs). Note that the SAP Tool Suite depends on the JCo and IDoc client libraries from SAP. You must have an SAP Service Marketplace Account, in order to install and use these libraries.

Installing the JBoss Fuse SAP Tool Suite

Overview

The JBoss Fuse SAP Tool Suite provides the Edit SAP Connection Configuration dialog, which helps you to create and manage the SAP Application Server and Destination connections. The suite is not installed by default, because it requires third-party JCo and IDoc client libraries, which are licensed separately by SAP.

Platform restrictions for SAP tooling

Because the SAP tool suite depends on the third-party JCo 3.0 and IDoc 3.0 libraries, it can only be installed on the platforms that these libraries support. For more details about the platform restrictions for SAP tooling, see Red Hat JBoss Fuse Supported Configurations.

Prerequisites

Before you can install the JBoss Fuse SAP Tool Suite, you must download the requisites JCo and IDoc libraries from the following location:

http://service.sap.com/connectors

Please note the following points:

You will require an SAP Service Marketplace Account to download the JCo and IDoc client archives.

Choose the appropriate JCo and IDoc libraries for your operating system.

Only version 3.0.11 or greater of the JCo library is supported.

Only version 3.0.10 or greater of the IDoc library is supported.

For this installation procedure, you can leave the downloaded files in archive format. There is no need to extract the contents.

Procedure

To install the JBoss Fuse SAP Tool Suite into JBoss Developer Studio, perform the following steps:

In JBoss Developer Studio, select File → Import to open the Import wizard.

In the Select screen of the Import wizard, select JBoss Fuse → Install JBoss Fuse SAP Tool Suite, and click Next.

The Install the JBoss Fuse SAP Tool Suite screen opens, which displays the instructions for downloading the JCo and IDoc libraries from the SAP Service Marketplace. Click Next.

The Select JCo3 and IDoc3 Archive to Import screen opens. Next to the JCo Archive File field, use the Browse button to select the JCo archive that you downloaded from the SAP Service Marketplace. After selecting the JCo archive, the Archive Version and Archive OS Platform fields are automatically filled in, so that you can check whether the library you are installing has the correct version and OS platform.

Next to the IDoc3 Archive File field, use the Browse button to select the IDoc archive that you downloaded from the SAP Service Marketplace.

After selecting both archive files, click Finish.

A new Install wizard (for installing Eclipse plug-ins) opens automatically. This wizard displays the following to plug-ins to be installed:

JBoss Fuse SAP Tool Suite

SAP JCo3 and IDoc3 Libraries

Make sure that both of these plug-ins are selected. Click Next.

Note

The SAP JCo3 and IDoc3 Libraries plug-in is dynamically constructed from the selected JCo and IDoc libraries.

The Install Details screen allows you to review the plug-ins to be installed. Click Next.

The Review Licenses dialog opens. Select the I accept radiobutton option, and then click Finish.

If you encounter a Security Warning dialog (warning of unsigned content), click OK to ignore the warning and continue installing.

The Restart Eclipse dialog opens. Click OK to restart Eclipse.

Create and Test SAP Destination Connection

Overview

In JBoss Fuse SAP Tool suite, the Edit SAP Connection Configuration dialog helps you to create and manage the SAP Application Destination connections. This section describes how to create and test the SAP destination connection.

Procedure

To create and test an SAP destination connection, perform the following steps:

Navigate to the global Configuration tab of Camel Editor and click Add.

The Create new global element view appears.

Under SAP, select the type of connection you would like to create. Choose the SAP Connection and click Ok.

The Edit SAP Connection Configuration dialog appears. It allows you to create, edit and delete the Destination and Server Connection Configurations.

To create a new Destination Data Store, click the Add Destination tab.

The Create Destination dialog appears.

Enter a name for the destination in the Destination Name field and click Ok.

In the Properties dialog,

Click on the Basic tab to configure the basic properties required to connect to an SAP destination. In this tab, fill in the following property fields to configure the connection:

SAP Application Server

SAP System Number

SAP Client

Logon User

Logon Password

Logon Language

Click on the Connection tab to add values required to connect to an SAP destination. Fill in the following property fields to configure the connection:

SAP System Number

SAP Router String

SAP Application Server

SAP Message Server

SAP Message Server Port

Gateway Host

Gateway Port

SAP System ID

SAP Application Server Group

Click on the Authenticate tab to add values required to validate an SAP destination. Fill in the following property fields to configure the connection.

SAP Authentication type

SAP Client

Logon User

Logon User Alias

Logon Password

SAP SSO Logon Ticket

SAP X509 Login Ticket

Logon Language

Click on the Special tab. In this tab, fill in the following property fields to configure the connection:

Select CPIC Trace

Initial Codepage

Click on the Pool tab and fill in the following property fields to configure the connection:

Connection Pool Peak Limit

Connection Pool Capacity

Connection Pool Expiration Time

Connection Pool Expire Check Period

Connection Pool Max Get Client Time

Click on the SNC tab and fill in the following property fields to configure the connection:

SNC Partner Name

SNC Level of Security

SNC Name

SNC Library Path

Click on the Repository tab and fill in the following property fields to configure the connection:

Repository Destination

Repository Logon User

Repository Logon Password

Note

If you need more information about these settings, refer the SAP documentation.

You are now ready to test the destination connection. In the Edit SAP Connection Configuration dialog, right-click on the destination name and select Test.

The Test Destination Connection dialog opens.

The dialog uses the current destination configuration settings to connect to the SAP Destination Data Store. If the test is successful, you will see the following message in the status area:

Connection test for destination 'YourDestination' succeeded.

Otherwise, an error report appears in the status area.

Click Close to close the Test Destination Connection dialog.

Click Finish. The newly created SAP Destination Connection appears under SAP.

Create and Test SAP Server Connection

Overview

In JBoss Fuse SAP Tool suite, the Edit SAP Connection Configuration dialog helps you to create and manage the SAP Application Server connections. This section describes how to create and test the SAP Server connection.

Procedure

To create and test the SAP Server connection, perform the following steps:

Navigate to the global Configuration tab of Camel Editor and click Add.

The Create new global element view appears.

Under SAP, select the type of connection you would like to create. Choose the SAP Connection and click Ok.

The Edit SAP Connection Configuration dialog appears. It allows you to create, edit and delete the Destination and Server Connection Configurations.

To create a new Server Data Store, click the Add Server tab.

The Create Server dialog appears.

Enter a name for the Server in the Server Name field and click Ok.

In the Properties dialog,

Click on the Mandatory tab to configure the basic properties required to connect to an SAP server. In this tab, fill in the following property fields to configure the connection:

Gateway Host

Gateway Port

Program ID

Repository Destination

Connection Count

Click on the Optional tab and fill in the following property fields to configure the connection:

SAP Router String

Worker Thread Count

Minimum Worker Thread Count

Maximum Startup Delay

Repository Map

Click on the SNC tab and fill in the following property fields to configure the connection.

SNC Level of Security

SNC Name

SNC Library Path

Note

For more information about the settings, refer the SAP documentation.

You are now ready to test the server connection. In the Edit SAP Connection Configuration dialog, right-click on the server name and select Test.

The Test Server Connection dialog opens.

The dialog uses the current server configuration settings to connect to the SAP Server Data Store. If the test is successful, you will see the following message in the status area:

Server state: STARTED
Server state: ALIVE

If the test fails, the server status is reported as DEAD.

Click Stop to shut down the Test Sever.

Click Close to close the Test Server Connection dialog.

Click Finish. The newly created SAP Server Connection appears under SAP.

Deleting Destination and Server Connections

Overview

This following section describes how to delete the SAP Destination and Server connections in the Edit SAP Connection Configuration dialog.

Procedure

If you want to delete the Destination and Server connections, perform the following steps:

Navigate to the global Configuration tab of Camel Editor and click Add.

The Create new global element view appears.

Under SAP, select the SAP Connection and click Ok.

The Edit SAP Connection Configuration dialog appears. It allows you to create, edit and delete the Destination and Server Connection Configurations.

In the Edit SAP Connection Configuration dialog, select the Destination and Server Data Stores which you want to delete.

Click Delete. It will delete the selected connections.

Atlast, click Finish. It will save all the changes.

Create a New SAP Endpoint

Overview

You can use the Components palette in the Camel editor to add SAP components to a route with the help of the Edit SAP Connection Configuration dialog.

Note

If you are using the SAP Connection view, remember to paste the requisite SAP connection configuration data into your Blueprint XML or Spring XML code.

Prerequisites

You must already have created some SAP destination connections and/or server connections with the help of the Edit SAP Connection Configuration dialog.

Note

If you are using the SAP Connection view, export this configuration to a file of the appropriate type (Blueprint XML or Spring XML).

Procedure

To create a new SAP endpoint, perform the following steps:

It is assumed that you already have a Fuse project and a Camel XML file to work with (which could either be in Blueprint XML or Spring XML format).

Open your Camel XML file in the Camel editor. If you have already installed the JBoss Fuse SAP Tool Suite, you should be able to see the SAP components under the Components palette in the Camel editor. The following SAP components are provided by the tool suite:

SAP IDoc Destination

SAP IDoc List Destination

SAP IDoc List Server

SAP qRFC Destination

SAP Queued IDoc Destination

SAP Queued IDoc List Destination

SAP sRFC Destination

SAP sRFC Server

SAP tRFC Destination

SAP tRFC Server

In the Design view of the Camel editor, drag one of these components onto the canvas to create a new SAP endpoint in the current camelContext.

Note

The SAP Netweaver component does not belong to the JBoss Fuse SAP Tool Suite. It is hosted in the Apache Camel project.

Switch to the Source view of the Camel editor, by clicking on the Source tab at the bottom of the canvas. In this view, you can see the XML source of the routes.

When specifying an SAP endpoint URI, you must embed either a destination name or a server connection name in the URI format. For example, the sap-srfc-destination component has the following URI format:

sap-srfc-destination:destinationName:rfcName

To reference a particular destination, use the value of the relevant entry element's key attribute as the destinationName in this URI.

Chapter 10. Getting Started with Data Transformation

Fuse Transformation Tooling

One of the challenges that comes with system and data integration is that the component systems often work with different data formats. You cannot simply send messages from one system to another without translating it into a format (or language) recognized by the receiving system. Data transformation is the term given to this translation.

Data Transformation Tutorial

In this tutorial you will learn how to use the data transformation tooling to include data transformation in a predefined Camel route. The Camel route directs messages from a source endpoint that produces XML data to a target endpoint that consumes JSON data. You will add and define a data transformation component that maps the source's XML data format to the target's JSON data format.

Prerequisites

JBoss Fuse tooling installed on JBoss Developer Studio. See Install Red Hat JBoss Developer Studio Integration Stack

Maven installed and configured correctly. See Red Hat JBoss Fuse Maven Repositories

the transformation quickstart applications downloaded and installed

Importing the starter quickstart application

Right-click in Project Explorer to open the context menu.

Select Import → Import....

Expand the Maven folder, and select Existing Maven Projects.

Click Next to open the Maven Projects wizard.

Click Browse to find and select the root directory of the starter quickstart application.

If the browse operation finds multiple projects, make sure you select the starter quickstart application. The full path to the starter quickstart application appears in the Projects pane.

Click Finish.

After the import operation finishes, the starter project appears in Project Explorer.

In Project Explorer, expand the starter project.

Double-click starter/src/main/resources/META-INF/spring/camel-context.xml to open the route in the route editor's Diagram view.

Click the Source tab to view the underlying XML.

You can see that an XML file is produced from a source endpoint and a JSON file is consumed by a target endpoint.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:camel="http://camel.apache.org/schema/spring"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd        http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

    <camelContext id="camelContext-272d04f8-e498-466d-b34b-3c24d01a4e10" xmlns="http://camel.apache.org/schema/spring"
        <route id="_route1">
            <from id="_from1" uri="file:src/data?fileName=abc-order.xml&noop=true"/>
            <to id="_to1" uri="file:target/messages?fileName=xyz-order.json"/>
        </route>
    </camelContext>
</beans>

Click the Design tab to return to Design view.

Remove the arrow connecting the source and target endpoints.

If Console view is not already open, open it now by clicking Window → Show View → Console.

Note

Although the following mini tutorials are written to be run in consecutive order, you can run through them in any order, but the Console output per tutorial will differ from that shown.

Adding a data transformation node to the Camel route

In the Palette, expand the Transformation drawer.

Drag a Data Transformation component onto the canvas.

The New Transformation wizard opens with the Project, Dozer File Path, and Camel File Path fields auto filled.

Fill in the remaining fields:

In Transformation ID, enter xml2json.

For Source Type, select XML from the drop-down menu.

For Target Type, select JSON from the drop-down menu.

Click Next.

The Source Type (XML) definition page opens, where you specify either an XML Schema (default) or an example XML Instance Document to provide the type definition of the source data:

Leave XML Schema enabled.

For Source file, browse to the location of the XML schema file or the XML instance file to use for the type definition of the source data, and select it (in this case, abc-order.xsd).

The XML Structure Preview pane displays a preview of the XML structure.

In Element root, enter ABCOrder.

The tooling uses this text to label the pane that displays the Source data items to map.

The Source Type (XML) definition page should now look like this:

Click Next.

The Target Type (JSON) definition page opens, where you specify the type definition for the target data.

Click JSON Instance Document.

In the Target File field, enter the path to the xyz-order.json instance document, or browse to it. The JSON Structure Preview pane displays a preview of the JSON data structure:

Click Finish.

The Transformation editor opens, so you can map data items in your XML source to data items in your JSON target.

The Transformation editor is composed of three panels:

Source—lists the available data items of the source

Mappings—displays the mappings between the source and target data items

Target—lists the available data items of the target

In addition, the editor's Details view, located just below the editor's three panels (once the first mapping has been made), graphically displays the hierarchical ancestors for both the mapped source and target data items currently selected. For example:

Using Details view, you can customize the mapping for the selected source and target data items:

Set property—Modify an existing mapping or map a simple data item to one in a collection (see the section called “Mapping a simple data item to a data item in a collection”)

Set variable—Specify a constant value for a data item (see the section called “Mapping a constant variable to a data item”)

Set expression—Map a data item to the dynamic evaluation of a specified expression (see the section called “Mapping an expression to a data item”)

Add transformation—Modify the value of a mapped data item using a built-in function (see the section called “Adding a built-in function to a mapped data item”)

Add custom transformation—Modify the value of a mapped data item using the Java method you create or one you previously created (see the section called “Adding a custom transformation to a mapped data item”)

Mapping source data items to target data items

Expand all items in the Source and Target panels located on left and right sides of the Mappings panel.

Drag a data item from the Source panel and drop it on its corresponding data item in the Target panel.

For example, drag the customerNum data item from the Source panel and drop it on the custId data item in the Target panel.

The mapping appears in the Mappings panel, and the details of both the Source and Target data items appear below in Details view.

Continue dragging and dropping source data items onto their corresponding target data items until you have completed all basic mappings.

In the starter example, the remaining data items to map are:

Source | Target
orderNum | orderId
status | priority
id | itemId
price | cost
quantity | amount

Note

You can map collections (data items containing lists or sets) to noncollection data items and vice versa, but you cannot map collections to other collections.

Click Hide mapped fields icon on both the Source and Target panels to quickly determine whether all data items have been mapped.

Only data items that have not been mapped are listed in the Source and Target panels.

In the starter example, the remaining unmapped Target attributes are approvalCode and origin.

Click the camel-context.xml tab to return to the route editor in Design view.

Hover your cursor over each endpoint to reveal its connecter arrow.

Selecting the file:src/data?fil... node, drag and drop its connector arrow onto the ref:xml2json node. Likewise drag and drop the connector arrow from the ref:xml2json node onto the file:target/messa... node.

Connecting the nodes on the canvas creates a valid Camel route, which you can now save.

Click File → Save.

You can run a JUnit test on your transformation file after you create the transformation test. For details, see the section called “Creating the transformation test file and running the JUnit test”. If you do so at this point, you will see this output in Console view:

<?xml version="1.0" encoding="UTF-8"?>
<ABCOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:java="http://java.sun.com">
    <header>
        <status>GOLD</status>
        <customer-num>ACME-123</customer-num>
        <order-num>ORDER1</order-num>
    </header>
    <order-items>
        <item id="PICKLE">
            <price>2.25</price>
            <quantity>1000</quantity>
        </item>
        <item id="BANANA">
            <price>1.25</price>
            <quantity>400</quantity>
        </item>
    </order-items>
</ABCOrder>

for the source XML data, and

{"custId":"ACME-123","priority":"GOLD","orderId":"ORDER1","lineItems":[{"itemId":"PICKLE",
"amount":1000,"cost":2.25},{"itemId":"BANANA","amount":400,"cost":1.25

for the target JSON data.

Creating the transformation test file and running the JUnit test

Right-click the starter project in Project Explorer, and select New → Other → Fuse Tooling → Fuse Transformation Test.

Select Next to open the New Transformation Test wizard.

In the New Transformation Test wizard, set the following values:

Field | Value
Package | example
Transformation ID | xml2json

Click Finish.

In Project Explorer, navigate to starter/src/test/java/example, and open the TransformationTest.java file.

Add the following code to the transform method:

startEndpoint.sendBodyAndHeader(readFile("src/data/abc-order.xml"), "approvalID", "AUTO_OK");

Click File → Save.

You can now run a JUnit test on your transformation file at any point in these tutorials.

In Project Explorer, expand the starter project to expose the /src/test/java/example/TransformationTest.java file.

Right click it to open the context menu, and select Run as JUnit Test.

The JUnit Test pane opens to display the status of the test. To avoid cluttering your workspace, drag and drop the pane in the bottom panel near Console view.

Open Console view to see the log output.

Mapping a constant variable to a data item

When a source/target data item has no corresponding target/source data item, you can map a constant variable to the existing data item.

In the starter example, the target data item origin does not have a corresponding source data item. To map the origin attribute to a constant variable:

In the Source panel, click the Variables tab to open Variables view.

In Variables view, click Add a new variable icon to open the Enter a new variable name dialog.

Enter a name for the variable you want to create.

For the starter example, enter ORIGIN.

Click OK.

The newly created variable ORIGIN appears in Variables view in the Name column and the default value "ORIGIN" in the Value column.

Click the default value to edit it, and change the value to Web.

Press Enter.

Drag and drop the new variable ORIGIN onto the origin data item in the Target panel.

The new mapping of the variable $(ORIGIN) appears in the Mappings panel and in Details view.

Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.

Console view displays the json-formatted output data:

{"custId":"ACME-123","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"itemId":"PICKLE","amount":1000,"cost":2.25},
{"itemId":"BANANA","amount":400,"cost":1.25}]}

Mapping an expression to a data item

This feature enables you, for example, to map a target data item to the dynamic evaluation of a Camel language expression.

Use the target approvalCode data item, which lacks a corresponding source data item:

Click Add a new mapping icon to add an empty transformation map to the Mappings panel.

From the Target panel, drag and drop the approvalCode data item to the target field of the newly created mapping in the Mappings panel.

The approvalCode data item also appears in Details view's target box.

In Details view, click drop-down menu access on the ABCOrder source box to open the drop-down menu.

Menu options depend on the selected data item's data type. The available options are bolded.

Select Set expression to open the Expression dialog.

In Language, select the expression language to use from the list of those available. Available options depend on the data item's data type.

For the starter example, select Header.

In the Details pane, select the source of the expression to use.

The options are Value and Script.

For the starter example, click Value, and then enter ApprovalID.

Click OK.

Both Mappings panel and Details view display the new mapping for the target data item approvalCode.

Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.

Console view displays the json-formatted output data:

{"custId":"ACME-123","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"itemId":"PICKLE","amount":1000,"cost":2.25},
{"itemId":"BANANA","amount":400,"cost":1.25}]}

Adding a custom transformation to a mapped data item

You may need to modify the formatting of source data items when they do not satisfy the requirements of the target system.

For example, to satisfy the target system's requirement that all customer ids be enclosed in brackets:

Mappings panel, select the customerNum mapping to populate Details view.

In Details view, click drop-down menu access on the ABCOrder source box to open the drop-down menu.

Select Add custom transformation to open the Add Custom Transformation page.

Click create new function button next to the Class field to open the Create a New Java Class wizard.

Modify the following fields:

Package—Enter example.

Name—Enter MyCustomMapper.

Method Name—Change map to brackets.

Leave all other fields as is.

Click Finish.

The Add Custom Transformation page opens with the Class and Method fields auto filled:

Click OK to open the MyCustomMapper.java file in the Java editor:

Edit the brackets method to change the last line return null; to this:

return "[" + input + "]";

Click the transformation.xml tab to switch back to the Transformation editor.

Details view shows that the brackets method has been associated with the customerNum data item.

The brackets method is executed on the source input before it is sent to the target system.

Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.

Console view displays the json-formatted output data:

{"custId":"[ACME-123]","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"itemId":"PICKLE","amount":1000,"cost":2.25},
{"itemId":"BANANA","amount":400,"cost":1.25}]}

Mapping a simple data item to a data item in a collection

In this tutorial, you will modify an existing mapping that maps all ids in the Source to the itemIds in the Target. The new mapping will map the customerNum data item in the Source to the itemId of the second item in the lineItems collection in the Target.

With this change, no ids in the Source will be mapped to itemIds in the Target.

In the Mappings panel, select the mapping id —> itemId to display the mapping in Details view.

On the Source box, click drop-down menu access to open the drop-down menu, and select Set property.

In the Select a property page, expand the header node and select customerNum. Click OK to save the changes.

The Details View now shows that XyzOrder now has a lineItems field. Click the toggle button next to lineItems to increase its value to 1.

Note

Indexes are zero-based, so a value of 1 selects the second instance of itemId in the collection.

Notice that Details view shows customerNum mapped to the itemId of the second item in the lineItems collection.

Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.

Console view displays the json-formatted output data:

{"custId":"[ACME-123]","priority":"GOLD","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"amount":1000,"cost":2.25},
{"itemId":"ACME-123","amount":400,"cost":1.25}]}

Adding a built-in function to a mapped data item

You can use the built-in string-related functions to apply transformations to mapped data items.

In the Transformations panel, select the status to priority mapping to populate Details view.

In the Source box, click drop-down menu access to open the drop-down menu, and select Add transformation.

In the Transformations pane, select append, and in the Arguments pane, enter -level for the value of suffix.

This append function adds the specified suffix to the end of the status string before mapping it to the target priority data item.

Click OK.

By default, Details view displays the results of adding the append function to the status data item in a user-friendly format. You can change this formatting by clicking the right-most drop-down menu access on the Source box, and selecting Show standard formatting.

Run a JUnit test on your TransformationTest.java file. For details, see the section called “Creating the transformation test file and running the JUnit test”.

Console view displays the json-formatted output data:

{"custId":"[ACME-123]","priority":"GOLD-level","orderId":"ORDER1","origin":"Web",
"approvalCode":"AUTO_OK","lineItems":[{"amount":1000,"cost":2.25},{"itemId":"ACME-123",
"amount":400,"cost":1.25}]}

Publishing a Fuse Integration project with data transformation to a Red Hat JBoss Fuse server

Before you publish your data transformation project to a JBoss Fuse server (see Chapter 27, Publishing Fuse Integration Projects to a Server), you need to install the following features in the JBoss Fuse runtime:

camel-dozer

camel-jackson

camel-jaxb

To install the required features on the JBoss Fuse runtime:

If not already there, switch to Fuse Integration perspective.

If necessary, add the JBoss Fuse server to the Servers list (see the section called “Adding a Server”).

Start up the JBoss Fuse Server (see the section called “Starting a Server”), and wait for the JBoss Fuse shell to appear in Terminal view:

For each of the required camel- features, at the JBossFuse:admin@root> prompt type:

features:install camel-<featureName>

Where featureName is one of dozer, jackson, or jaxb.

To verify that each of the features was successfully installed, at the JBossFuse:admin@root> prompt type:

features:list --ordered --installed

You should see the camel features you just installed in the output listing:

Chapter 11. Using the Switchyard Tooling

JBoss Integration and SOA Development

JBoss Integration and SOA Development

The JBoss SwitchYard Tooling for JBoss Developer Studio supports integration and SOA development by providing these features:

Creation of SwitchYard projects

Configuration of SwitchYard capabilities

Editing SwitchYard application configuration using a graphical editor

Java2WSDL transformation

XML catalog entries for SwitchYard configuration schema

Support for workspace deployment of SwitchYard projects

The JBoss SwitchYard Tooling plug-in is provided by the JBoss Development Studio Integration Stack.

Installing JBoss Developer Studio Integration Stack

JBoss Developer Studio Integration Stack (JBDSIS) is packaged as a plug-in for JBoss Developer Studio installations. It contains numerous, individual plug-ins, including the Fuse and SwitchYard tooling. You can download JBDSIS through JBoss Central, and then install all of the plug-ins it contains or only a select few. For more details, see Product Documentation for Red Hat JBoss Developer Studio Integration Stack.

Once installed, you may need to complete additional configuration tasks before you can use the individual JBoss Developer Studio Integration Stack components.

Here are some general tips to follow:

Honor all XML schema locations

After installation, go to XML → XML Files → Validation → Preferences and disable Honor all XML schema locations. This prevents erroneous XML validation errors from appearing on switchyard.xml files.

DTD warning

Importing SwitchYard quickstarts into JBoss Developer Studio results in non-fatal warnings regarding log4j.dtd. You can safely ignore them. To stop receiving the warning, make sure that either the log4j.xml or log4j.properties file is present before starting a project.

JavaSE-1.6 error message

When commencing a project, the warning "Build path specifies execution environment JavaSE-1.6" may appear. To disable this warning, go to your Java preferences and ensure that JavaSE-1.7 or JavaSE-1.8 is checked to support JavaSE-1.6 environments.

Running a SwitchYard Project on a JBoss Fuse Server

To publish and run Fuse SwitchYard projects on an installed Fuse server, you must first add the server and its runtime definition to the tooling's Servers list. Once added to the list, the server appears in the Servers view, where you can configure it, start and stop it, and publish projects to it.

You can publish SwitchYard projects to JBoss Fuse 6.3 and newer servers that you have defined and added to the Servers list.

Note

If you haven't already installed a server, you can do so when you define and add it to the Servers list.

Adding a JBoss Fuse server

Follow the instructions in the section called “Adding a Server” to define and add an installed JBoss Fuse 6.3 server.

Installing the SwitchYard features on the server

JBoss Fuse is SwitchYard-ready, but you have to install the switchyard features.

In the Servers view, select the JBoss Fuse server you just added, and click Installing the SwitchYard features on the server on the view's menu bar to start it up.

Console view opens and displays the server's startup progress:

Wait until [PATCH] Storing user changes appears at the end of the output.

Switch to Shell view, and install the switchyard-* features, one after another, on the server:

JBossFuse:admin@root> features:install switchyard-bean
JBossFuse:admin@root> features:install switchyard-camel
JBossFuse:admin@root> features:install switchyard-soap

Note

To see a list of all available SwitchYard-related features, enter features:list | grep switchyard*.

Check that the switchyard-* features are installed and active:

JBossFuse:admin@root> osgi:list

The end of the output should show the switchyard components installed and active :

Importing a SwitchYard quickstart project

The SwitchYard quickstarts are installed in $FUSE_HOME/quickstarts/switchyard/.

Right-click in Project Explorer, and select Import → Import... to open the Choose Import source dialog.

In the Maven folder, select Existing Maven Projects.

Click Next to open the Select Maven projects dialog.

Click the Browse button next to the Root Directory field to locate and select the $FUSE_HOME/quickstarts/switchyard/bean-service.

In the Projects pane, make sure the box next to the pom.xml file entry for the switchyard-bean-service is checked to select it.

Click Finish to start the import.

The switchyard-bean-service project appears in Project Explorer.

Wait a moment for the import process to finish.

Note

See the section called “Resolving Maven dependency errors” for details on what to do if you encounter Maven dependency errors, caused by failure to download all of the project's dependencies from the Maven repositories.

In Project Explorer, right-click the switchyard-bean-service project to open the context menu, and select Enable Fuse Camel Nature.

This option enables you to publish a switchyard project to the JBoss Fuse server, which you can do at any time now (for details, see the section called “Publishing a SwitchYard project to the server”).

Testing the SwitchYard quickstart project locally

It's a good idea to run projects as a JUnit test to check that they successfully build and run locally. The provided test files included with each SwitchYard quickstart are complete and comprehensive and need no modification.

In Project Explorer, expand the switchyard-bean-service project to expose src/test/java/OrderServiceTest.java file.

If you want to take a look at the test code, double-click the file to open it in the Java editor.

In Project Explorer, right-click the OrderServiceTest.java file to open the context menu, and select Run As → JUnit Test.

Console view automatically opens and displays the log entries generated by the JUnit test.

The last two log entries indicate that the test ran successfully against Apache Camel as expected.

Click the JUnit tab to open JUnit view.

This test proves that the switchyard-bean-service successfully builds and runs locally.

Note

If you failed to set the Execution environment to JavaSE-1.7 or JavaSE-1.8 when you defined the JBoss Fuse server, this test will fail. You can easily reset it by right-clicking the JRE System Library node in Project Explorer, and selecting Build Path → Configure Build Path. In the Java Build Path dialog's Library tab, edit the current library to change the Execution environment setting to JavaSE-1.7 or JavaSE-1.8. (The library you select must be installed on your machine.) Then rerun the test.

Publishing a SwitchYard project to the server

You can publish a project to a supported server, defined and listed in the Servers view, whether it's running or not. A published project will run as scheduled according to the server's settings (for details, see Chapter 27, Publishing Fuse Integration Projects to a Server).

In the Servers view, right-click the target server to open the context menu, and then select Add and Remove.

When a project is ready for publishing, it appears in the Available column. For example:

Note

The option If server is started, publish changes immediately is enable by default. See the section called “Publishing Fuse projects automatically when resources change” for information on how this option works and on using other publishing options.

Double-click the project in the Available column to move it to the Configured column.

Click Finish.

Once publishing has finished, the project appears as a node under the server runtime node in the Servers view.

Servers view shows that both the server runtime and the project are started and synchronized.

Note

For a server runtime, Synchronized means that all published resources on the server are identical to their local counterparts. For a published resource, Synchronized means that it is identical to its local counterpart.

In Shell view, enter the command osgi:list to confirm that the switchyard-bean-service project is installed and active.

Testing the published SwitchYard project

You can use the JBoss Web Service Tester tool to test your published web service.

Open a web browser, and go to http://localhost:8181/cxf/ to see the available SOAP services with OrderService in the list.

This site provides a link to the OrderService's WSDL.

Click the link to the OrderService's WSDL to open it in the browser.

Copy the URL displayed in the browser's address field.

In JBoss Developer Studio, click Window → Show View → Other, then scroll down to the JBoss Tools Web Services folder, and select Web Service Tester.

Click the drop-down menu labeled GET, and select JAX-WS.

The Request Body pane displays an example SOAP request message.

Click Testing the published SwitchYard project next to Testing the published SwitchYard project to open the Specify the Source WSDL for the Web Service dialog, and then paste the URI you copied in Step 3 into the WSDL URI field.

The Web Service Tester auto fills the remaining fields with the data retrieved from the WSDL.

Click OK.

The Web Service Tester displays the XML request message retrieved from the WSDL in the Request Body pane.

You can enter values for the <order> items <orderId>, <itemId>, and <quantity> to test the project's request and response services.

Note

You can discover what the data types are for each order item. In Project Explorer, double-click src/test/java/OrderServiceTest.java file to open it in the Java editor:

In the Request Body pane, click the value field of each order item and enter an appropriate value for it. For example:

For <orderID> replace ? with ORDER10

For <itemId> replace ? with BUTTER

For <quantity> replace 0 with 1000

Click Testing the published SwitchYard project to the right of Testing the published SwitchYard project to invoke the submitOrder operation. and populate the Response Body pane with an example response message.

Console view automatically opens to show the status of the submitOrder operation:

Switch to the Web Service Tester tool and check the response message in the Response Body pane.

Running a SwitchYard Project on a JBoss Enterprise Application Server

To publish and run Fuse SwitchYard projects on an installed EAP server, you must first:

Install JBoss Fuse on the JBoss EAP server

For details, see Installation of JBoss Fuse on JBoss EAP

Add the server and its runtime definition to the tooling's Servers list

Once added to the list, the server appears in the Servers view, where you can configure it, start and stop it, and publish projects to it.

You can publish SwitchYard projects to Red Hat JBoss Enterprise Platform 6.4 and newer servers that you have defined and added to the Servers list.

Note

If you haven't already installed a server, you can do so when you define and add it to the Servers list.

Adding a JBoss EAP server

You can add a new server to the Servers view in three ways:

In Servers view, click the link No servers are available. Click this link to create a new server....

Note

This link appears in Servers view only when no server has been defined.

Right-click in Servers view to open the context menu, then select New → Server.

On the menu bar, select File → New → Other → Server → Server.

In the Define a New Server dialog, select Red Hat JBoss Enterprise Application Platform 6.1+.

Server's host name and Server name are auto filled by default. In Server name, you can enter a different name to use to identify the server in the Servers view.

Click Next to open the Create a New Server Adapter page.

To specify that the server life-cycle is managed from outside the tooling, check Server is externally managed. Assume server is started..

If you have not configured a runtime before, Create new runtime (next page) appears on the drop-down menu bar under The selected profile requires a runtime (as shown in the figure above). Otherwise, a previously configured runtime appears on the drop-down menu bar.

Note

You can assign the same runtime to multiple server instances, which enables you to quickly launch a server in debug mode or to configure other runtime settings.

To use a previously created runtime with this server, click the drop-down menu and select it from the list (skip to Step 6).

To create a new runtime, select Create new runtime (next page) from the list.

Click Next to open the JBoss Runtime page.

Note

If the server is not already installed on your machine, you can install it now by clicking the link Download and install runtime... and following the site's download instructions. Depending on the site, you may be required to provide valid credentials before you can continue the download process.

Configure the JBoss runtime:

Accept the default for Name, or enter a different name.

In Home Directory, enter the path where the server runtime is installed, or click Browse to find and select it.

Select the runtime JRE from the drop-down menu next to Execution Environment.

If the version you want does not appear on the list, click Environments, and then select the version from the list. The JRE version you select must be installed on your machine.

Accept the defaults for Configuration base directory and Configuration file, or browse to the directory where the .xml configuration file to use is located.

Click Finish.

The server appears in the Servers view.

Importing a SwitchYard quickstart project

The JBoss Fuse on JBoss EAP installer installs the SwitchYard quickstarts in $EAP_HOME/quickstarts/switchyard/.

Right-click in Project Explorer, and select Import → Import... to open the Choose Import source dialog.

In the Maven folder, select Existing Maven Projects.

Click Next to open the Select Maven projects dialog.

Click the Browse button next to the Root Directory field to locate and select the $EAP_HOME/quickstarts/switchyard/bean-service.

In the Projects pane, make sure the pom.xml file entry for the switchyard-bean-service is selected.

Click Finish to start the import.

The switchyard-bean-service project appears in Project Explorer.

Wait a moment for the import process to finish.

Testing a SwitchYard project locally

Before you try to publish your project to a server, it's useful to confirm that it builds and runs locally. The provided test files included with each SwitchYard quickstart are complete and comprehensive and need no modification.

In Project Explorer, expand the switchyard-bean-service project to expose src/test/java/OrderServiceTest.java file.

If you want to take a look at the test code, double-click the file to open it in the Java editor.

In Project Explorer, right-click the OrderServiceTest.java file to open the context menu, and select Run As → JUnit Test.

Console view automatically opens and displays the log entries generated by the JUnit test.

These log entries indicate that the test ran successfully against Apache Camel as expected.

Click the JUnit tab to open JUnit view.

This test proves that the switchyard-bean-service successfully builds and runs locally.

Publishing a SwitchYard project to the server

You can publish a project to a supported EAP server, defined and listed in the Servers view, whether it's running or not. A published project will run as scheduled according to the server's settings (for details, see (Chapter 27, Publishing Fuse Integration Projects to a Server).

Important

The EAP server must have JBoss Fuse on JBoss EAP installed on it. For details, see Installation of JBoss Fuse on JBoss EAP

In the Servers view, select the EAP 6.4 server you just added, and click Publishing a SwitchYard project to the server on the menu bar to start it.

In the Servers view, right-click the server to open the context menu, and select Add and Remove.

When a project is ready for publishing, it appears in the Available column.

Note

The option If server is started, publish changes immediately is enable by default. See the section called “Publishing Fuse projects automatically when resources change” for information on how this option works and on using other publishing options.

Double-click the project in the Available column to move it to the Configured column.

Click Finish.

Once publishing has finished, the project appears as a node under the server runtime node in the Servers view.

Servers view shows that both the server runtime and the project are started and synchronized.

Note

For a server runtime, Synchronized means that all published resources on the server are identical to their local counterparts. For a published resource, Synchronized means that it is identical to its local counterpart.

Look at the log output in Console view to confirm that the switchyard-bean-service project is deployed and running:

Testing the published SwitchYard project

You can use the JBoss Web Service Tester tool to test your published web service.

From the log output in Console view, copy the address of the bean-service project's OrderService.

In the example we are using, the address is http://localhost:8080/quickstart-bean/OrderService.

Open a browser, and paste the address of the OrderService in the browser's address field.

Add ?wsdl to the end of the address, so it reads http://localhost:8080/quickstart-bean/OrderService?wsdl.

Press Enter.

The browser displays the WSDL for the OrderService:

Copy the URL in the browser's address field.

In JBoss Developer Studio, click Window → Show View → Other, then scroll down to the JBoss Tools Web Services folder, and select Web Service Tester.

Click the drop-down menu labeled GET, and select JAX-WS.

The Request Body pane displays an example SOAP request message.

Click Testing the published SwitchYard project next to Testing the published SwitchYard project to open the Specify the Source WSDL for the Web Service dialog, then paste the URL you copied in Step 5 into the WSDL URI field.

The Web Service Tester auto fills the remaining fields with the data retrieved from the WSDL.

Click OK.

The Web Service Tester displays the XML request message retrieved from the WSDL in the Request Body pane.

You can enter values for the <order> items <orderId>, <itemId>, and <quantity> to test the project's request and response services.

Note

You can discover what the data types are for each order item. In Project Explorer, double-click src/test/java/OrderServiceTest.java file to open it in the Java editor:

In the Request Body pane, click the value field of each order item and enter an appropriate value for it. For example:

For <orderID>, replace ? with ORDER10

For <itemId>, replace ? with BUTTER

For <quantity>, replace 0 with 1000

Click Testing the published SwitchYard project to the right of Testing the published SwitchYard project to invoke the submitOrder operation. and populate the Response Body pane with an example response message.

Console view automatically opens to display the status of the submitOrder operation like this—

... INFO [stdout] (http-localhost/127.0.0.1:8080-2) |--- Validating Order object: [OrderID=ORDER10,
       ItemID=BUTTER, quantity=1000] ---|

... INFO [stdout] (http-localhost/127.0.0.1:8080-2) |--- Validating OrderAck object: [OrderID=ORDER10,
       accepted=true, status=Order Accepted [intercepted]] ---|

—at the end of the Console output.

Switch to the Web Service Tester tool and check the response message in the Response Body pane.

Part III. Debugging Routing Contexts

The Camel debugger includes many features for debugging routing contexts:

Setting conditional and unconditional breakpoints on nodes in the route editor

Autolaunching the debugger and switching to Debug Perspective

Interacting with the running routing context:

Switch between breakpoints to quickly compare variable values of message instances

Examine and change the value of variables of interest

Add variables of interest to the Watch list to track them throughout the debug session

Disable and re-enable breakpoints on-the-fly

Track message flow graphically in the routing context runtime

Examine Console logs to track Camel and debugger actions

Note

Before you can run the Camel debugger, you must set breakpoints on the nodes of interest displayed on the route editor's canvas. Once that's done, you can run the Camel debugger on a project's routing context .xml file to find the logic errors in it and fix them. Invoking the Camel debugger runs the routing context in debug mode and opens the Debug perspective (Chapter 2, Debug Perspective).

Chapter 12. Setting Breakpoints

Overview

To set breakpoints, your project's routing context .xml file must be open in the route editor's Design View.

The Camel debugger supports two types of breakpoints:

Unconditional breakpoints—triggered whenever one is encountered during a debugging session

Conditional breakpoints—triggered only when the breakpoint's specified condition is met during a debugging session

Note

You cannot set breakpoints on Consumer endpoints or on When or Otherwise nodes.

Setting unconditional breakpoints

With your routing context displayed on the canvas in Design View:

Select a node whose state you want to examine during the debugging session.

Click its Setting unconditional breakpoints icon to set an unconditional breakpoint.

Repeat these steps for each node on which you want to set an unconditional breakpoint.

Setting conditional breakpoints

With your routing context displayed on the canvas in Design View:

Select a node whose state you want to examine during the debugging session.

Click its Setting conditional breakpoints icon to set a conditional breakpoint and to open the Edit the condition and language of your breakpoint... dialog:

Click the Language drop-down menu and select the expression langauge to use to create the condition that will trigger the breakpoint.

Fuse Tooling supports twenty-four expression languages from which to choose. Some of these languages provide variables for creating conditional expressions, while others do not.

Click the Variables button to access a list of the selected language's supported variables.

If a list appears, select in sequence one or more of the variables to create the condition for triggering the breakpoint. The variables you select appear in the Condition text box.

If Setting conditional breakpoints appears, enter the expression directly into the Condition text box.

Repeat steps Step 1 through Step 4 for each node on which you want to set a conditional breakpoint.

Disabling breakpoints

You can temporarily disable a breakpoint, leaving it in place, then enable it again later. The Disabling breakpoints button skips over disabled breakpoints during debugging sessions.

To disable a breakpoint, select the node on the canvas and click its Disabling breakpoints icon. The breakpoint turns gray, indicating it has been disabled.

To enable a disabled breakpoint, select the node on the canvas and click its Disabling breakpoints icon. Depending on whether the disabled breakpoint is conditional or unconditional, it turns yellow or red, respectively, to indicate it has been re-enabled.

Note

You can also disable and re-enable breakpoints during debugging sessions. For details, see Chapter 17, Disabling Breakpoints in a Running Context.

Deleting breakpoints

You can delete individual breakpoints or all breakpoints.

Individual breakpoints—in a route container, select the node whose breakpoint you want to delete, and click its Deleting breakpoints icon.

All breakpoints in a particular route—right-click the target route's container, and select Deleting breakpoints Delete all breakpoints.

All breakpoints in all routes—right-click the canvas, and select Deleting breakpoints Delete all breakpoints.

Related topics

Chapter 13, Starting the Camel Debugger

chapter "To Debug a Routing Context" in "Tooling Tutorials"

Chapter 13. Starting the Camel Debugger

Overview

Note

You must set breakpoints in your routing context file before you can start the Camel debugger.

Procedure

In Project Explorer, select the routing context file you want to debug.

Right-click it to open the context menu, and then select Debug As... → Local Camel Context.

Fuse Tooling builds the Camel route, starts up Apache Camel, starts the routing context, enables JMX, starts the route(s) in the routing context, adds the breakpoints to the nodes, and enables the Camel debugger.

The Camel debugger suspends execution of the routing context at the first breakpoint it encounters, and asks whether you want it to open the Debug perspective.

Click Yes to open Debug perspective.

Debug perspective opens with the routing context suspended at the first breakpoint in the running routing context.

Important

Breakpoints are held for a maximum of five minutes, after which debugging automatically resumes, moving on to the next breakpoint or to the end of the routing context if there are no more breakpoints.

Note

To see the console output, you'll need to open Console view if it was not open when you switched perspectives.

Note

By default, Debug perspective opens displaying Outline view, which provides the means to switch between separate routes in a running routing context. If your routing context contains a single route, closing Outline view will provide more space to expand the other views, making it easier to access and examine debugger output.

Watching message exchanges progress through the routing context

Click Watching message exchanges progress through the routing context (Step Over) to jump to the next node of execution in the routing context. Click Watching message exchanges progress through the routing context (Resume) to continue execution at the next active breakpoint in the routing context.

Related topics

Chapter 14, Stopping the Camel Debugger

chapter "To Debug a Routing Context" in "Tooling Tutorials"

Chapter 14. Stopping the Camel Debugger

Overview

To stop the Camel debugger, click Terminate button on the menu bar once if the debugging session has ended. Otherwise you need to click Terminate button twice. Once to terminate the currently running node thread and once to terminate the Camel Context thread (both displayed in Debug view).

Note

Terminating the Camel debugger also terminates the Console but does not clear its output. To clear the output, click Overview (Clear Console) on Console view's menu bar.

Terminating the Camel Debugger before the session ends

Terminating the debugger before the debugging session ends may add extraneous entries to some of the project's folders in Project Explorer. For example, you may see message lock files, such as message3.xml.camelLock, in an input source directory. You need to delete any .camelLock file before you run the debugger again. To do so, right-click the .camelLock file entry to open the context menu, and then select Delete. When asked to confirm the operation, click OK.

Closing the Camel debugger

After you have finished debugging your project, you may want to close Debug perspective to make more space for your workbench.

To do so, right-click Debug perspective icon on the right side of the JBoss Developer Studio toolbar, and then select Close.

Related topics

Chapter 13, Starting the Camel Debugger

chapter "To Debug a Routing Context" in "Tooling Tutorials"

Chapter 15. Changing Variable Values

Overview

When the Camel debugger hits a breakpoint, Variables view displays the values of all variables available at that point in the routing context. Some variables are editable, allowing you to change their value. This enables you to see how the application handles changes in program state.

Note

Not all variables are editable. The context menu of those that are displays the option, Change Value....

Procedure

To change the value of a variable:

If necessary, start up the debugger. See Chapter 13, Starting the Camel Debugger.

In Variables view, select a variable whose value you want to change, and then click its Value field.

The variable's value field turns a lighter shade of blue, indicating it is in edit mode.

Note

Alternatively, you can right-click the variable to open its context menu, and select Change Value... to edit its value.

Enter the new value and then click Enter.

Console view displays an INFO level log entry noting the change in the variable's value (for example, Breakpoint at node to1 is updating message header on exchangeId: ID-dhcp-97-16-bos-redhat-com-52574-1417298894070-0-2 with header: Destination and value: UNITED KINGDOM).

Continue stepping through the breakpoints and check whether the message is processed as expected. At each step, check Debug view, Variables view, and the Console output.

Related topics

Chapter 17, Disabling Breakpoints in a Running Context

Chapter 16, Adding Variables to the Watch List

chapter "To Debug a Routing Context" in "Tooling Tutorials"

Chapter 16. Adding Variables to the Watch List

Overview

By adding them to the watch list, you can easily zero in on particular variables to see whether their values change as expected over the course of the routing context.

Procedure

To add a variable to the watch list:

If necessary, start up the debugger. See Chapter 13, Starting the Camel Debugger.

In Variables view, right-click a variable you want to track to open the context menu.

Select Watch.

A new tab, Expressions, opens next to the Breakpoints tab, displaying the name of the added variable and its current value, for example:

Repeat Step 2 and Step 3 to add additional variables to the Watch list.

Note

The variables you add will remain in the watch list until you remove them. To do so, right-click a variable in the list to open the context menu, and then click Remove.

With Expressions view open, step through the routing context to track how the value of each variable in the Watch list changes at each step in the routing context.

Related topics

Chapter 15, Changing Variable Values

Chapter 17. Disabling Breakpoints in a Running Context

Overview

You can disable and re-enable breakpoints in a running routing context in Breakpoints view.

When a breakpoint is disabled, the Overview button causes the debugger to skip over it during the debugging session.

Disabling and enabling breakpoints in Breakpoints view

Breakpoints view opens with all set breakpoints enabled.

To disable a breakpoint, clear its check box.

For each breakpoint you disable, Console view displays an INFO level log entry noting that it has been disabled (for example, Removing breakpoint log2). Likewise, for each breakpoint you re-enable, Console view displays an INFO level log entry noting that it has been enabled (for example, Adding breakpoint log2).

Note

To re-enable a disabled breakpoint, click its check box. Console view displays an INFO level log entry noting that the breakpoint has been added to the selected node.

Part IV. Monitoring and Testing Applications

JMX Navigator provides numerous ways to monitor and test your Fuse applications.

Chapter 18. JMX Navigator

JMX Navigator, shown in Figure 18.1, displays all of the processes running in your application and drives all interactions with the monitoring and testing features. Other areas of the Fuse Integration perspective adapt to display information related to the node selected in JMX Navigator. JMX Navigator's context menu also provides the commands needed to activate route tracing and to add JMS destinations.

Figure 18.1. JMX Navigator

By default, JMX Navigator discovers all of the JMX servers running on the local machine and lists them under the following categories:

Local Processes

Server Connections

User-Defined Connections

Note

You can add other JMX servers using a server's JMX URL. For details, see the section called “Adding a JMX server”.

Viewing Processes in JMX

Overview

JMX Navigator lists all known processes in a series of trees. The root for each tree is a JMX server.

The first tree in the list is a special Local Processes tree that contains all of the JMX servers running on the local machine. You must connect to one of the JMX servers to see the processes it contains.

Viewing processes in a local JMX server

To view information about processes in a local JMX server:

Expand the Local Processes entry in JMX Navigator.

Double-click one of the top-level entries under Local Processes to connect to the JMX server.

Double-click it to open a connection.

Click the expansion arrow icon that appears next to the entry to display the list of all components running in the JVM.

Viewing processes in alternate JMX servers

To view information about processes in an alternate JMX server:

Add the JMX server to JMX Navigator.

Expand the server's entry in JMX Navigator using the expansion arrow icon that appears next to the entry to display the list of all components running in the JVM.

Adding a JMX server

Overview

JMX Navigator lists all of the local JMX servers under the Local Processes branch of the tree. You may need to connect to specific JMX servers to see components deployed on other machines.

To add a JMX server you need to know the JMX URL of the server you want to add.

Procedure

To add a JMX server to the JMX Navigator:

Click New Connection Procedure on the JMX Navigator tab .

In the Create a new JMX connection wizard, select Default JMX Connection.

Click Next>.

Select the Advanced tab.

In the Name field, enter a name for the JMX server.

The name can be any string. It is used to label the entry in the JMX Navigator tree.

In the JMX URL field, enter the JMX URL of the server.

If the JMX server requires authentication, enter your user name and password in the Username and Password fields.

Click Finish.

The new JMX server is displayed as a branch in the User-Defined Connections tree.

Chapter 19. Viewing a component's JMX statistics

Overview

The tooling collects and displays in Properties view all of the JMX statistics reported by Fuse components. This statistical information can provide significant insight into what is happening in your integration application.

JMX statistics are grouped into three categories: Properties, Processor, and Profile.

Procedure

To see a Fuse component's statistics:

Locate the node for the component in JMX Navigator.

You may have to expand nodes on the tree to locate low-level components.

Select the node of the Fuse component whose statistics you want to review.

Open Properties view.

The Properties tab displays the JMX properties of the selected component:

Click the Processors tab to check exchange metrics for the selected component:

Click the Profile tab to check message metrics for the selected node and its subnodes:

Chapter 20. Browsing messages

Overview

A key tool in debugging applications in a distributed environment is seeing all of the messages stored in the JMS destinations and route endpoints in the application. The tooling can browse the following:

JMS destinations

JMS routing endpoints

Apache Camel routing endpoints

SEDA routing endpoints

Browse routing endpoints

Mock routing endpoints

VM routing endpoints

DataSet routing endpoints

Procedure

To browse messages:

In JMX Navigator, select the JMS destination or endpoint you want to browse.

The list of messages is displayed in Messages View.

In Messages View, select an individual message to inspect.

Message details and content are displayed in Properties view:

Related topics

the section called “Tracing messages through a routing context”

Chapter 21. Tracing Routes

Debugging a route often involves solving one of two problems:

a message was improperly transformed

a message failed to reach its destination endpoint

Tracing one or more test messages through the route is the easiest way to discover the source of such problems.

The tooling's route tracing feature enables you to monitor the path a message takes through a route and see how the message is transformed as it passes from processor to processor.

Diagram view displays a graphical representation of the route, which enables you to see the path a message takes through it. For each processor in a route, it also displays the average processing time, in milliseconds, for all messages processed since route start-up and the number of messages processed since route start-up.

Messages view displays the messages processed by a JMS destination or route endpoint selected in the JMX Navigator tree. Selecting an individual message trace in Messages view displays the full details and content of the message in Properties view and highlights the correspoding node in Diagram view.

Tracing messages through a route involves the following steps:

Creating test messages for route tracing

Activating route tracing

Tracing messages through a routing context

Deactivating route tracing

Creating test messages for route tracing

Overview

Route tracing works with any kind of message structure. The Fuse Message wizard creates an empty .xml message, leaving the structuring of the message entirely up to you.

Note

If the folder where you want to store the test messages does not exist, you need to create it before you create the messages.

Creating a new folder to store test messages

To create a new folder:

In Project Explorer, right-click the project root to open the context menu.

Select New → Folder to open the New Folder wizard.

The project root appears in the Enter or select the parent folder field.

Expand the nodes in the graphical representation of the project's hierarchy, and select the node you want to be the parent folder.

In Folder name, enter a name for the new folder.

Click Finish.

The new folder appears in Project Explorer, under the selected parent folder.

Creating a test message

To create a test message:

In Project Explorer, right-click the project to open the context menu.

Select New → Fuse Message to open the New File wizard.

Expand the nodes in the graphical representation of the project's hierarchy, and select the folder in which you want to store the new test message.

In File name, enter a name for the message, or accept the default (message.xml).

Click Finish.

The new message opens in the XML editor.

Fill in the message contents, both body and header text.

Note

You may see the warning No grammar constraints (DTD or XML Schema) referenced in the document, depending on the header text you entered. You can safely ignore this warning .

Related topics

the section called “Tracing messages through a routing context”

chapter "To Trace a Message Through a Route" in "Tooling Tutorials"

Activating route tracing

Overview

Before you can trace messages through a routing context, you must activate route tracing for the routing context.

Procedure

To start tracing on a routing context:

In JMX Navigator, select the running routing context on which you want to start tracing.

Note

You can select any route in the context to start tracing on the entire context.

Right-click it to open the context menu, and then select Start Tracing to start the trace.

If Stop Tracing Context is enabled on the context menu, then tracing is already active.

Related topics

the section called “Tracing messages through a routing context”

the section called “Deactivating route tracing”

Tracing messages through a routing context

Overview

The best way to see what's happening in a routing context is to watch what happens to a message at each stop along the way. The tooling provides a mechanism for dropping messages into a running routing context and tracing the path the messages take through it.

Procedure

To trace messages through a routing context:

Create one or more test messages as described in the section called “Creating test messages for route tracing”.

In Project Explorer, right-click the project's Camel context file to open the context menu, and select Run As → Local Camel Context (without Tests).

Note

Do not run it as Local Camel Context unless you have created a comprehensive JUnit test for the project.

Activate tracing for the running routing context as described in the section called “Activating route tracing”.

Drag one of the test messages from Project Explorer onto the routing context's starting point in JMX Navigator .

In JMX Navigator, select the routing context being traced.

The tooling populates Messages view with message instances that represent the message at each stage in the traced context.

Diagram view displays a graphical representation of the selected routing context.

In Messages view, select one of the message instances.

Properties view displays the full details and content of the message instance.

In Diagram view, the route step corresponding to the selected message instance is highlighted. If the route step is a processing step, the tooling tags the exiting path with timing and processing metrics.

Repeat this prodedure as needed.

Related topics

the section called “Creating test messages for route tracing”

the section called “Activating route tracing”

the section called “Deactivating route tracing”

chapter "To Trace a Message Through a Route" in "Tooling Tutorials"

Deactivating route tracing

Overview

When you are finished debugging the routes in a routing context, you should deactivate tracing.

Important

Deactivating tracing stops tracing and flushes the trace data for all of the routes in the routing context. This means that you cannot review any past tracing sessions.

Procedure

To stop tracing for a routing context:

In JMX Navigator, select the running routing context for which you want to deactivate tracing.

Note

You can select any route in the context to stop tracing for the context.

Right-click it to open the context menu, and then select Stop Tracing Context.

If Start Tracing appears on the context menu, tracing is not activated for the routing context.

Related topics

the section called “Activating route tracing”

the section called “Tracing messages through a routing context”

Chapter 22. Managing JMS destinations

The tooling's JMX Navigator enables you to easily add or delete JMS destinations from a running instance of Red Hat JBoss Fuse A-MQ.

Important

These changes are not persistent across broker restarts.

Adding a JMS destination

Overview

When testing a new scenario, it is convenient to add a new JMS destination to one of your brokers. The tooling provides a menu choice for adding a destination with a single click.

Procedure

To add a JMS destination to a broker:

In JMX Navigator, select either the Queues child or the Topics child under the broker node for which you want to add a destination.

Right-click it to open the context menu, and then select either Create Queue or Create Topic.

In either the Create Queue or Create Topic dialog, enter a name for the new destination.

Click OK.

Right-click either the Queues or the Topics child, and then select Refresh.

The new destination appears in JMX Navigator under the Queues or the Topics child.

Related topics

the section called “Deleting a JMS destination”

Deleting a JMS destination

Overview

When testing failover scenarios or other scenarios that involve handling failures, it's convenient to be able to easily remove a JMS destination. The tooling has a menu option that allows you to remove a destination with a single click.

Procedure

To delete a JMS destination:

In JMX Navigator, select the JMS destination you want to delete listed under the Queues or the Topics child.

Right-click it to open the context menu, and then select Delete Queue/Topic.

Related topics

the section called “Adding a JMS destination”

Chapter 23. Managing routing endpoints

JMX Navigator enables you to easily add or delete routing endpoints.

Important

These changes are not persistent across routing context restarts.

Adding a routing endpoint

Overview

When testing a new scenario, it is convenient to add a new endpoint to a routing context. The tooling provides a menu choice for adding a routing endpoint with a single click.

Procedure

To add an endpoint to a routing context:

In JMX Navigator, select the Endpoints child under the routing context node for which you want to add an endpoint.

Right-click it to open the context menu, and then select Create Endpoint.

In the Create Endpoint dialog, enter a URL defining the new endpoint.

(For example, file://target/messages/validOrders.)

Click OK.

Right-click the routing context node, and select Refresh.

The new destination appears in JMX Navigator under the Endpoints node, in a folder corresponding to the type of endpoint it is (for example, file).

Note

The new endpoint also appears in Project Explorer, in the project's Target folder under the node that corresponds to the endpoint's URL, but only after you have refreshed the root project. This folder, created by Camel, is not used by the tooling, so you can safely delete it using its context menu.

Related topics

the section called “Deleting a routing endpoint”

Deleting a routing endpoint

Overview

When testing failover scenarios or other scenarios that involve handling failures, it is convenient to be able to easily remove an endpoint from a routing context. The tooling has a menu option that allows you to remove an endpoint with a single click.

Procedure

To delete a routing endpoint:

In JMX Navigator, select the endpoint you want delete.

Right-click it to open the context menu, and then select Delete Endpoint.

The tooling deletes the endpoint, but you need to do a refresh to remove it from view.

Right-click the Endpoints node, and then select Refresh.

The endpoint disappears from JMX Navigator.

Note

To remove the endpoint's node from Project Explorer without rerunning the project, you need to explicitly delete it by right-clicking the node and selecting Delete. To remove it from view, Refresh the project.

Related topics

the section called “Adding a routing endpoint”

Chapter 24. Editing running routes

Overview

If you want to experiment with changes to a running route, you can make the edits directly from JMX Navigator. The tooling opens the context file containing the route in the route editor. When your changes are saved, they take effect immediately.

The changes are made to the in-memory model of the running context, but are not persisted in the original project or anywhere else.

Note

If you want to save the changes permanently, you must use the Save As menu option, which saves the changes in a new routing context file.

Procedure

To edit a running route:

In JMX Navigator, select the context containing the routes you want to edit.

Right-click to open the context menu, and select Edit Routes.

The route editor displays the context and all of its routes.

Edit the routes as described in Part II, “Developing Applications”.

When done, save the changes.

Select File → Save to update the in-memory version of the routing context.

Changes take effect immediately.

Select File → Save As to save changes to the routing context in a new routing context file.

Related topics

the section called “Adding routes to the routing context”

the section called “Adding patterns to a route”

the section called “Configuring a pattern”

the section called “Connecting patterns to make a route”

the section called “Removing patterns from a route”

the section called “Disconnecting two patterns”

the section called “Deleting a route”

Chapter 25. Managing routing contexts

JMX Navigator enables you to easily suspend and resume routing contexts.

Suspending a routing context

Overview

The tooling enables you to suspend the operation of a routing context in JMX Navigator. Suspending a context gracefully shuts down all of the routes in the context, but keeps them loaded in memory, so that they can easily be resumed.

Procedure

To suspend a routing context:

In JMX Navigator, expand the project's Camel Contexts node, and select the routing context you want to suspend.

Right-click it to open the context menu, and then select Suspend Camel Context.

Note

If Resume Camel Context appears on the context menu, the context is already suspended.

Related topics

the section called “Resuming a routing context”

Resuming a routing context

Overview

The tooling enables you to resume a suspended routing context in JMX Navigator. Resuming a context restarts all of the routes in it, so that they can process messages.

Procedure

To resume a routing context:

In JMX Navigator, expand the project's Camel Contexts node, and select the routing context you want to resume.

Right-click it to open the context menu, and then select Resume Camel Context.

Note

If Suspend Camel Context appears in the context menu, the context and its routes are running.

Related topics

the section called “Suspending a routing context”

Part V. Publishing Applications to a Container

To publish Fuse Integration projects to a server container, you must first add the server and its runime definition to the tooling's Servers list. Then you can assign projects to the server runtime and set the publishing options for it.

Chapter 26. Managing servers

The Servers panel enables you to run and manage servers in your Red Hat Developer Studio environment. The supported servers are:

Red Hat JBoss Fuse Server—versions 6.2+ and 6.3

Red Hat JBoss Enterprise Application Platform—version 6.4

Note

For step by step instructions on how to publish a Camel project to Red Hat JBoss Fuse, see chapter "To Publish a Fuse Project to Red Hat JBoss Fuse" in "Tooling Tutorials".

Adding a Server

Overview

For the tooling to manage a server, you need to add the server to the Servers list. Once added, the server appears in Servers panel, where you can connect to it and publish your Fuse Integration projects.

Note

If adding a Red Hat JBoss Fuse 6.2+ or 6.3 server, it's recommended that you edit its installDir/etc/users.properties file and add user information, in the form of user=password,role, to enable the tooling to establish an SSH connection to the server.

Procedure

You can add a new server to the Servers panel in three ways:

In Servers panel, click the link No servers are available. Click this link to create a new server....

Note

This link appears in Servers panel only when no server has been defined.

If you defined and added a server when you first created your project, the Servers panel displays that server.

Right-click in Servers panel to open the context menu, then select New → Server.

On the menu bar, select File → New → Other → Server → Server.

In the Define a New Server dialog, expand the JBoss Fuse node to expose the list of available server options:

Click the server you want to add.

In Server's host name, accept the default (localhost).

Note

The address of localhost is 0.0.0.0.

In Server name, accept the default, or enter a different name for the runtime server.

In Server runtime environment, accept the default, or enter a different name for the server runtime environment.

Click Next to open the server's Runtime definition page:

Note

If the server is not already installed on your machine, you can install it now by clicking the link Download and install runtime... and following the site's download instructions. Depending on the site, you may be required to provide valid credentials before you can continue the download process.

Accept the default for Name.

In Home Directory, enter the path where the server runtime is installed, or click Browse to find and select it.

Select the runtime JRE from the drop-down menu next to Execution Environment.

If the version you want does not appear on the list, click the Environments button and select the version from that list. The JRE version you select must be installed on your machine.

Note

JBoss Fuse 6.3 requires either JRE version 1.8 or 1.7.

Leave the Alternate JRE option as is.

Click Next > to save the server's runtime definition and open its Configuration details page:

Accept the default for SSH Port (8101).

The runtime uses the SSH port to connect to the server's Karaf shell. If this default is incorrect for your setup, you can discover the correct port number by looking in the server's installDir/etc/org.apache.karaf.shell.cfg file.

In User Name, enter the name used to log into the server.

In the case of Red Hat JBoss Fuse, this is a user name stored in the Red Hat JBoss Fuse installDir/etc/users.properties file.

Note

If the default user has been activated (uncommented) in the /etc/users.properties file, the tooling autofills User Name and Password with the default user's name and password, as shown in Step 11. The default user is already activated in JBoss Fuse 6.2, but not in JBoss Fuse 6.0 or 6.1.

If one has not been set, you can either add one to that file using the format user=password,role (for example, joe=secret,Administrator), or you can set one using the karaf jaas command set:

jaas:realms—to list the realms

jaas:manage --index 1—to edit the first (server) realm

jaas:useradd <username> <password>—to add a user and associated password

jaas:roleadd <username> Administrator—to specify the new user's role

jaas:update—to update the realm with the new user information

If a jaas realm has already been selected for the server, you can discover the user name by issuing the command JBossFuse:karaf@root>jaas:users.

In Password, enter the password required for User Name to log into the server.

Click Finish to save the server's configuration details.

The server runtime will appear in Servers panel. For example:

Expanding the server node exposes the server's JMX node:

Starting a Server

Overview

When you start a configured server, the tooling opens the server's remote management console in a Terminal panel. This allows you to easily manage the container while testing your application.

Procedure

To start a server:

In the Servers panel, select the server you want to start.

Click run button .

Console view opens and displays a message asking you to wait while the container is starting; for example:

Note

If you did not properly configure the user name and password for opening the remote console, a dialog opens asking you to enter the proper credentials. See the section called “Adding a Server”.

After the container has started up, Terminal view opens to display the container's management console; for example:

The running server appears in Servers panel:

The running server also appears in JMX Navigator under Server Connections:

Note

If the server is running on the same machine as the tooling, it also has an entry under Local Processes.

Connecting to a Running Server

Overview

After you start up a configured server, it appears in Servers panel and in JMX Navigator, under the ServerConnections node. You may need to expand the Server Connections node to see the server.

To publish and test your Fuse project application on the running server, you must first connect to it. You can connect to a running server either in Servers panel or in JMX Navigator.

Note

Servers panel and JMX Navigator are synchronized with regards to server connections, so connecting to a server in Servers panel also connects it in JMX Navigator, and vice versa.

Connecting to a running server in Servers panel

In Servers panel, expand the server runtime to expose its JMX[Disconnected] node.

Double-click the JMX[Disconnected] node:

Connecting to a running server in JMX Navigator

In JMX Navigator, select the server to which you want to connect under the Server Connections node.

Double-click it:

Viewing bundles installed on the connected server

In either the Servers panel or JMX Navigator, expand the server runtime tree to expose the Bundles node, and select it.

The tooling populates Properties view with a list of bundles that are installed on the server:

Using Properties view's Search tool, you can search for bundles by their Symbolic Name or by their Identifier, if you know it. As you type in the symbolic name or the identifier, the list updates, showing only the bundles that match the current search string.

Note

Alternatively, you can issue the osgi:list command in Terminal view to see a generated list of bundles installed on the JBoss Fuse server runtime. The tooling uses a different naming scheme for OSGi bundles displayed by the osgi:list command.

In the <build> section of project's pom.xml file, you can find the bundle's symbolic name and its bundle name (OSGi) listed in the maven-bundle-plugin entry. For more details, see the section called “Verifying the project was published to the server”.

Disconnecting from a Server

Overview

When you are done testing your application, you can disconnect from the server without stopping it.

Note

Servers panel and JMX Navigator are synchronized with regards to server connections, so disconnecting from a server in Servers panel also disconnects it in JMX Navigator, and vice versa.

Disconnecting from a server in Servers panel

In Servers panel, expand the server runtime to expose its JMX[Connected] node.

Right-click the JMX[Connected] node to open the context menu, and then select Disconnect.

Disconnecting from a server in JMX Navigator

In JMX Navigator, select the server from which you want to disconnect under Server Connections.

Right-click it to open the context menu, and then select Disconnect.

Stopping a Server

Overview

You can shut down a server in one of two ways:

from Servers panel

from the server's remote console in Terminal view

Using Servers panel

To stop a server:

In Servers panel, select the server you want to stop.

Click stop button .

Using the remote console

To stop a server:

Open the Terminal view hosting the server's remote console.

Type CTRL+D.

Deleting a Server

Overview

When you are finished with a configured server, or if you misconfigure a server, it is easy to delete it and it's configuration.

First you delete the server from Servers view or from JMX Navigator, and then you delete the server's configuration.

Deleting a server

In Servers panel, right-click the server you want to delete to open the context menu.

Select Delete.

Click OK.

Deleting the server's configuration

On the menu bar, click JBoss Developer Studio → Preferences → Server.

Note

On Linux and Windows machines, you access Preferences through the Window menu.

Expand the Server folder, and then select Runtime Environments to open the Server Runtime Environments page.

From the list, select the runtime environment of the server that you previously deleted from Servers panel, and then click Remove.

Click OK.

Chapter 27. Publishing Fuse Integration Projects to a Server

Abstract

You deploy Fuse Integration projects into a server runtime using the Eclipse publishing mechanism. To do so, you must have defined and added the server to the Servers panel in Fuse Integration perspective. For details, see Chapter 26, Managing servers. For a step-by-step demonstration, see chapter "To Publish a Fuse Project to Red Hat JBoss Fuse" in "Tooling Tutorials".

Overview

You can set up supported servers to publish assigned Fuse projects automatically or to publish them only when you manually invoke the publish command.

Each server runtime added to the Servers panel has its own Overview page that contains its configuration, connection, and publishing details:

You may need to expand Publishing to expose the server runtime publishing options and default settings:

Never publish automatically—You must select this option to manually publish projects.

Important

You must also disable the If server started, publish changes immediately option on the server's Add and Remove page (for details see, the section called “Publishing Fuse projects manually”.

Automatically publish when resources change—[default] Enable this option to automatically publish or republish a Fuse project when you save changes made to it. How quickly projects are published depends on the Publishing interval (default is 15 seconds).

Automatically publish after a build event—For Fuse projects, works the same as Automatically publish when resources change.

Publishing Fuse projects automatically when resources change

The default publishing option for server runtimes is Automatically publish when resources change.

If necessary, start up the server runtime to which you want to publish a Fuse project. For details, see the section called “Starting a Server”.

In the Servers panel, double-click the server runtime to open its Overview page.

Expand Publishing, and then select Automatically publish when resources change.

To increase or decrease the interval between publishing cycles, click the radio button next to Publishing interval (in seconds) up or down, as appropriate.

In the Servers panel, right-click the server runtime to open the context menu, and then select Add and Remove.

All resources available for publishing appear in the Available column.

To assign a resource (in this case, the CBRroute Fuse project) to the server runtime:

double-click it, or

select it, and click Add .

The selected resource moves to the Configured column:

At this stage, the time at which the assigned resource would actually be published depends on whether the server runtime was running and on the Publishing interval setting. However, if the server was stopped, you would have to manually publish the project after you started the server (for details, see the section called “Publishing Fuse projects manually”).

Click the If server started, publish changes immediately option to enable it:

This option ensures that the configured project is published immediately once you click Finish. The Automatically publish when resources change option on the server runtime Overview page ensures that the configured project is republished whenever changes made to the local project are saved.

Click Finish.

The project appears in the Servers panel under the server runtime node, and the server runtime status reports [Started,Publishing...].

When publishing is done, the status of both the server runtime and the project report [Started,Synchronized]:

Note

For a server runtime, Synchronized means that all published resources on the server are identical to their local counterparts. For a published resource, Synchronized means that it is identical to its local counterpart.

Publishing Fuse projects manually

If necessary, start up the server runtime to which you want to publish a Fuse project. For details, see the section called “Starting a Server”.

In the Servers panel, double-click the server runtime to open its Overview page.

Expand Publishing, and then select Never publish automatically.

Click File → Save to save the publishing option changes.

If the Fuse project has already been assigned to the server runtime, make sure the If server started, publish changes immediately option is disabled.

In the Servers panel, right-click the server runtime to open the context menu.

Click Add and Remove... to open the server's Add and Remove page.

If the If server started, publish changes immediately option is enabled, disable it.

Skip to Step 7.

If the Fuse project has not been assigned to the server runtime, assign it now.

Follow Step 5 through Step 6 in the section called “Publishing Fuse projects automatically when resources change”.

Do not enable the If server started, publish changes immediately option.

Click Finish.

The project appears in the Servers panel under the server runtime node, and the server runtime status reports [Started]:

In the Servers panel, right-click the project's node (in this case, the Fuse project CBRroute) to open the context menu:

Select Full Publish.

During the publishing operation, the status of both the server runtime and the project report [Started,Republish]:

When publishing is done, the status of both the server runtime and the project report [Started,Synchronized]:

Note

The tooling does not support the Incremental Publish option. Clicking Incremental Publish results in a full publish.

Verifying the project was published to the server

After you have published a Fuse project to a server runtime, you can connect to the server and check that the project's bundle was installed on it.

Connect to the server runtime. For details see the section called “Connecting to a running server in Servers panel”.

In the Servers panel, expand the server runtime tree to expose the Bundles node and select it.

The tooling populates Properties view with a list of bundles that are installed on the server:

To find your project's bundle, either scroll down to the bottom of the list, or start typing the bundle's Symbolic Name in Properties view's Search box. The bundle's Symbolic Name is the name you gave your project when you created it.

Note

Alternatively, you can issue the osgi:list command in Terminal view to see a generated list of bundles installed on the JBoss Fuse server runtime. The tooling uses a different naming scheme for OSGi bundles displayed by the osgi:list command.

In the <build> section of project's pom.xml file, you can find the bundle's symbolic name and its bundle name (OSGi) listed in the maven-bundle-plugin entry; for example:

Related topics

Appendix A. Tooling preferences

Name

Editor — Sets the default value for some route editor properties.

Properties

Table A.1 describes the properties you can specify.

Table A.1. Editor Properties

Name | Default | Description
Language | Simple | Specifies the default expression language used by the route editor.
ID values | Enabled | Determines whether ID values are used to label EIP nodes on the route editor's canvas.
Layout direction | Right | Specifies the direction in which routes are laid out on the route editor's canvas.
Diagram grid | Enabled | Determines whether a grid overly is displayed in the background on the route editor's canvas.

Related topics

the section called “Configuring the route editor”