Chapter 1. Getting started with Fuse on Karaf

To learn about Fuse on Karaf as well as install, develop, and build your first Fuse application on a Karaf container, the information and instructions here assist you with this. See the following topics for details:

1.1. About Fuse on Karaf

Apache Karaf is based on the OSGi standard from the OSGi Alliance. OSGi originated in the telecommunications industry, where it was used to develop gateway servers that could be upgraded on the fly, without needing to shut down the server (a feature known as hot code swapping). Subsequently, OSGi container technology has found a variety of other uses and is popular for modularised applications (for example, the Eclipse IDE).

Distinctive features of this container technology are:

  • Particularly suited to running in standalone mode.
  • Strong support for modularisation (OSGi bundles), with sophisticated class-loading support.
  • Multiple versions of a dependency can be deployed side by side in a container (but this requires some care in practice).
  • Hot code swapping, enabling you to upgrade or replace a module without shutting down the container. This is a unique feature, but requires significant effort to make it work properly.

Note: Spring Dynamic Modules (Spring-DM) (which integrates Spring XML with the OSGi service layer in Apache Karaf) is not supported. Instead, you should use the Blueprint framework. Using Blueprint XML does not prevent you from using the Java libraries from the Spring framework: the latest version of Spring is compatible with Blueprint.

1.2. Installing Fuse on Karaf

The standard installation package for Fuse 7.11 on Karaf is available for download from the Red Hat Customer Portal. It installs the standard assembly of the Karaf container, and provides the full Fuse technology stack.

Prerequisites

Procedure

  1. Unpack the downloaded .zip archive file for Fuse on Apache Karaf to a convenient location on your file system, FUSE_INSTALL.
  2. Add an administrator user to the Fuse runtime.

    1. Open the FUSE_INSTALL/etc/users.properties file in a text editor.
    2. Delete the # character at the start of the line that starts with #admin = admin.
    3. Delete the # character at the start of the line that starts with #_g_\:admingroup.
    4. Customize the username, USERNAME, and password, PASSWORD, of the user entry, so that you have a user entry and an admin group entry like the following (on consecutive lines):

      USERNAME = PASSWORD,_g_:admingroup
      _g_\:admingroup = group,admin,manager,viewer,systembundles,ssh
    5. Save the etc/users.properties file.
  3. Run the CodeReady Studio installer as follows:

    java -jar DOWNLOAD_LOCATION/codereadystudio-12.21.3.GA-installer-standalone.jar
  4. During installation:

    1. Accept the terms and conditions.
    2. Choose your preferred installation path.
    3. Select the Java 8 JVM.
    4. At the Select Platforms and Servers step, configure the Fuse on Karaf runtime by clicking Add and browsing to the location of the FUSE_INSTALL directory.
    5. At the Select Additional Features to Install step, select Red Hat Fuse Tooling.
  5. CodeReady Studio starts up. When the Searching for runtimes dialog appears, click OK to create the Fuse on Karaf runtime.
  6. (Optional) In order to use Apache Maven from the command line, you need to install and configure Maven as described in Setting up Maven locally).

    Note

    If you are using CodeReady Studio exclusively, it is not strictly necessary to install Maven, because CodeReady Studio has Maven pre-installed and configured for you. However, if you plan to invoke Maven from the command line, it is necessary to perform this step.

1.3. Building your first Fuse application on Karaf

This set of instructions assists you in building your first Fuse application on Karaf.

Prerequisites

Procedure

  1. In CodeReady Studio, create a new project, as follows:

    1. Select File→New→Fuse Integration Project.
    2. Enter fuse-camel-cbr in the Project Name field.
    3. Click Next.
    4. In the Select a Target Environment pane, choose the following settings:

      • Select Standalone as the deployment platform.
      • Select Karaf/Fuse on Karaf as the runtime environment and use the Runtime (optional) dropdown menu to select the fuse-karaf-7.11.1.fuse-7_11_1-00013-redhat-00003 Runtime server as the target runtime.
    5. After selecting the target runtime, the Camel Version is automatically selected for you and the field is grayed out.
    6. Click Next.
    7. In the Advanced Project Setup pane, select the Beginner→Content Based Router - Blueprint DSL template.
    8. Click Finish.
    9. If prompted to open the associated Fuse Integration perspective, click Yes.
    10. Wait while CodeReady Studio downloads required artifacts and builds the project in the background.

      Important

      If this is the first time you are building a Fuse project in CodeReady Studio, it will take several minutes for the wizard to finish generating the project, as it downloads dependencies from remote Maven repositories. Do not attempt to interrupt the wizard or close CodeReady Studio while the project is building in the background.

  2. Deploy the project to the server, as follows:

    1. In the Servers view (bottom left corner of the Fuse Integration perspective), if the server is not already started, select the fuse-karaf-7.11.1.fuse-7_11_1-00013-redhat-00003 Runtime Server server and click the green arrow to start it.

      Note

      If you see the dialog, Warning: The authenticity of host 'localhost' can’t be established., click Yes to connect to the server and access the Karaf console.

    2. Wait until you see a message like the following in the Console view:

      Karaf started in 1s. Bundle stats: 12 active, 12 total
    3. After the server has started, switch back to the Servers view, right-click on the server and select Add and Remove from the context menu.
    4. In the Add and Remove dialog, select the fuse-camel-cbr project and click the Add > button.
    5. Click Finish.
    6. You can check whether the project’s OSGi bundle has started up by going to the Terminal view and entering bundle:list | tail. You should see some output like the following:

      ...
      228 │ Active │  80 │ 1.0.0.201505202023          │ org.osgi:org.osgi.service.j
      232 │ Active │  80 │ 1.0.0.SNAPSHOT              │ Fuse CBR Quickstart
      Note

      As soon as the Camel route starts up, it will create a directory, work/cbr/input, in your Fuse installation (not in the fuse-camel-cbr project).

  3. Copy the files you find in the project’s src/main/data directory to the FUSE_INSTALL/work/cbr/input directory. You can do this in your system file browser (outside of Eclipse).
  4. Wait a few moments and then look in the FUSE_INSTALL/work/cbr/output directory to see the same files organized by country:

    1. order1.xml in work/cbr/output/others
    2. order2.xml and order4.xml in work/cbr/output/uk
    3. order3.xml and order5.xml in work/cbr/output/us
  5. Undeploy the project, as follows:

    1. In the Servers view, select the Red Hat Fuse 7+ Runtime Server server.
    2. Right-click on the server and select Add and Remove from the context menu.
    3. In the Add and Remove dialog, select your fuse-camel-cbr project and click the < Remove button.
    4. Click Finish.