Listen to a Folder

Introduction

In this hands-on workshop, you will build a file monitoring integration using Kaoto’s visual designer and Apache Camel. You’ll learn how to watch a directory for file system changes, filter events based on conditions, and automatically back up files when they are created.

What You’ll Learn:

• File system monitoring with the file-watch component
• Extracting metadata from Camel message headers
• Filtering events using the Message Filter pattern
• Copying files to backup locations
• Testing and debugging Camel routes locally
• Using Apache Camel’s Simple Expression Language

What You’ll Build: A Camel route that monitors a directory for file changes, filters CREATE events, backs up newly created files to a separate directory, and logs all file system events to the console.

Prerequisites

Before starting this workshop, ensure you have the following installed and configured on your system:

Required Software

• Visual Studio Code - Download from code.visualstudio.com
• Kaoto Extension for VSCode - Install from the VSCode Marketplace
• Java Development Kit (JDK) 17 or later - Required for running Apache Camel
  • Download from Adoptium or your preferred JDK distribution
• Apache Camel JBang - For easy infrastructure setup
  • Install via: curl -Ls https://sh.jbang.dev | bash -s - trust add https://github.com/apache/camel
  • Then: jbang app install camel@apache/camel

Required Knowledge

This workshop assumes you have:

• Basic understanding of integration concepts - Familiarity with data processing
• Basic command-line skills - Ability to navigate directories and run commands
• Familiarity with VSCode - Basic navigation and file management

What You’ll Set Up During the Workshop

The following will be configured as part of the workshop steps:

• Test directories for file monitoring
• Backup directory for file copies
• Camel integration route

Project Setup

1. Install the Kaoto extension for VSCode.
2. Create a new directory for the workshop:

$ mkdir file-monitor-workshop
$ cd file-monitor-workshop

Description

This workshop guides you through building a file monitoring integration using Apache Camel and Kaoto. You will create a route that demonstrates the File Integration Pattern and Message Filter Pattern, two fundamental Enterprise Integration Patterns (EIPs).

The Route Flow:

File System Events → File Watch → Filter (CREATE only) → Copy to Backup
                                                       ↓
                                                    Log All Events

The route continuously monitors a directory, processes each file system event, filters for CREATE events to trigger backups, and logs all events for visibility.

Part 1: Log Changes

Goal

Create a route that watches a folder and logs file system events (CREATE, MODIFY, DELETE) with detailed information about each change.

Step-by-Step Instructions

Step 1: Create a New Route

1. Open VSCode and navigate to your file-monitor-workshop directory
2. Click the Kaoto icon in the left sidebar
3. Click the Camel File… button to create a new integration

4. If the Camel File… button is not showing, click on the second icon next to Integrations (a file with a + sign).
5. In the dialog that appears:
   • Select Camel Route as the file type
   • Select YAML as the Camel DSL
   • Choose your workshop folder as the saving location
   • Name the file file-monitor

A new route will appear in the Kaoto visual designer with a default timer component, a SetBody step and Log processor.

6. Select Camel Main 4.16.0 from the options that appear when clicking the Camel version selector. This tutorial was created using this version and other versions have not been tested in this context. If chosen other Camel versions, they may present slight variations in component availability and presentation.

Step 2: Configure the File Watcher

The first component needs to monitor the test directory for file changes.

1. Hover over the timer component in the visual designer
2. Click the Replace icon (circular arrow) that appears

3. In the search box, type file-watch and select the File Watch component

4. Click on the File Watch component to open its properties panel on the right
5. Navigate to the All tab at the top of the properties panel
6. Configure the following properties:

   Property	Value	What it does
   path	/tmp/tutorial/	Directory to monitor for changes
   recursive	false	Don’t watch subdirectories
   auto create	true	Creates the directory automatically. True by default

7. Save the file using Ctrl/Cmd + S or by clicking File → Save in the VS Code menu bar

Step 3: Add Log Processor

Now we’ll add a log step to output information about detected changes.

1. Hover over the second component (SetBody) in the route

2. Click the Delete icon

3. Click on the Log processor to open its properties

4. Configure the message property in Required tab:

   Property	Value
   message	Detected ${header.CamelFileEventType} on file ${header.CamelFileName} at ${header.CamelFileLastModified}

5. Save the changes

💡 Understanding Camel Headers: The file-watch component populates message headers with metadata about file events:

• CamelFileEventType: Type of event (CREATE, MODIFY, DELETE)
• CamelFileName: Name of the affected file
• CamelFileLastModified: Timestamp of last modification

Step 4: Review Your Route

You can find the source code by clicking in the </> icon on the top right of the visual designer.

Your completed route should look like this in the visual designer. The YAML source should be similar to:

Image Preview View YAML

View Image YAML Source

- route:
    id: route-2573
    from:
      id: from-3280
      uri: file-watch
      parameters:
        path: /tmp/tutorial/
        recursive: false
      steps:
        - log:
            message: Detected ${header.CamelFileEventType} on file ${header.CamelFileName}
              at ${header.CamelFileLastModified}

✅ Checkpoint: You’ve completed Part 1! The route will now monitor the folder and log all file system events.

Part 2: Add a Filter

Goal

Enhance the route to filter events and only back up files when they are created (not modified or deleted). This introduces the Message Filter Pattern.

Step-by-Step Instructions

Step 1: Add Filter Processor

We’ll insert a filter between the file-watch and log components.

1. Hover over the arrow between file-watch and log

2. Click the + icon that appears on the arrow
3. Search for filter and select the Filter processor
4. Click on the Filter component to open its properties
5. Configure the filter expression in Required tab:

   Property	Value	What it does
   Expression language	Simple	The expression language to use
   Expression	${header.CamelFileEventType} == 'CREATE'	Condition to evaluate

6. Save the changes

💡 Understanding the Filter: The filter creates a conditional branch. Steps inside the filter only execute when the condition is true. In this case, only CREATE events will pass through.

Step 2: Add File Component Inside Filter

Now we’ll add a file component inside the filter to copy created files.

1. Click inside the filter placeholder (the dotted box area)

2. This will add a new component inside the filter branch

3. Search for file and select the File component

4. Click on the File component to open its properties

5. Configure in Required tab:

   Property	Value	What it does
   directoryName	/tmp/backup/	Destination folder for file copies
   auto create	true	Creates the directory automatically. True by default

6. Save the changes

Step 3: Review Your Route

Your completed route should look like this in the visual designer. The YAML source should be similar to:

Image Preview View YAML

View Image YAML Source

- route:
    id: route-2573
    from:
      id: from-3280
      uri: file-watch
      parameters:
        path: /tmp/tutorial/
        recursive: false
      steps:
        - filter:
            id: filter-2413
            steps:
              - to:
                  id: to-2610
                  uri: file
                  parameters:
                    directoryName: /tmp/backup/
            simple:
              expression: ${header.CamelFileEventType} == 'CREATE'
        - log:
            message: Detected ${header.CamelFileEventType} on file ${header.CamelFileName}
              at ${header.CamelFileLastModified}

✅ Checkpoint: You’ve completed Part 2! The route now backs up files only when they are created, while still logging all events.

Part 3: Testing Your Route

Goal

Launch the route locally and verify it works correctly by creating, modifying, and deleting test files.

Step-by-Step Instructions

Step 1: Launch the Route

1. In the VSCode file explorer, locate your file-monitor-workshop folder
2. In the Kaoto extension panel, find the folder containing your YAML route file
3. Click the Play button (▶️) next to Integrations or next to the folder name

4. A new terminal will open in VSCode
5. Watch the terminal output as Camel JBang starts the route

You should see output similar to:

INFO  [route-2573] Apache Camel 4.16.0 (file-monitor) started in ...

💡 What’s happening: The Kaoto extension uses Camel JBang to run your route locally, making it easy to test without complex setup.

Step 2: Test the Integration

With the route running, test it by creating files in the monitored directory:

1. Open a new terminal window
2. Create a test file:

$ echo "test content" > /tmp/tutorial/test1.txt

3. Watch the Camel terminal for log output showing the CREATE event
4. Verify the file was copied to /tmp/backup/
5. Try modifying the file:

$ echo "modified" >> /tmp/tutorial/test1.txt

6. Watch for the MODIFY event in the logs (file won’t be copied again)
7. Try deleting the file:

$ rm /tmp/tutorial/test1.txt

8. Watch for the DELETE event in the logs

Step 3: Stop the Route

To stop the running integration:

1. Go to the terminal where Camel is running
2. Press Ctrl + C

✅ Checkpoint: You’ve completed the workshop! You now understand file monitoring, filtering, and local testing with Kaoto.

Key Concepts Covered

Apache Camel Components

Components are the building blocks of Camel routes. They represent endpoints that can send or receive messages.

Apache Camel Processors

Processors transform or manipulate messages as they flow through a route.

Simple Expression Language

Camel’s Simple Expression Language is used for accessing message data and performing operations.

Enterprise Integration Patterns

This workshop demonstrates the Message Filter Pattern:

Message Filter - Selectively processes messages based on criteria. In this workshop, we filter file events to process only CREATE events for backup purposes.

Best Practices

Route Design

1. Start simple: Begin with basic routes, add complexity gradually
2. Use meaningful names: Name components and routes clearly
3. Add descriptions: Use the description property to document components
4. Test incrementally: Test after each major change

Component Selection

1. Choose the right component: Understand component vs. processor differences
2. Read documentation: Reference Apache Camel docs for details
3. Configure properly: Fill all required parameters
4. Use appropriate expressions: Match expression language to use case

Testing Strategy

1. Verify prerequisites: Check installations before testing
2. Create test data: Prepare files and directories
3. Monitor output: Watch terminal for errors and results
4. Iterate quickly: Make small changes and retest

Troubleshooting

1. Check prerequisites: Verify Extension Pack and JBang installed
2. Verify paths: Ensure directories exist and are accessible
3. Review configuration: Double-check parameter values
4. Read error messages: Camel provides detailed error information

Additional Resources

Documentation

• Kaoto Documentation - Kaoto user guide and tutorials
• Apache Camel Documentation - Complete Camel reference
• Apache Camel YAML DSL - YAML DSL reference
• Enterprise Integration Patterns - EIP reference

Community

• Kaoto GitHub - Report issues and contribute
• Apache Camel Community - Get help and connect with other users