Getting Started
Get started quickly with Red Hat Fuse!
Abstract
Chapter 1. Getting Started Dashboard
1.1. Alternatives for getting started with Fuse standalone
The following dashboard shows alternative paths for getting started with Fuse standalone, depending on which container type you prefer:
1.2. Overview of the Fuse containers
To help you choose the right container for your project, the following sections give a brief overview of each container type.
1.2.1. JBoss EAP
JBoss Enterprise Application Platform (EAP), based on Jakarta EE (previously, Java EE) technology from the Eclipse Foundation, was originally created to address the use cases for developing enterprise applications. Characterized by well-defined patterns for implementing services and standardized Java APIs (for accessing services such as persistence, messaging, security, and so on), in recent years this technology has evolved to be more lightweight, with the introduction of CDI for dependency injection and simplified annotations for enterprise Java beans.
Distinctive features of this container technology are:
- Particularly suited to running in standalone mode.
- Many standard services (for example, persistence, messaging, security, and so on) pre-configured and provided out of the box.
- Application WARs typically small and lightweight (since many dependencies are pre-installed in the container).
- Standardized, backward-compatible Java APIs.
1.2.2. Apache 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.3. Spring Boot
Spring Boot is a recent evolution of the well-known Spring container. A distinctive quality of the Spring Boot container is that container functionality is divided up into small chunks, which can be deployed independently. This enables you to deploy a container with a small footprint, specialized for a particular kind of service, and this happens to be exactly what you need to fit the paradigm of a microservices architecture.
Distinctive features of this container technology are:
- Particularly suited to running on a scalable cloud platform (Kubernetes and OpenShift).
- Small footprint (ideal for microservices architecture).
- Optimized for convention over configuration.
- No application server required. You can run a Spring Boot application Jar directly in a JVM.
Chapter 2. Getting Started with Spring Boot
2.1. Overview of the circuit breaker booster
The Netflix/Hystrix circuit breaker component enables distributed applications to cope with interruptions to network connectivity and temporary unavailability of backend services. The basic idea of the circuit breaker pattern is that the loss of a dependent service is detected automatically and an alternative behavior can be programmed, in case the backend service is temporarily unavailable.
The Fuse circuit breaker booster consists of two related services:
- A name service, which returns a name to greet, and
-
A greetings service, which invokes the name service to get a name and then returns the string,
Hello, NAME.
In this demonstration, the Hystrix circuit breaker is inserted between the greetings service and the name service. If the name service becomes unavailable, the greetings service can fall back to an alternative behavior and respond to the client immediately, instead of blocking while it waits for the name service to restart.
2.2. Prerequisites
To build and run the booster demonstration, install the following prerequisites:
- A supported version of the Java Developer Kit (JDK). See the Supported Configurations page for details.
- Apache Maven 3.3.x or later. See the Maven Download page. To learn more about Maven, see Appendix A, Preparing to use Maven.
2.3. Generate the booster project
To generate the circuit breaker booster project, perform the following steps:
- Navigate to https://developers.redhat.com/launch.
- Click LAUNCH YOUR PROJECT.
- The launcher wizard prompts you to log in to your Red Hat account. Click the Log in or register button to log in.
- On the Deployment type page, click I will build and run locally.
- On the Mission page, select the Circuit Breaker mission and click Next.
- On the Runtime page, select the Fuse runtime (not the Spring Boot runtime) and click Next.
- On the Project Info page, select the 7.0.0 GA version from the Runtime Version dropdown menu. Accept the default settings for the other fields on this page.
- Click Next.
- On the Review Summary page, click Download as ZIP File to download the generated project.
- After downloading the ZIP file, use an archive utility to extract the generated project to a convenient location on your local filesystem.
2.4. Build and run the booster
To build and run the booster project, perform the following steps:
Open a shell prompt and build the project from the command line, using Maven:
cd booster-circuit-breaker-spring-boot mvn clean package
Open a new shell prompt and start the name service, as follows:
cd name-service mvn spring-boot:run -DskipTests -Dserver.port=8081
As Spring Boot starts up, you should see some output like the following:
... 2017-12-08 15:44:24.223 INFO 22758 --- [ main] o.a.camel.spring.SpringCamelContext : Total 1 routes, of which 1 are started 2017-12-08 15:44:24.227 INFO 22758 --- [ main] o.a.camel.spring.SpringCamelContext : Apache Camel 2.20.0 (CamelContext: camel-1) started in 0.776 seconds 2017-12-08 15:44:24.234 INFO 22758 --- [ main] org.jboss.fuse.boosters.cb.Application : Started Application in 4.137 seconds (JVM running for 4.744)
Open a new shell prompt and start the greetings service, as follows:
cd greetings-service mvn spring-boot:run -DskipTests
As Spring Boot starts up, you should see some output like the following:
... 2017-12-08 15:46:58.521 INFO 22887 --- [ main] o.a.c.c.s.CamelHttpTransportServlet : Initialized CamelHttpTransportServlet[name=CamelServlet, contextPath=] 2017-12-08 15:46:58.524 INFO 22887 --- [ main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http) 2017-12-08 15:46:58.536 INFO 22887 --- [ main] org.jboss.fuse.boosters.cb.Application : Started Application in 6.263 seconds (JVM running for 6.819)
The greetings service exposes a REST endpoint at the URL,
http://localhost:8080/camel/greetings. You can invoke the REST endpoint either from a Web browser or from a shell prompt, using thecurlcommand, as follows:$ curl http://localhost:8080/camel/greetings {"greetings":"Hello, Jacopo"}- To demonstrate the circuit breaker functionality provided by Camel Hystrix, kill the backend name service by typing Ctrl-C in the window of the shell prompt where the name service is running.
Now that the name service is unavailable, the circuit breaker kicks in to prevent the greetings service from hanging when it is invoked. Invoke the greetings REST endpoint using the
curlcommand, as follows:$ curl http://localhost:8080/camel/greetings {"greetings":"Hello, default fallback"}The log in the window where the greetings service is running shows the following sequence of messages:
2017-12-08 16:38:30.483 INFO 23579 --- [-CamelHystrix-2] route2 : Try to call name Service 2017-12-08 16:38:30.488 INFO 23579 --- [-CamelHystrix-2] o.a.c.httpclient.HttpMethodDirector : I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) 2017-12-08 16:38:30.488 INFO 23579 --- [-CamelHystrix-2] o.a.c.httpclient.HttpMethodDirector : Retrying request 2017-12-08 16:38:30.489 INFO 23579 --- [-CamelHystrix-2] o.a.c.httpclient.HttpMethodDirector : I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) 2017-12-08 16:38:30.489 INFO 23579 --- [-CamelHystrix-2] o.a.c.httpclient.HttpMethodDirector : Retrying request 2017-12-08 16:38:30.489 INFO 23579 --- [-CamelHystrix-2] o.a.c.httpclient.HttpMethodDirector : I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) 2017-12-08 16:38:30.489 INFO 23579 --- [-CamelHystrix-2] o.a.c.httpclient.HttpMethodDirector : Retrying request 2017-12-08 16:38:30.495 INFO 23579 --- [-CamelHystrix-2] route2 : We are falling back!!!!
-
For more information about this example, visit the Circuit Breaker Mission page at http://localhost:8080/ (while the
greetings-serviceis running). This page provides a link to the Hystrix dashboard, which monitors the state of the circuit breaker.
Chapter 3. Getting Started with Apache Karaf
3.1. Log in to the Customer Portal
Before you can download the required packages, you need an account on Red Hat’s Customer Portal which has a Red Hat Fuse subscription. Using this account, log in to the portal at https://access.redhat.com/login.
3.2. Download the required packages
Click each of the Download buttons to get the required packages from the Customer Portal:
3.3. Install and configure Fuse on Apache Karaf
To install and configure Fuse on Apache Karaf, perform the following steps:
-
Unpack the downloaded
.ziparchive file for Fuse on Apache Karaf to a convenient location on your file system,FUSE_INSTALL. Add an administrator user to the Fuse runtime.
-
Open the
FUSE_INSTALL/etc/users.propertiesfile in a text editor. -
Delete the
#character at the start of the line that starts with#admin = admin. -
Delete the
#character at the start of the line that starts with#g\:admingroup. 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
-
Save the
etc/users.propertiesfile.
-
Open the
3.4. Set up your development environment
To set up your development environment, perform the following steps:
Run the Developer Studio installer, as follows:
java -jar DOWNLOAD_LOCATION/devstudio-11.3.0.GA-installer-standalone.jar
During installation:
- Accept the terms and conditions.
- Choose your preferred installation path.
- Select the Java 8 JVM.
-
At the Select Platforms and Servers step, configure the Fuse on Karaf runtime by clicking Add and browsing to the location of the
FUSE_INSTALLdirectory (see Section 3.3, “Install and configure Fuse on Apache Karaf”). - At the Select Additional Features to Install step, select JBoss Fuse Tooling.
- Developer Studio starts up. When the Searching for runtimes dialog appears, click OK to create the Fuse on Karaf runtime.
(Optional) In order to use Apache Maven from the command line, you need to install and configure Maven as described in Appendix A, Preparing to use Maven.
NoteIf you are using Developer Studio exclusively, it is not strictly necessary to install Maven, because Developer Studio has Maven pre-installed and configured for you. But if you plan to invoke Maven from the command line, it is necessary to perform this step.
3.5. Build your first application
To build your first application with Fuse on JBoss EAP, perform the following steps:
In Developer Studio, create a new project, as follows:
- Select File→New→Fuse Integration Project.
-
Enter
fuse-camel-cbrin the Project Name field. Click Next. -
Select the
Red Hat Fuse 7.0 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 Use a predefined template.
- Select the Red Hat Fuse→Beginner→Content Based Router template.
-
Make sure that the selected project type is
Blueprint DSL. - Click Finish.
- If prompted to open the associated Fuse Integration perspective, click Yes.
Wait for a couple of minutes, while Developer Studio downloads required artifacts and builds the project in the background.
NoteIf this is the first time you are building a Fuse project in Developer Studio, it might take several minutes for the wizard to finish generating the project, as it downloads dependencies from remote Maven repositories.
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
Red Hat Fuse 7.0 Runtimeserver and click the green arrow to start it. Wait until you see a message like the following in the Console view:
Karaf started in 5s. Bundle stats: 229 active, 229 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 │ 1.0.0.201505202023 │ org.osgi:org.osgi.service.j 232 │ Active │ 80 │ 1.0.0.SNAPSHOT │ Fuse CBR Quickstart
NoteIf 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.
-
In the Servers view (bottom left corner of the Fuse Integration perspective), if the server is not already started, select the
3.5.1. Verify the project
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).
Now you can test your Camel route and see it in action.
Copy the files you find in the project’s fuse-camel-cbr/src/main/data directory (under the Eclipse workspace directory) to the newly created work/cbr/input directory. You can do this in your system file browser (outside of Eclipse).
Wait a few moments and you will find the same files organized by country under the work/cbr/output directory:
-
order1.xmlinwork/cbr/output/others -
order2.xmlandorder4.xmlinwork/cbr/output/uk -
order3.xmlandorder5.xmlinwork/cbr/output/us
Enter log:display in the Karaf console (Terminal view) to see the application output in the log, for example:
... 15:46:14.859 INFO [Camel (cbr-example-context) thread #3 - file://work/cbr/input] Receiving order order2.xml 15:46:14.888 INFO [Camel (cbr-example-context) thread #3 - file://work/cbr/input] Sending order order2.xml to the UK 15:46:14.891 INFO [Camel (cbr-example-context) thread #3 - file://work/cbr/input] Done processing order2.xml 15:46:14.895 INFO [Camel (cbr-example-context) thread #3 - file://work/cbr/input] Receiving order order3.xml
3.5.2. Undeploy the project
Undeploy the project, as follows:
-
In the Servers view, select the
Red Hat Fuse 7.0 Runtimeserver. - 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.
Chapter 4. Getting Started with Fuse on JBoss Enterprise Application Platform
4.1. Log in to the Customer Portal
Before you can download the required packages, you need an account on Red Hat’s Customer Portal which has a Red Hat Fuse subscription. Using this account, log in to the portal at https://access.redhat.com/login.
4.2. Download the required packages
Click each of the Download buttons to get the required packages from the Customer Portal:
4.3. Install and configure Fuse on JBoss EAP
To install and configure Fuse on JBoss EAP, perform the following steps:
Run the JBoss EAP installer from a shell prompt, as follows:
java -jar DOWNLOAD_LOCATION/jboss-eap-7.1.0-installer.jar
During installation:
- Accept the terms and conditions.
-
Choose your preferred installation path,
EAP_INSTALL, for the JBoss EAP runtime. - Create an administrative user and make a careful note of these administrative user credentials for later.
- You can accept the default settings on the remaining screens.
-
Open a shell prompt and change directory to
EAP_INSTALL. From the
EAP_INSTALLdirectory, run the Fuse on EAP installer, as follows:java -jar DOWNLOAD_LOCATION/jboss-fuse-eap-installer-7.0.0.000041-fuse-000001-redhat-1.jar
4.4. Set up your development environment
To set up your development environment, perform the following steps:
Run the Developer Studio installer, as follows:
java -jar DOWNLOAD_LOCATION/devstudio-11.3.0.GA-installer-standalone.jar
During installation:
- Accept the terms and conditions.
- Choose your preferred installation path.
- Select the Java 8 JVM.
-
At the Select Platforms and Servers step, configure the JBoss EAP runtime by clicking Add and browsing to the location of the
EAP_INSTALLdirectory (see Section 4.3, “Install and configure Fuse on JBoss EAP”). - At the Select Additional Features to Install step, select JBoss Fuse Tooling.
- Developer Studio starts up. When the Searching for runtimes dialog appears, click OK to create the JBoss EAP runtime.
(Optional) In order to use Apache Maven from the command line, you need to install and configure Maven as described in Appendix A, Preparing to use Maven.
NoteIf you are using Developer Studio exclusively, it is not strictly necessary to install Maven, because Developer Studio has Maven pre-installed and configured for you. But if you plan to invoke Maven from the command line, it is necessary to perform this step.
4.5. Build your first application
To build your first application with Fuse on JBoss EAP, perform the following steps:
In Developer Studio, create a new project, as follows:
- Select File→New→Fuse Integration Project.
-
Enter
eap-camelin the Project Name field. Click Next. -
Select the
Red Hat JBoss EAP 7.1 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 Use a predefined template.
- Select the Fuse on EAP→Medium→Spring on EAP template.
- Click Finish.
- If prompted to open the associated Fuse Integration perspective, click Yes.
- Wait for a couple of minutes, while Developer Studio downloads required artifacts and builds the project 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
Red Hat JBoss EAP 7.1 Runtimeserver and click the green arrow to start it. Wait until you see a message like the following in the Console view:
12:02:25,467 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss EAP 6.4.0.GA (AS 7.5.0.Final-redhat-21) started in 9494ms - Started 480 of 518 services (69 services are lazy, passive or on-demand)
- 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
eap-camelproject and click the Add > button. - Click Finish.
-
In the Servers view (bottom left corner of the Fuse Integration perspective), if the server is not already started, select the
Verify that the project is working, as follows:
-
Browse to the following URL to access the service running in the
eap-camelproject: http://localhost:8080/camel-test-spring?name=Kermit -
The browser window should show the response
Hello Kermit.
-
Browse to the following URL to access the service running in the
Undeploy the project, as follows:
-
In the Servers view, select the
Red Hat JBoss EAP 7.1 Runtimeserver. - Right-click on the server and select Add and Remove from the context menu.
-
In the Add and Remove dialog, select your
eap-camelproject and click the < Remove button. - Click Finish.
-
In the Servers view, select the
Appendix A. Preparing to use Maven
A.1. Overview
This section gives a brief overview of how to prepare Maven for building Red Hat JBoss Fuse projects and introduces the concept of Maven coordinates, which are used to locate Maven artifacts.
A.2. Prerequisites
In order to build a project using Maven, you must have the following prerequisites:
- Maven installation — Maven is a free, open source build tool from Apache. You can download the latest version from the Maven download page.
Network connection — whilst performing a build, Maven dynamically searches external repositories and downloads the required artifacts on the fly. By default, Maven looks for repositories that are accessed over the Internet. You can change this behavior so that Maven will prefer searching repositories that are on a local network.
NoteMaven can run in an offline mode. In offline mode Maven only looks for artifacts in its local repository.
A.3. Adding the Red Hat Maven repositories
In order to access artifacts from the Red Hat Maven repositories, you need to add them to Maven’s settings.xml file. Maven looks for your settings.xml file in the .m2 directory of the user’s home directory. If there is not a user specified settings.xml file, Maven will use the system-level settings.xml file at M2_HOME/conf/settings.xml.
To add the Red Hat repositories to Maven’s list of repositories, you can either create a new .m2/settings.xml file or modify the system-level settings. In the settings.xml file, add repository elements for the Red Hat repositories as shown in Adding the Red Hat JBoss Fuse Repositories to Maven.
Adding the Red Hat JBoss Fuse Repositories to Maven
<?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>
A.4. Artifacts
The basic building block in the Maven build system is an artifact. The output of an artifact, after performing a Maven build, is typically an archive, such as a JAR or a WAR.
A.5. Maven coordinates
A key aspect of Maven functionality is the ability to locate artifacts and manage the dependencies between them. Maven defines the location of an artifact using the system of Maven coordinates, which uniquely define the location of a particular artifact. A basic coordinate tuple has the form, {groupId, artifactId, version}. Sometimes Maven augments the basic set of coordinates with the additional coordinates, packaging and classifier. A tuple can be written with the basic coordinates, or with the additional packaging coordinate, or with the addition of both the packaging and classifier coordinates, as follows:
groupdId:artifactId:version groupdId:artifactId:packaging:version groupdId:artifactId:packaging:classifier:version
Each coordinate can be explained as follows:
- groupdId
-
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,
org.fusesource.example. - artifactId
- Defines the artifact name (relative to the group ID).
- version
-
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 of1.0-SNAPSHOTis the alphanumeric substring,0-SNAPSHOT). - packaging
-
Defines the packaged entity that is produced when you build the project. For OSGi projects, the packaging is
bundle. The default value isjar. - classifier
- Enables you to distinguish between artifacts that were built from the same POM, but have different content.
The group ID, artifact ID, packaging, and version are defined by the corresponding elements in an artifact’s POM file. For example:
<project ... > ... <groupId>org.fusesource.example</groupId> <artifactId>bundle-demo</artifactId> <packaging>bundle</packaging> <version>1.0-SNAPSHOT</version> ... </project>
For example, to define a dependency on the preceding artifact, you could add the following dependency element to a POM:
<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 type element.







