Camel JBang

A JBang-based Camel app for easily running Camel routes.

Installation

It is not necessary to install Camel JBang. However, if you prefer to do so, JBang makes it easy for us by providing an installation feature that works with GitHub. If you have JBang installed on your system, then you can run the following command to install Camel JBang:

jbang app install camel@apache/camel

Using Camel JBang

The Camel JBang supports multiple commands. Running the command below, will print all of them:

jbang camel@apache/camel --help
The first time you run this command, it may cause dependencies to be cached, therefore taking a few extra seconds to run.

All the commands support the --help and will display the appropriate help if that flag is provided.

Using a specific Camel version

You can specify which Camel version to run as shown:

jbang run -Dcamel.jbang.version=3.16.0 camel@apache/camel [command]

And you can also try bleeding edge development by using SNAPSHOT such as:

jbang run -Dcamel.jbang.version=3.17.0-SNAPSHOT camel@apache/camel [command]

Creating and running Camel routes

You can create a new basic routes with the init command.

For example to create an XML route you do:

camel init cheese.xml

Which creates the file cheese.xml with a sample route.

To run the file, you simply do:

camel run cheese.xml
You can create and run any of the supported DSLs in Camel such as YAML, XML, Java, Groovy.

To create a new .java integration, you simply do:

camel init foo.java

Running Routes from multiple files

You can run more than 1 file, for example to run two YAML files you can do:

camel run one.yaml two.yaml

You can also mix different DSLs such as yaml and Java:

camel run one.yaml hello.java

You can also use wildcards (i.e. *) to match multiple files, such as running all the yaml files:

camel run *.yaml

Or you can run all files starting with foo*

camel run foo*
The run goal can also detect files that are properties.

Dev mode with live reload

You can enable dev mode that comes with live reload of the route(s) when the source file is updated (saved), using the --dev options as shown:

camel run jms-amqp-10-sink-binding.yaml --dev

Then while the Camel application is running, you can update the YAML route and update when saving.

The live reload is meant for development purposes, and if you encounter problems with reloading such as JVM class loading issues, then you may need to restart the application.

Running routes hosted on GitHub

You can run a route that is hosted on GitHub using Camels github resource loader.

For example to run one of the Camel K examples you can do:

camel run github:apache:camel-k:examples/languages/routes.yaml

You can also use the https URL for GitHub. For example, you can browse the examples from a web-browser and then copy the URL from the browser window and run the example with Camel JBang:

camel run https://github.com/apache/camel-k/blob/main/examples/languages/routes.yaml

You can also use wildcards (i.e. *) to match multiple files, such as running all the groovy files:

camel run https://github.com/apache/camel-k/tree/main/examples/languages/*.groovy

Or you can run all files starting with rou*

camel run https://github.com/apache/camel-k/tree/main/examples/languages/rou*

Running routes from GitHub gists

Using gists from GitHub is a quick way to share small Camel routes that you can easily run.

For example to run a gist you simply do:

camel run https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92

A gist can contain one or more files, and Camel JBang will gather all relevant files, so a gist can contain multiple routes, properties files, Java beans, etc.

Downloading routes hosted on GitHub

We have made it easy for Camel JBang to download existing examples from GitHub to local disk, which allows for modifying the example and to run locally.

All you need to do is to copy the https link from the web browser. For example, you can download the dependency injection example by:

camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection

Then the files (not sub folders) are downloaded to the current directory. The example can then be run locally with:

camel run *

You can also run in dev mode, to hot-deploy on source code changes.

camel run * --dev

You can also download a single file, such as one of the Camel K examples:

camel init https://github.com/apache/camel-k/blob/main/examples/languages/simple.groovy

This is a groovy route, which you can run with (or use *):

camel run simple.groovy

Running local Kamelets

You can also use Camel JBang to try local Kamelets, without the need to publish them on GitHub or package them in a jar.

camel run --local-kamelet-dir=/path/to/local/kamelets earthquake.yaml

Downloading routes form GitHub gists

You can also download files from gists easily as shown:

camel init https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92

This will then download the files to local disk, which you can run afterwards:

camel run *

Running Camel K integrations or bindings

Camel also supports running Camel K integrations and binding files, which are in CRD format (Kubernetes Custom Resource Definitions).

For example a kamelet binding file named joke.yaml:

#!/usr/bin/env jbang camel@apache/camel run
apiVersion: camel.apache.org/v1alpha1
kind: KameletBinding
metadata:
  name: joke
spec:
  source:
    ref:
      kind: Kamelet
      apiVersion: camel.apache.org/v1
      name: chuck-norris-source
    properties:
      period: 2000
  sink:
    ref:
      kind: Kamelet
      apiVersion: camel.apache.org/v1
      name: log-sink
    properties:
      show-headers: false

Can be run with camel:

camel run joke.yaml

Run from clipboard

You can also run Camel routes directly from the OS clipboard. This allows to copy some code, and then quickly run this.

The syntax is

camel run clipboard.<extension>

Where <extension> is what kind of file the content of the clipboard is, such as java, xml, or yaml etc.

For example. you can copy this to your clipboard and then run it afterwards:

<route>
  <from uri="timer:foo"/>
  <log message="Hello World"/>
</route>
camel run clipboard.xml

Using platform-http component

When a route is started from platform-http then Camel JBang will automatically include a VertX HTTP server running on port 8080. For example the following route in a file named server.yaml:

#!/usr/bin/env jbang camel@apache/camel run
- from:
    uri: "platform-http:/hello"
    steps:
      - set-body:
          constant: "Hello World"

Can be run with

camel run server.yaml

And you can call the HTTP service with:

curl http://localhost:8080/hello
Hello World%

Using Java beans and processors

There is basic support for including regular Java source files together with Camel routes, and let Camel JBang runtime compile the Java source. This means you can include smaller utility classes, POJOs, Camel Processors and whatnot that the application needs.

The Java source files cannot use package names. This may change in the future.

Dependency Injection in Java classes

When running Camel applications with camel-jbang, then the runtime is camel-main based. This means there is no Spring Boot, or Quarkus available. However, we have added support for using annotation based dependency injection in Java classes.

Using Camel dependency injection

You can use the following Camel annotations (they work on all runtimes):

  • @BindToRegistry on class level to create an instance of the class and register in the Registry.

  • @BeanInject to dependency inject a bean on a class field.

  • @PropertyInject to inject a property placeholder. Such as a property defined in application.properties.

  • @BindToRegistry on a method to create a bean by invoking the method.

  • @Converter on class level to auto-register the type converters from the class.

Using Spring Boot dependency injection

You can use the following Spring Boot annotations:

  • @Component or @Service on class level to create an instance of the class and register in the Registry.

  • @Autowired to dependency inject a bean on a class field. @Qualifier can be used to specify the bean id.

  • @Value to inject a property placeholder. Such as a property defined in application.properties.

  • @Bean on a method to create a bean by invoking the method.

Using Quarkus injection

You can use the following Quarkus annotations:

  • @ApplicationScoped or @Singleton on class level to create an instance of the class and register in the Registry. @Named can be used to specify the bean id.

  • @Inject to dependency inject an bean on a class field. @Named can be used to specify the bean id.

  • @ConfigProperty to inject a property placeholder. Such as a property defined in application.properties.

  • @Produces on a method to create a bean by invoking the method. @Named can be used to specify the bean id.

Debugging

Java debugging

You can debug both Camel JBang and your integration scripts by making use of the --debug flag provided by JBang:

camel --debug run /path/to/integration.java
[jbang] Building jar...
Listening for transport dt_socket at address: 4004

As you can see the default listening port is 4004 but can be configured as described in JBang Debugging.

This is a standard Java debug socket. You can then use the IDE of your choice. For instance, see the generic documentation for IntelliJ, VS Code and Eclipse Desktop. You will surely want to add Processor to be able to put breakpoints hit during route execution (as opposed to route definition creation).

Camel debugging

The Camel debugger is available by default (the camel-debug component is automatically added to the classpath). By default, it can be reached through JMX at the URL service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi/camel.

You can then use the Integrated Development Environment (IDE) of your choice. For instance IntelliJ, VS Code or Eclipse Desktop.

A specific how-to is available for VS Code, see this video or this /blog/2022/05/start-camel-quarkus-application-with-camel-textual-debug-in-vscode/[blogpost].

Open API

Camel JBang allows to quickly expose an Open API service using contract first approach, where you have an existing OpenAPI specification file.

Then Camel JBang is able to bridge each API endpoints from the OpenAPI specification to a Camel route with the naming convention direct:<operationId>.

This make it quick to implement a Camel route for a given operation.

See the open-api example for more details.

Packaging as uber-jar

The Camel JBang application can be packaged as a standalone uber-jar without the need for JBang to run the application.

You simply do this by

camel package uber-jar

Which will generate camel-runner.jar as the output file. You can then run this JAR with Java that comes with everything included inside the .jar file.

You can run the JAR with Java as follows:

java -jar camel-runner.jar
Packaging as uber-jar does not support using Camel K modeline style configurations. It is better practice specifying configurations in external files such as application.properties.

Creating Projects

You can export your Camel JBang application to a traditional Java based project such as Spring Boot or Quarkus.

Create Quarkus Project

New implementation on the way

The create project command can be used to generate a Maven project. After running the integration with the run command create project will generate a Maven Quarkus project with some required dependencies that can be used as a starting point for complex integrations.

To execute this feature run:

jbang camel@apache/camel create project integration.java integration.yaml integration.xml

This command generates a folder named CamelJBang that contains the Quarkus project, in order to execute it the following command can be run:

cd CamelJBang
mvn compile quarkus:dev

The table below lists all the command line options configurable on the create project command:

Option Description

name

The name of the Camel application (artifactId and folder)

group-id

The group ID of the maven project

directory

Directory where the project will be created

quarkus-dependency

Comma separated list of camel-quarkus dependencies

quarkus-bom-version

Override quarkus bom version in pom.xml

Examples

jbang camel@apache/camel create project TimerRoute.java --quarkusDependencies=camel-quarkus-timer,camel-quarkus-log,camel-quarkus-yaml-dsl,camel-quarkus-http --name=TimerRouteProject
jbang camel@apache/camel create project KafkaRoute.java --quarkusDependencies=camel-quarkus-kafka,camel-quarkus-log --name=KafkaRouteProject

Troubleshooting

When using JBang then JBang stores state in ~/.jbang directory. This is also the location where JBang stores downloaded JARs.

Camel JBang also downloads needed dependencies while running. However, these dependencies are downloaded to ~/.groovy (downloaded via Groovy Grape).

So if you find problems with running Camel JBang using what is seems like an outdated JAR, then you can try to delete these directories, or parts of it.

Back to top