Camel JBang

Camel JBang provides shell completion for bash and zsh out of the box. To enable shell completion for Camel JBang, run:

To make it permanent, run:

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

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

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

Or you can run all files starting with foo*

And to run everything

Camel JBang is intended for flat-file-based projects, where you run small integrations. However, Camel JBang may be used as a tool for migrating existing Maven or Gradle based projects. To make the migration easier, then JBang can do best effort to run, export, or transform these projects.

For example, if you have a Maven-based project, you can execute

or for a Gradle project

Camel JBang will then scan in src/main/java and src/main/resources for files to include (recursive).

You can create Camel integrations that makes it possible for the user to quickly enter placeholder values from command prompt.

For example, given the following route:

Then if you run this with:

You will have an exception on startup about the missing value

However, you can then run in prompt mode as follows:

And Camel will now prompt in the terminal for you to enter values for the placeholders:

From the snippet above, Camel JBang had two prompts. First for the time which has a default value of 1000 so you can just press ENTER to accept the default value. And for you a value must be entered, and we entered Jack in this example.

You may want to use this for Camel prototypes where you want the user to be able to enter custom values quickly. Those values can of course be pre-configured in application.properties as well.

For very small Java routes then it is possible to provide the route as CLI argument, as shown below:

This is very limited as the CLI argument is a bit cumbersome to use than files.

From Camel 4.7 onwards the --code parameter can also refer to a .java source file, that are not wrapped in a public class which makes it possible to quickly try a prototype with some Camel java based routes such as the following stored in a file named quick.java:

Then you can run this route via:

You can also run dev mode when running Camel with --source-dir, such as:

This starts Camel where it will load the files from the source dir (also subfolders).

Sometimes you need to troubleshoot an existing integration and is given some Camel code (routes). These routes may use different components, and those components may be tricky to run as they are configured in a custom way, or need connection to servers you may not have access to.

You can run Camel JBang by stubbing those components (or all of them).

For example, suppose you need access to a JMS broker in the given route below.

Then you can run this by stub the jms component by:

Then Camel will not start up the JMS component but replace it with the stub component, but keep the actual endpoint URIs.

You can then simulate sending messages to Camel with the cmd send command:

Which then will send the message to the incoming endpoint in the route, i.e. jms:inbox which has been stubbed.

You can also stub a specific endpoint by providing the full uri, such as:

Then only the jms:inbox endpoint is stubbed.

Camel JBang comes with the camel cmd stub command that allows to list all endpoints that has been stubbed, and also browse any messages that are currently present in their internal queues. A stub endpoint is based on the seda component.

And to browse the messages:

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:

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

This works for all DSLs, even java, so you can do:

You can also run dev mode when running Camel with --source-dir, such as:

This starts Camel where it will load the files from the source dir (also subfolders). And in dev mode then you can add new files, update existing files, and delete files, and Camel will automatically hot-reload on the fly.

Using source dir is more flexible than having to specify the files in the CLI as shown below:

In this situation, then Camel will only watch and reload these two files (foo.java and bar.java). So, for example, if you add a new file cheese.xml, then this file is not reloaded. On the other hand, if you use --source-dir then any files in this directory (and subfolders) are automatic detected and reloaded. You can also delete files to remove routes.

You can enable the developer console, which presents a variety of information to the developer.

The console is then accessible from a web browser at: http://localhost:8080/q/dev (by default). The link is also shown in the log when Camel is starting up.

The console can give you insights into your running Camel integration, such as reporting the top routes that takes the longest time to process messages. You can then drill down to pinpoint exactly which individual EIPs in these routes are the slowest.

The developer console can also output the data in JSON format, which, for example, can be used by 3rd-party tooling to scrape the information.

For example, to output the top routes via curl, you can execute:

And if you have jq installed which can format and output the JSON data in color, then do:

Available from Camel 4.5

Camel JBang comes with three sets of profiles

The developer profile will pre-configure Camel JBang with a number of developer assisted features when running Camel. For example, tracing messages during routing, additional metrics collected, and more. This is useful during development and also enhanced the Camel JBang CLI tool.

However, you may want to run Camel JBang in a production-like scenario, which you can do with:

You can have profile-specific configuration in configuration files using the naming style application-<profile>.properties, such as in the following:

The profile-specific configuration will override values in the common configuration.

By default, Camel JBang will automatically resolve dependencies needed to run Camel, which is done by JBang and Camel respectively. Camel itself detects at runtime if a component has a need for JARs that are not currently available on the classpath, and can then automatically download the JARs (incl transitive).

Camel will download these JARs in the following order:

If you do not want Camel JBang to download over the internet, you can turn this off with --download, as shown below:

If you do not want Camel JBang to use your existing Maven settings file, you can use:

Camel JBang will automatically detect dependencies for Camel components, languages, data formats, etc. that from its own release. This means you often do not have to specify which JARs to use.

However, if you need to add 3rd-party custom JARs, then you can specify these with --deps as CLI argument in Maven GAV syntax (groupId:artifactId:version), such as:

In case you need to explicit add a Camel dependency you can use a shorthand syntax (starting with camel: or camel-) such as:

You can specify multiple dependencies separated by comma:

Camel JBang will download from local repository first, and then online from Maven Central. To be able to download from 3rd-party Maven repositories then you need to specify this as CLI argument, ]or in application.properties

The configuration for the 3rd-party Maven repositories can also be configured in application.properties with the key camel.jbang.repositories as shown:

And when running Camel then application.properties is automatically loaded:

However, you can also explicitly specify the properties file to use:

And even better if you specify this as a profile:

Where the profile id is the name of the properties file.

By default, existing ~/.m2/settings.xml file is loaded, so it is possible to alter the behaviour of Maven resolution process. Maven settings file can provide information about Maven mirrors, credential configuration (potentially encrypted) or active profiles, and additional repositories.

Maven repositories can use authentication and the Maven-way to configure credentials is through <server> elements, like this:

While the password may be specified using plain text, it’s better to configure maven master password first and then use it to configure repository password:

The above password should be added to ~/.m2/settings-security.xml file like this:

Then a normal password can be configured like this:

Finally, such passwords can be used in <server>/<password> configuration.

By default, Maven reads the master password from ~/.m2/settings-security.xml file, but we can override it. The location of the settings.xml file itself can be specified as well:

If you want to run Camel application without assuming any location (even ~/.m2/settings.xml), use this option:

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

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

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:

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

Or you can run all files starting with rou*

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:

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

You can also download to a new folder using the --directory option, for example, to download to a folder named myproject, you would do:

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

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

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

You can specify which Camel version to run as shown:

In Camel 3.20.2 onwards the run command has built-in support, using --camel-version, for specifying the Camel version to use for the running Camel integration.

You can also try bleeding-edge development by using SNAPSHOT such as:

In Camel 3.20.3 onwards the version command makes it possible to configure a specific version of Camel to use when running or exporting. This makes it possible to use the latest Camel JBang CLI and run integrations using an older Camel version.

Here Camel JBang is using version 3.20.3. Now suppose we want to run Camel integrations with version 3.18.2.

And you can see what Camel version has been set by:

And when running an integration, then Camel JBang will show you the overridden version when starting.

If you want to unset the version, you can use the --reset option:

Then the Camel version in use will be the same version as Camel JBang.

Camel JBang uses a plugin concept for some of the subcommands so users can add functionality on demand. Each provided plugin adds a list of commands to the Camel JBang command line tool.

You can list the supported plugins with

In case you want to enable a plugin and its functionality, you can add it as follows:

For example to install generate you execute:

This adds the plugin, and all subcommands are now available for execution.

You can list the currently installed plugins with:

To remove a plugin from the current Camel JBang command line tooling, you can use the plugin delete command.

Camel also supports running Camel K integrations and pipes, which represent Kubernetes custom resources following a specific CRD format (Kubernetes Custom Resource Definitions).

For example, a pipe file named joke.yaml:

Can be run with camel:

You can create a new kamelet with the init command by using kamelet naming convention.

For example, to create a new kamelet source, you can do:

This will create a basic kamelet (based on the timer source).

And to use the kamelet, you could create the following route:

If you want to create a sink kamelet, then you just name it with sink as follows (based on log sink):

You can then change the route to use the wine kamelet as follows:

If you want to create a new Kamelet based on an existing Kamelet, for example, to create a new sink based on the existing MySQL:

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

The syntax is

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

Available since Camel 4

When building integrations with Camel JBang, you may find yourself in need of being able to send messages into Camel, to test your Camel routes. This can be challenging when the Camel routes are connected to external systems using different protocols.

The best approach is to send messages into these external systems using standard tools provided by these systems, which often can be done using CLI tools. However, in some situations, where you may not be familiar with these tools, you can try to let Camel send the message. Note that this can only be possible in some scenarios, and should only be used as a quick way.

Suppose you have a Camel route that consumes messages from an external MQTT broker:

In the example above the MQTT broker is running on hostname mybroker port 1883.

The idea with the camel cmd send command is to tap into an existing running Camel integration, and reuse an existing endpoint (if possible). In this example, we want to use the existing configuration to avoid having to configure this again.

By executing the following from a shell

We can send a message where the payload is loaded from a file (payload.json). You can also specify the payload in the CLI argument, but it’s cumbersome to specify JSON structure so often it’s better to refer to a local file.

The mqtt argument is the name of the existing running Camel integration. You can also specify the PID instead. So what happens is that Camel will let the existing integration send the message.

Because the existing integration only has one route, then the send command will automatically pick the from endpoint, i.e. kamelet:mqtt5-source with all its configuration. If there are multiple routes, then you can filter which route/endpoint by the --endpoint option:

For example, to pick the first route by route id:

Or to pick the first route that uses mqtt component:

We are fortunate in this situation as the endpoint can be used as both a consumer and producer in Camel, and therefore we are able to send the message to the MQTT broker via tcp://mybroker:1883 on topic temperate.

The source for this example is provided on GitHub at camel-jbang MQTT example.

To list the currently running Camel integrations, you use the ps command:

This lists the PID, the name and age of the integration.

You can use the stop command to stop any of these running Camel integrations. For example, to stop dude, you can do

You can also stop by the PID:

To stop all integrations, then execute without any pid:

The Hawtio web console allows inspecting running Camel integrations, such as all the JMX management information, and not but least to visualize the Camel routes with live performance metrics. Hawtio is a handy tool for many years, and we have made it easy to use Hawtio with Camel JBang.

To let Hawtio able to inspect the Camel integrations, then the Jolokia JVM Agent must be installed in the running integration, this can be done, either explicit as follows:

With the PID you can then attach Jolokia:

Instead of using PID, you can also attach by name pattern. In this example, because the two Camel integrations have unique names (foo and dude), then you can also attach Jolokia without knowing the PID as follows:

Then you can launch Hawtio using Camel JBang:

This will automatically download and start Hawtio, and open in web browser.

And when Hawtio launches in the web browser, click the Discover tab which should list all the local available Jolokia Agents (yes you can use camel jolokia PID to connect to multiple different Camel integrations and from this list select which to load).

Click the green lightning icon to connect to running Camel integration (of choice).

You can uninstall the Jolokia JVM Agent in a running Camel integration when no longer needed:

It is also possible to do this with only one command, as follows:

Where dude is the name of the running Camel integration. When you stop Hawtio (using ctrl + c) then Camel will attempt to uninstall the Jolokia JVM Agent. However, this may not be able to do this always, because the JVM is being terminated which can prevent camel-jbang from doing JVM process communication to the running Camel integration.

You can also execute a Camel JBang file as a script that can be used for terminal scripting with pipes and filters.

This requires adding the following line in top of the file, for example, as in the upper.yaml file below:

To be able to execute this as a script, you need to set execute file permission:

Then you can then execute this as a script:

Which should output:

Logging can be turned on using --logging=true which then logs to .camel-jbang/camel-pipe.log file. The name of the logging file cannot be configured.

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

You can also point to a folder in a GitHub repository. For example, we have provided some custom Kamelets at https://github.com/apache/camel-kamelets-examples/tree/main/custom-kamelets, which can be used easily:

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:

Can be run with

And you can call the HTTP service with:

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.

When running Camel integrations 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.

When using SQL databases, then you would often need to configure a JDBC connection pool. You can do this:

There are two kinds of debugging:

In the example above we externalize the transformation into a template file named transform.json. However, it’s possible to transform directly in the Camel DSL route.

In the following, we cover the json-transform example from: https://github.com/apache/camel-kamelets-examples/tree/main/jbang/json-transform

In this example, a random beer is fetched via the beer-source kamelet. The beer data is as follows:

We save this beer into a file named sample.json as we want to use this as source for message transformation.

Now suppose we want to transform this to a smaller JSON document with only a few elements, then we can do this directly in the route:

As we can see the route has a setBody where we want to transform the message, which we can do with the simple language combined with JQ (or JSonPath). At first, we just write TODO to get started:

And the output from the transformation is:

We can now do live updates in the Camel route, and when we save the file, the transform command will output the changes in the terminal. So we modify the DSL to grab the details we want, such as:

Notice how we use inlined JQ expressions to grab the desired data from the sample, and when saving the file, we have the result shown in the terminal:

And when we are done with the transformation we can stop by ctrl + c to exit the command.

When transforming messages directly from the DSL (using the --source option), then by default Camel will pick the last expression in the route. If you only have one expression like in this example, then that is easy. But when you have many, then you need to tell which one to use.

You can do this either by referring to the line number in the source code of the EIP / expression, or by its id (if specified).

So suppose the example had many expressions, and the one we want to use is on line 11, then we can do as follows:

Notice how we specify the line number in the source file name, by prefixing with :line-number. The line number does not have to be 100% accurate, as long the number is within range of the EIP, until the next EIP in the route. In the example, this means you can pick number in range 8-17.

If we want to use the id of the expression/EIP, we can do the same as shown below:

You can also transform the message from JSON to XML as shown (or any other kind of fixed structure):

You can configure options that the language format should use, such as shown below:

Pay attention that we now use JSONPath as the language, and the template is a tiny JSON path expression. Because the sample does not have a beer.unknown path, then JSonPath would normally throw an exception. This can be suppressed by setting the option suppressExceptions to true as shown above. Then the output is as follows:

Some components can also be used for message transformation such as FlatPack, Velocity, FreeMarker, Thymeleaf, and good old XSLT.

Given the below XML in the sample.xml file:

Then you can transform this using an XSLT named mystyle.xsl:

Then you can do live changes to the stylesheet and see the output in real-time with Camel JBang by running:

You can then edit the mystyle.xsl file, and save the file, and watch the terminal for the updated result.

You can find this example at: https://github.com/apache/camel-kamelets-examples/tree/main/jbang/xslt-transform

You can configure options that the XSLT component format should use, such as shown below:

Some data formats can also be used for message transformation such as Base64, Csv, FlatPack.

Given the below CSV file in the daltons.csv:

Then you can transform this via Camel CSV dataformat from its form into Java objects (unmarshal). This will NOT transform the CSV into another format such as XML, but allows you to quickly try out the dataformat, and be able to inspect the Java object inside Camel.

This will then output:

As you can see Camel CSV dataformat will then unmarshal the input (from CSV file) to a java.util.ArrayList object with 5 elements (one per row), and each row is another List of the columns.

You can configure options that the CSV data format should use, such as shown below:

The doc goal can show quick documentation for every component, dataformat, kamelets etc. For example, to see the kafka component you run:

To see the documentation for jackson dataformat:

In some rare cases then there may be a component and dataformat with the same name, and the doc goal prioritizes components. In such a situation you can prefix the name with dataformat, i.e.:

You can also see the kamelet documentation such as shown:

You can use the camel dependency copy command to copy the required JARs to a specific folder.

By default, the JARs are copied to lib folder:

The command export --runtime=spring-boot will export your current Camel JBang file(s) to a Maven-based Spring Boot project with files organized in src/main/ folder structure.

For example, to export to Spring Boot using the Maven groupId com.foo and the artifactId acme and with version 1.0-SNAPSHOT you execute:

To export to another directly (copies the files), you execute:

When exporting to Spring Boot then the Camel version defined in the pom.xml or build.gradle is the same version as Camel JBang uses. However, you can specify the Camel version as shown below:

The command export --runtime=quarkus will export your current Camel JBang file(s) to a Maven-based Quarkus project with files organized in src/main/ folder structure.

For example, to export to Quarkus using the Maven groupId com.foo and the artifactId acme and with version 1.0-SNAPSHOT you simply execute:

To export to another directly (copies the files) you execute:

The command export --runtime=camel-main will export your current Camel JBang file(s) to a Maven-based vanilla Camel Main project with files organized in src/main/ folder structure.

For example, to export to Camel Main using the Maven groupId com.foo and the artifactId acme and with version 1.0-SNAPSHOT you simply execute:

To export to another directly (copies the files), you execute:

By default, Camel will export what was last run, or all files from the current directory. You can also explicitly specify which files should be exported.

For example, you may have 3 files in a folder:

These are 3 Camel routes, and you want to export them into 2 different applications:

As you can see the first export command will only include Foo.java, and then 2nd export includes both bar.xml and cheese.yaml.

Camel JBang exports by default as a Maven-based project. To use Gradle instead, you can specify the --build-tool=gradle when exporting, such as:

Usually when exporting to Spring Boot, Quarkus or Camel Main, then JMX management is not included out of the box. To include JMX, you need to add camel:management in the --deps option, as shown below:

Usually when exporting to Spring Boot, Quarkus or Camel Main, then Camel JBang CLI is not included out of the box. To be able to continue to use Camel CLI (i.e. camel), you need to add camel:cli-connector in the --deps option, as shown below:

The export command will by default load configuration from application.properties which also can be used to specific parameters for export such as selecting the runtime and java version.

The follow options related to exporting, can be configured in application.properties:

Every Camel JBang option is added to the user configuration. For example, to export a simple project such as

User configuration keys are unset using the following:

User configuration keys are listed using the following:

Following is the output for the above-mentioned configuration.

To obtain a value for the given key, use the get command.

User configuration values can be used as placeholder substitutes with command line properties, for example:

In this example, since repos is set in the user configuration (config set) and the camel run command declares the placeholder #repos, camel run will replace the placeholder so that both repositories will be used during the execution. Notice, that to refer to the configuration value the syntax is #optionName eg #repos.