Getting Started with Fuse on Apache Karaf
Get started quickly with Red Hat Fuse on Karaf
To get started with Fuse, you need to download and install the files for your Apache Karaf container. The information and instructions here guide you in installing, developing, and building your first Fuse application.
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
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.
1.2. Installing the Java runtimes
In order to run Fuse Tooling with the latest version of CodeReady Studio, you need both Java 8 and Java 11 installed on your local machine. The Java 8 JVM is required for launching applications targeting Fuse on Karaf and the Java 11 JVM is required for running CodeReady Studio.
To install the full Java 8 SDK on RHEL 8, enter the following command:
sudo yum install java-1.8.0-openjdk-devel
To install the full Java 11 SDK on RHEL 8, enter the following command:
sudo yum install java-11-openjdk-devel
In both cases you must install the full SDK (packages with the
-devel suffix). A plain Java Runtime Environment (JRE) is not sufficient.
1.3. Installing Fuse on Karaf
The standard installation package for Fuse 7.9 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.
- You must have installed both the Java 8 SDK and the Java 11 SDK, as described in Section 1.2, “Installing the Java runtimes”.
- You need a full-subscription account on the Red Hat Customer Portal.
- You must be logged into the customer portal.
- You must have downloaded the CodeReady Studio installer.
- You must have downloaded the Fuse on Karaf installer.
Unpack the downloaded
.ziparchive file for Fuse on Apache Karaf to a convenient location on your file system,
Add an administrator user to the Fuse runtime.
FUSE_INSTALL/etc/users.propertiesfile in a text editor.
#character at the start of the line that starts with
#admin = admin.
#character at the start of the line that starts with
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
- Open the
Run the CodeReady Studio installer as follows:
java -jar DOWNLOAD_LOCATION/codereadystudio-12.21.0.GA-installer-standalone.jar
- Accept the terms and conditions.
- Choose your preferred installation path.
- Select the Java 11 JVM.
At the Select Platforms and Servers step, configure the Fuse on Karaf runtime by clicking Add and browsing to the location of the
- At the Select Additional Features to Install step, select Red Hat Fuse Tooling.
- CodeReady Studio starts up. When the Searching for runtimes dialog appears, click OK to create the Fuse on Karaf runtime.
Switch the default JVM for new projects from Java 11 to Java 8 (required for launching Fuse on Karaf applications).
- Drill down to Window→Preferences→Java→Installed JREs.
- In the Installed JREs pane, click Add to open the Add JRE wizard.
- In the JRE Type dialog, select Standard VM and click Next.
- In the JRE Definition dialog, paste the absolute path to the home directory of your Java 8 installation into the JRE home field. The other fields in the dialog will automatically be filled in. Click Finish.
- In the Installed JREs pane, select the Java 8 runtime and then click Apply.
- Drill down to Window→Preferences→Java→Compiler. Under JDK Compliance, set the Compiler Compliance level to 1.8. Click Apply and Close.
(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.4. Building your first Fuse application on Karaf
This set of instructions assists you in building your first Fuse application on Karaf.
In CodeReady Studio, create a new project, as follows:
- Select File→New→Fuse Integration Project.
fuse-camel-cbrin the Project Name field.
- Click Next.
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.9.0.fuse-790071-redhat-00001 Runtimeserver as the target runtime.
- After selecting the target runtime, the Camel Version is automatically selected for you and the field is grayed out.
- Click Next.
- In the Advanced Project Setup pane, select the Beginner→Content Based Router - Blueprint DSL template.
- Click Finish.
- If prompted to open the associated Fuse Integration perspective, click Yes.
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.
Deploy the project to the server, as follows:
In the Servers view (bottom left corner of the Fuse Integration perspective), if the server is not already started, select the
fuse-karaf-7.9.0.fuse-790071-redhat-00001 Runtime Serverserver 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.
Wait until you see a message like the following in the Console view:
Karaf started in 1s. Bundle stats: 12 active, 12 total
- 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.
In the Add and Remove dialog, select the
fuse-camel-cbrproject and click the Add > button.
- Click Finish.
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 │ 18.104.22.168505202023 │ org.osgi:org.osgi.service.j 232 │ Active │ 80 │ 1.0.0.SNAPSHOT │ Fuse CBR QuickstartNote
As soon as the Camel route starts up, it will create a directory,
work/cbr/input, in your Fuse installation (not in the
Copy the files you find in the project’s
src/main/datadirectory to the
FUSE_INSTALL/work/cbr/inputdirectory. You can do this in your system file browser (outside of Eclipse).
Wait a few moments and then look in the
FUSE_INSTALL/work/cbr/outputdirectory to see the same files organized by country:
Undeploy the project, as follows:
In the Servers view, select the
Red Hat Fuse 7+ Runtime Serverserver.
- Right-click on the server and select Add and Remove from the context menu.
In the Add and Remove dialog, select your
fuse-camel-cbrproject and click the < Remove button.
- Click Finish.
- In the Servers view, select the
Chapter 2. Setting up Maven locally
Typical Fuse application development uses Maven to build and manage projects.
The following topics describe how to set up Maven locally:
2.1. Preparing to set up Maven
Maven is a free, open source, build tool from Apache. Typically, you use Maven to build Fuse applications.
- Download the latest version of Maven from the Maven download page.
Ensure that your system is connected to the Internet.
While building a project, the default behavior is that Maven searches external repositories and downloads the required artifacts. Maven looks for repositories that are accessible over the Internet.
You can change this behavior so that Maven searches only repositories that are on a local network. That is, Maven can run in an offline mode. In offline mode, Maven looks for artifacts in its local repository. See Section 2.3, “Using local Maven repositories”.
2.2. Adding Red Hat repositories to Maven
To access artifacts that are in Red Hat Maven repositories, you need to add those repositories to Maven’s
settings.xml file. Maven looks for the
settings.xml file in the
.m2 directory of the user’s home directory. If there is not a user specified
settings.xml file, Maven uses the system-level
settings.xml file at
You know the location of the
settings.xml file in which you want to add the Red Hat repositories.
settings.xml file, add
repository elements for the Red Hat repositories as shown in this example:
<?xml version="1.0"?> <settings> <profiles> <profile> <id>extra-repos</id> <activation> <activeByDefault>true</activeByDefault> </activation> <repositories> <repository> <id>redhat-ga-repository</id> <url>https://maven.repository.redhat.com/ga</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> <repository> <id>redhat-ea-repository</id> <url>https://maven.repository.redhat.com/earlyaccess/all</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> <repository> <id>jboss-public</id> <name>JBoss Public Repository Group</name> <url>https://repository.jboss.org/nexus/content/groups/public/</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>redhat-ga-repository</id> <url>https://maven.repository.redhat.com/ga</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> <pluginRepository> <id>redhat-ea-repository</id> <url>https://maven.repository.redhat.com/earlyaccess/all</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> <pluginRepository> <id>jboss-public</id> <name>JBoss Public Repository Group</name> <url>https://repository.jboss.org/nexus/content/groups/public</url> </pluginRepository> </pluginRepositories> </profile> </profiles> <activeProfiles> <activeProfile>extra-repos</activeProfile> </activeProfiles> </settings>
2.3. Using local Maven repositories
If you are running a container without an Internet connection, and you need to deploy an application that has dependencies that are not available offline, you can use the Maven dependency plug-in to download the application’s dependencies into a Maven offline repository. You can then distribute this customized Maven offline repository to machines that do not have an Internet connection.
In the project directory that contains the
pom.xmlfile, download a repository for a Maven project by running a command such as the following:
mvn org.apache.maven.plugins:maven-dependency-plugin:3.1.0:go-offline -Dmaven.repo.local=/tmp/my-project
In this example, Maven dependencies and plug-ins that are required to build the project are downloaded to the
etc/org.ops4j.pax.url.mvn.cfgfile to set
org.ops4j.pax.url.mvn.offlineto true. This enables offline mode:
## # If set to true, no remote repository will be accessed when resolving artifacts # org.ops4j.pax.url.mvn.offline = true
- Distribute this customized Maven offline repository internally to any machines that do not have an Internet connection.
2.4. Setting Maven mirror using environmental variables or system properties
When running the applications you need access to the artifacts that are in the Red Hat Maven repositories. These repositories are added to Maven’s
settings.xml file. Maven checks the following locations for
- looks for the specified url
if not found looks for
if not found looks for
if not found looks for
if no location is found, empty
org.apache.maven.settings.Settingsinstance is created.
2.4.1. About Maven mirror
Maven uses a set of remote repositories to access the artifacts, which are currently not available in local repository. The list of repositories almost always contains Maven Central repository, but for Red Hat Fuse, it also contains Maven Red Hat repositories. In some cases where it is not possible or allowed to access different remote repositories, you can use a mechanism of Maven mirrors. A mirror replaces a particular repository URL with a different one, so all HTTP traffic when remote artifacts are being searched for can be directed to a single URL.
2.4.2. Adding Maven mirror to
To set the Maven mirror, add the following section to Maven’s
<mirror> <id>all</id> <mirrorOf>*</mirrorOf> <url>http://host:port/path</url> </mirror>
No mirror is used if the above section is not found in the
settings.xml file. To specify a global mirror without providing the XML configuration, you can use either system property or environmental variables.
2.4.3. Setting Maven mirror using environmental variable or system property
To set the Maven mirror using either environmental variable or system property, you can add:
Environmental variable called MAVEN_MIRROR_URL to
System property called mavenMirrorUrl to
2.4.4. Using Maven options to specify Maven mirror url
To use an alternate Maven mirror url, other than the one specified by environmental variables or system property, use the following maven options when running the application:
-DmavenMirrorUrl=http://mirror.net/repository. In this example, the <id> of the <mirror> is just a mirror.
2.5. About Maven artifacts and coordinates
In the Maven build system, the basic building block is an artifact. After a build, the output of an artifact is typically an archive, such as a JAR or WAR file.
A key aspect of Maven is the ability to locate artifacts and manage the dependencies between them. A Maven coordinate is a set of values that identifies the location of a particular artifact. A basic coordinate has three values in the following form:
Sometimes Maven augments a basic coordinate with a packaging value or with both a packaging value and a classifier value. A Maven coordinate can have any one of the following forms:
groupId:artifactId:version groupId:artifactId:packaging:version groupId:artifactId:packaging:classifier:version
Here are descriptions of the values:
Defines a scope for the name of the artifact. You would typically use all or part of a package name as a group ID. For example,
- Defines the artifact name relative to the group ID.
Specifies the artifact’s version. A version number can have up to four parts:
n.n.n.n, where the last part of the version number can contain non-numeric characters. For example, the last part of
1.0-SNAPSHOTis the alphanumeric substring,
Defines the packaged entity that is produced when you build the project. For OSGi projects, the packaging is
bundle. The default value is
- Enables you to distinguish between artifacts that were built from the same POM, but have different content.
Elements in an artifact’s POM file define the artifact’s group ID, artifact ID, packaging, and version, as shown here:
<project ... > ... <groupId>org.fusesource.example</groupId> <artifactId>bundle-demo</artifactId> <packaging>bundle</packaging> <version>1.0-SNAPSHOT</version> ... </project>
To define a dependency on the preceding artifact, you would add the following
dependency element to a POM file:
<project ... > ... <dependencies> <dependency> <groupId>org.fusesource.example</groupId> <artifactId>bundle-demo</artifactId> <version>1.0-SNAPSHOT</version> </dependency> </dependencies> ... </project>
It is not necessary to specify the
bundle package type in the preceding dependency, because a bundle is just a particular kind of JAR file and
jar is the default Maven package type. If you do need to specify the packaging type explicitly in a dependency, however, you can use the