Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 2. Editing a routing context in the route editor

The following sections describe how to edit a routing context.

2.1. 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. A complete route typically consists of a starting endpoint, a string of processing nodes, and one or more destination endpoints.

When you add a pattern into a Route container on the canvas, the pattern takes on a color that indicates its type of node:

  • 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 add a pattern to a route:

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

  2. Use one of the following methods:

    • Click the pattern in the Palette and then, in the canvas, click the route container.

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

      Alternatively, you can add 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 adding the pattern on the target. For valid connections, the tooling behaves differently depending on whether the target is a node or a connection:

      • For an existing node, the tooling 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
      • For an existing connection, the tooling inserts the new node between the two connected nodes and automatically rewires the connections between the three nodes

  3. Optionally, you can manually connect two nodes:

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

    2. Drag the source node’s connector arrow ( ConnectorArrow ) to the target node, and release the mouse button to drop the connector on it.

      Note

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

  4. After you add a pattern inside a Route container, you can drag it to different location inside the route container or to another route container on the canvas, as long as it can establish a valid connection. You can also relocate existing nodes that are already connected, as long as the move can establish another valid connection.

    To view a short video that illustrates how to reposition endpoints, click here.

  5. Select File → Save. The tooling saves routes in the context file regardless of whether they are complete.

The new pattern appears on the canvas in the Route container and becomes the selected node. The Properties view displays a list of the new node’s properties that you can edit.

Changing the layout direction

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, select Windows → Preferences → Fuse Tooling → Editor → Choose the layout direction for the diagram editor.
  • On OS X, select Developer Studio → Preferences → Fuse Tooling → Editor → Choose the layout direction for the diagram editor.

2.2. Configuring a pattern

Overview

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

The tooling’s Properties view provides a form that lists all of the configuration details a particular pattern supports. The Properties view 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:

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

    The Properties view 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.

  2. Edit the fields in the Properties view to configure the node.
  3. When done, save your work by selecting File → Save from the menu bar.

2.3. 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 garbageIcon 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:

  1. Select the node you want to delete.
  2. Click its garbageIcon icon.
  3. 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.

2.4. 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.

Procedure

To add another route to the camelContext:

  1. In the Design tab, do one of the following:

    • Click a Route pattern in the Palette's Routing drawer and then click in the canvas where you want to place the route.

    • Drag a Route pattern from the Palette's Routing drawer and drop it onto the canvas.

      The Properties view displays a list of the new route’s properties that you can edit.

  2. In the Properties view, 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
    • Values for any other properties, as needed. Required properties are indicated by an asterisk (*).
  3. On the menu bar, select File → Save to save the changes you made to the routing context file.

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

    routeEntriesProjectExplorer
  5. To display all routes in the context, as space allows, click the context file entry in the Project Explorer view.

  6. To view the code generated by the tooling when you add a route to the canvas, click the Source tab.

    Note

    You can alternately add a route in the Source tab, by adding a <route/> element to the existing list within the camelContext element.

2.5. Deleting a route

Overview

In some cases you made need to delete an entire route from your routing context. The Route container’s garbageIcon 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:

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

    routeEntriesProjectExplorer

  2. On the canvas, click the Route container’s garbageIcon icon.

    routeDelete
  3. 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 the Project Explorer view.

2.6. Adding global endpoints, data formats, or beans

Overview

Some routes rely on shared configuration provided by global endpoints, global data formats, or global beans. You can add global elements to the project’s routing context file by using the route editor’s Configurations tab.

To add global elements to your routing context file:

  1. Open your routing context file in the route editor.

  2. At the bottom of the route editor, click the Configurations tab to display global configurations, if there are any.

    ConfigurationsView

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

    CnfigsVAddButton

    The options are:

Adding a global endpoint

  1. In the Create a new global element dialog, select Endpoint and click OK to open the Select component dialog.

    CnfigsVSelectCamComponent1
    Note

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

    Note

    The Grouped by categories option groups components by type.

    CnfigsVSelectCamComponentGrouped

  2. 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.

    CnfigsVCamComponentSelected

    In this example, the JMS component is selected and myJMS is the Id value.

  3. Click Finish.

    CnfigsVmyEndptAdded2

    You can now set properties in the Properties view as needed.

    The tooling autofills Id with the value you entered in the component’s Id field in [globalEndptSelect]. In this example, Camel 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.

    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).

  4. To complete the component’s uri, click Advanced.

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

    JMSCompAdvanPathProp

    The Properties view’s Details and Advanced tabs provide access to all properties available for configuring a particular component.

  6. Click the Consumer (advanced) tab.

    JMSCompConsumerAdvanProps2

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

  7. In the route editor, switch to the Source tab to see the code that the tooling added to the context file (in this example, a configured JMS endpoint), before the first route element.

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

Adding a global data format

  1. In the Create a new global element dialog, select Data Format and click OK to open the Create a global Data Format dialog.

    CnfigsVCreateGlobalDF1

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

  2. Open the Data Format drop-down menu, and select the format you want, for example, xmljson.

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

    CnfigsVCreateGlobalDF2

  4. Click Finish.

    CnfigsVEditGlobalDFprops1

  5. In the Properties view, set property values as appropriate for your project, for example:

    CnfigsVEditGlobalDFprops2

  6. In the route editor, click the Source tab to see the code that the tooling added to the context file. In this example, a configured xmljson data format is before the first route element.

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

Adding a global bean

A global bean enables out-of-route bean definitions that can be referenced from anywhere in the route. When you copy a Bean component from the palette to the route, you can find defined global beans in the Properties view’s Ref dropdown. Select the global bean that you want the Bean component to reference.

To add a global bean element:

  1. In the Create a new global element window, select Bean and click OK to open the Bean Definition dialog.

    CnfigsVCreateGlobalBean1
  2. In the Id field, enter an ID for the global bean, for example, TransformBean. The ID must be unique in the configuration.

  3. Identify a bean class or a factory bean.

    To specify a factory bean, you must have already added another global bean with a factory class specified. You can then select that global bean to declare it as a global bean factory. One instance of the bean factory class will be in the runtime. Other global beans can call factory methods on that class to create their own instances of other classes.

    To fill the Class field, do one of the following:

    • Enter the name of a class that is in the project or in a referenced project.
    • Click …​ to navigate to and select a class that is in the project or in a referenced project.
    • Click + to define a new bean class and add it as a global bean.

  4. If the bean you are adding requires one or more arguments, in the Constructor Arguments section, for each argument:

    1. Click Add.
    2. Optionally, in the Type field, enter the type of the argument. The default is java.lang.String.
    3. In the Value field, enter the value of the argument.
    4. Click OK.

  5. Optionally specify one or more properties that are accessible to the global bean. In the Bean Properties section, do the following for each property:

    1. Click Add.
    2. In the Name field, enter the name of the property.
    3. In the Value field, enter the value of the property.
    4. Click OK.

  6. Click Finish to add the global bean to the configuration. The global bean ID you specified appears in the Configurations tab, for example:

    CnfigsBeanInList

  7. Switch to the Source tab to see the bean element that the tooling added to the context file. For example:

    CnfigsBeanSourceV

  8. Click the Configurations tab to return to the list of global elements and select a global bean to display its standard properties in the Properties view, for example:

    CnfigsBeanProperties
    Note

    To view or edit a property that you specified when you added a global bean, select the bean in the Configurations tab and then click Edit.

  9. Set global bean properties as needed:

    • Depends-on is a string that you can use to identify a bean that must be created before this global bean. Specify the ID (name) of the depended on bean. For example, if you are adding the TransformBean and you set Depends-on to ChangeCaseBean then ChangeCaseBean must be created and then TransformBean can be created. When the beans are being destroyed then TransformBean is destroyed first.
    • Factory-method is useful only when the global bean is a factory class. In this situation, specify or select a static factory method to be called when the bean is referenced.
    • Scope is singleton or prototype. The default, singleton, indicates that Camel uses the same instance of the bean each time the bean is called. Specify prototype when you want Camel to create a new instance of the bean each time the bean is called.
    • Init-method lets you specify or select which of the bean’s init() methods to call when the bean is referenced.
    • Destroy-method lets you specify or select which of the bean’s destory methods to call when the processing performed by the bean is done.
  10. When done, save your changes by selecting File → Save on the menu bar.

Deleting a global element

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

Note

You cannot perform an undo operation for deletion of a global element. If you inadvertently delete a global element that you want to keep in the configuration you might be able to undo the deletion by closing the context file without saving it. If this is not feasible then re-add the inadvertently deleted global element.

  1. In the Configurations tab, select the global element that you want to delete.

    For example, suppose you want to delete the data format myDataFormat that was added in the section called “Adding a global data format”:

    CnfigsVDFSelectDelete

  2. Click Delete.

    The global element myDataFormat disappears from the Configurations tab.

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

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

Editing a global element

The procedure is the same whether modifying the properties of an endpoint, data format or bean that you added to the routing context.

Typically, you do not want to change the ID of a global element. If the global element is already in use in a running route, changing the ID can break references to the global element.

  1. In the Configurations tab, select the global element that you want to edit.

    For example, to edit the endpoint myJMS that was added in the section called “Adding a global endpoint”, select it:

    CnfigsVEndptEditSelect

  2. Click Edit.

    CnfigsVEndptClickEdit

    In the Properties view, modify the element’s properties as needed.

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

    CnfigsEditEndpntConcurConsume2

  4. In the route editor, click the Source tab and check that the tooling added the property concurrentConsumers=2 to the routing context:

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

2.7. Configuring the route editor

Overview

Using Fuse preference settings, you can specify options for the route editor’s behavior and user interface:

  • The default language to use for expressions in Enterprise Integration Patterns (EIPs)
  • The direction (to the right or down) in which patterns flow on the Design canvas when you create routes
  • Whether the Design canvas displays a grid overlay in the background of the canvas.
  • The method for labeling nodes on the Design canvas

Procedure

To configure the route editor:

  1. Open the Editor preferences window:

    • On Linux and Windows machines, select Windows → Preferences → Fuse Tooling → Editor.

    • On OS X, select Developer Studio → Preferences → Fuse Tooling → Editor.

      PreferencesEditor

  2. To select the default language that you want to use for expressions in Enterprise Integration Pattern (EIP) components, select a language from the drop-down list. The default is Simple.
  3. To specify the direction in which you want the route editor to align the patterns in a route, select Down or Right. The default is Down.
  4. To enable or disable displaying a grid overlay on the background of the canvas, check the box next to Show diagram grid in Routes Editor. The default is enabled.

  5. To enable or disable using component IDs as labels in the route editor’s Design tab, check the box next to Use ID values for component labels. The default is disabled.

    If you check this option and also specify a preferred label for a component (see Step 6), then the preferred label is used for that component instead of the ID value.

  6. To use a parameter as the label for a component (except for endpoints, such as File nodes) in the route editor’s Design tab:

    1. In the Preferred labels section, click Add. The New Preferred Label dialog opens.

      NewPreferredLabel

    2. Select a Component and then select the Parameter to use as the label for the component.

    3. Click OK. The component and parameter pairs are listed in the Editor Preferences window.

      PreferredLabelsList

      You can optionally Edit and Remove component labels.

      Note

      If you check the Use ID values for component labels option, it applies to all components except for the components listed in the Preferred labels section.

  7. Click Apply and Close to apply the changes to the Editor preferences and close the Preferences window.
Note

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