Camel JBang

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

The camel-jbang is available from Camel 3.12 and newer versions.

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 CamelJBang:

jbang app install CamelJBang@apache/camel

Using Camel JBang

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

jbang CamelJBang@apache/camel [command]

Note: 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.

Troubleshooting

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

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

Using a specific Camel version

You can specify which Camel version to run as shown:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel [command]

Running Routes

You can run Camel routes from any of the supported DSLs in Camel such as YAML, XML, Java, Groovy.

For example to run YAML-based routes which also refer to Kamelets in the catalog. In order to do so, write a YAML-based file with the route, the steps and the to destination for the route. The following example, shows a route that uses the Timer Source Kamelet to produce messages every second. The body of the messages will be logged to the standard output. Subsequently, they will be sent to a AMQP 1.0 compliant broker using the JMS AMQ 1.0 Sink Kamelet.

- route:
    id: "hello"
    from:
      uri: "kamelet:timer-source"
      parameters:
        period: 1000
        message: "Hello Camel JBang"
    steps:
      - log: "${body}"
      - to:
          uri: "kamelet:jms-amqp-10-sink"
          parameters:
            remoteURI: amqp://localhost:61616
            destinationName: test-queue

Execute the following command to run this route:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run jms-amqp-10-sink-binding.yaml

it is necessary to have a AMQP 1.0 broker, such as Apache Artemis, running locally and listening on port 61616. Adjust the route accordingly if using a different address for the broker.

Running Routes from multiple files

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

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run one.yaml two.yaml

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

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run one.yaml hello.java

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

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run *.yaml

Or you can run all files starting with foo*

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run foo*

The run goal can also detect files that are properties.

Live reload

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

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run jms-amqp-10-sink-binding.yaml --reload

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:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run run github:apache:camel-k:examples/languages/routes.yaml

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.

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run --local-kamelet-dir=/path/to/local/kamelets earthquake.yaml

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:

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 CamelJBang:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run joke.yaml

Using platform-http component

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

- from:
    uri: "platform-http:/hello"
    steps:
      - set-body:
          constant: "Hello World"

Can be run with

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel run server.yaml

And you can call the HTTP service with:

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

Debugging

You can debug both CamelJBang@apache/camel and your integration scripts by making use of the --debug flag provided by JBang:

jbang --debug CamelJBang@apache/camel 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.

Search

You can use the CLI to search for kamelets, components, languages and miscellaneous components (others). Running the following command will present a list of items that can be searched:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel search --help

For example, to search for kamelets named jms, you can use:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel search kamelets --search-term=jms

To list all the kamelets, just run the command without any search term:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel search kamelets

The same behavior also works for all the other search commands. The table below lists all search commands available at the moment:

Command	Description
kamelets	search for kamelets
components	search for components
languages	search for languages
others	search for miscellaneous components

Command

Description

kamelets

search for kamelets

components

search for components

languages

search for languages

others

search for miscellaneous components

Init Kamelets

The init sub-command can be used to simplify creating Kamelets. Through this command, it is possible to create new Kamelets through pre-configured templates. It works in two steps: first it is necessary to bootstrap the Kamelet by creating a properties file with the parameters necessary to create the Kamelet. Once the properties file is correctly set, then it is possible to create a pre-filled Kamelet by processing that properties file.

To bootstrap the Kamelet run:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel  init kamelet --bootstrap

This will create a sub-directory called work in the current directory with a properties file named init-template.properties inside it.

The keys of the properties file are commented with the details about what need to be filled in order to generate the Kamelet. If a value is missing, it will be ignored when generating the Kamelet and will need to be filled in manually later.

After you have filled the values, you can generate the Kamelet using:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel init kamelet --properties-path work/init-template.properties

Running this command will create a new file in the work directory. The name of the generated file is determined by the kameletMetadataName property in the properties file. As such, parsing the default properties file would generate a file named my-sample-sink.kamelet.yaml in the directory.

After the file is generated, it may still need to require final adjustments, such as correctly setting the name, the icon and other requirements for official Kamelets. Please consult the Kamelet development documentation for updated details.

Init Bindings

The init sub-command can also be used to simplify creating Kamelets bindings. Through this command, it is possible to create new bindings through pre-configured templates. Use the --kamelet option (you can list the available ones using the search command) to set the Kamelet to generate the binding for.

To execute this feature run:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel init binding --destination /path/to/destination/directory/ --kamelet sftp-source

This will create a new sample YAML binding file that can be modified and used in Camel K.

You can also generate bindings that can be run by CamelJBang or Camel Core, but setting the --project option:

jbang -Dcamel.jbang.version=3.14.0 CamelJBang@apache/camel init binding --destination /path/to/destination/directory/ --kamelet sftp-source --project core