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
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 inapplication.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 inapplication.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 inapplication.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.