docs/components/modules/ROOT/pages/file-watch-component.adoc

[[file-watch-component]]
= file-watch Component
:page-source: components/camel-file-watch/src/main/docs/file-watch-component.adoc

*Available as of Camel version 3.0*

This component can be used to watch file modification events in folder. It is based on https://github.com/gmethvin/directory-watcher[gmethvin/directory-watcher].

== URI Options

// component options: START
The file-watch component supports 6 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *concurrentConsumers* (consumer) | The number of concurrent consumers. Increase this value, if your route is slow to prevent buffering in queue. | 1 | int
| *queueSize* (consumer) | Maximum size of queue between WatchService and consumer. Unbounded by default. | 2147483647 | int
| *pollThreads* (consumer) | The number of threads polling WatchService. Increase this value, if you see OVERFLOW messages in log. | 1 | int
| *fileHasher* (consumer) | Reference to io.methvin.watcher.hashing.FileHasher. This prevents emitting duplicate events on some platforms. For working with large files and if you dont need detect multiple modifications per second per file, use #lastModifiedTimeFileHasher. You can also provide custom implementation in registry. | #murmur3FFileHasher | FileHasher
| *useFileHashing* (consumer) | Enables or disables file hashing to detect duplicate events. If you disable this, you can get some events multiple times on some platforms and JDKs. Check java.nio.file.WatchService limitations for your target platform. | true | boolean
| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
|===
// component options: END


// endpoint options: START
The file-watch endpoint is configured using URI syntax:

----
file-watch:path
----

with the following path and query parameters:

=== Path Parameters (1 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *path* | *Required* Path of directory to consume events from. |  | String
|===


=== Query Parameters (14 parameters):


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *antInclude* (consumer) | ANT style pattern to match files. The file is matched against path relative to endpoint path. Pattern must be also relative (not starting with slash) | ** | String
| *autoCreate* (consumer) | Auto create directory if does not exists. | true | boolean
| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
| *concurrentConsumers* (consumer) | The number of concurrent consumers. Increase this value, if your route is slow to prevent buffering in queue. | 1 | int
| *events* (consumer) | Comma separated list of events to watch. | CREATE,MODIFY,DELETE | Set
| *fileHasher* (consumer) | Reference to io.methvin.watcher.hashing.FileHasher. This prevents emitting duplicate events on some platforms. For working with large files and if you dont need detect multiple modifications per second per file, use #lastModifiedTimeFileHasher. You can also provide custom implementation in registry. | #murmur3FFileHasher | FileHasher
| *pollThreads* (consumer) | The number of threads polling WatchService. Increase this value, if you see OVERFLOW messages in log. | 1 | int
| *queueSize* (consumer) | Maximum size of queue between WatchService and consumer. Unbounded by default. | 2147483647 | int
| *recursive* (consumer) | Watch recursive in current and child directories (including newly created directories). | true | boolean
| *useFileHashing* (consumer) | Enables or disables file hashing to detect duplicate events. If you disable this, you can get some events multiple times on some platforms and JDKs. Check java.nio.file.WatchService limitations for your target platform. | true | boolean
| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. |  | ExceptionHandler
| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. |  | ExchangePattern
| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
|===
// endpoint options: END

// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-file-watch-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 7 options, which are listed below.



[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.component.file-watch.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean
| *camel.component.file-watch.concurrent-consumers* | The number of concurrent consumers. Increase this value, if your route is slow to prevent buffering in queue. | 1 | Integer
| *camel.component.file-watch.enabled* | Whether to enable auto configuration of the file-watch component. This is enabled by default. |  | Boolean
| *camel.component.file-watch.file-hasher* | Reference to io.methvin.watcher.hashing.FileHasher. This prevents emitting duplicate events on some platforms. For working with large files and if you dont need detect multiple modifications per second per file, use #lastModifiedTimeFileHasher. You can also provide custom implementation in registry. The option is a io.methvin.watcher.hashing.FileHasher type. |  | String
| *camel.component.file-watch.poll-threads* | The number of threads polling WatchService. Increase this value, if you see OVERFLOW messages in log. | 1 | Integer
| *camel.component.file-watch.queue-size* | Maximum size of queue between WatchService and consumer. Unbounded by default. | 2147483647 | Integer
| *camel.component.file-watch.use-file-hashing* | Enables or disables file hashing to detect duplicate events. If you disable this, you can get some events multiple times on some platforms and JDKs. Check java.nio.file.WatchService limitations for your target platform. | true | Boolean
|===
// spring-boot-auto-configure options: END

== Examples:

=== Recursive watch all events (file creation, file deletion, file modification):
[source,java]
----
from("file-watch://some-directory")
    .log("File event: ${header.CamelFileEventType} occurred on file ${header.CamelFileName} at ${header.CamelFileLastModified}");
----

=== Recursive watch for creation and deletion of txt files:
[source,java]
----
from("file-watch://some-directory?events=DELETE,CREATE&antInclude=**/*.txt")
    .log("File event: ${header.CamelFileEventType} occurred on file ${header.CamelFileName} at ${header.CamelFileLastModified}");
----

=== Create snapshot of file when modified:
[source,java]
----
from("file-watch://some-directory?events=MODIFY&recursive=false")
    .setHeader(Exchange.FILE_NAME, simple("${header.CamelFileName}.${header.CamelFileLastModified}"))
    .to("file:some-directory/snapshots");
----

== Message Headers

The following headers are supported by this component:

=== File Watch consumer only

[width="100%",cols="10%,90%",options="header",]
|===
|Header |Description

|`CamelFileEventType` |Type of event. Possible values: CREATE, DELETE, MODIFY.
The java type of this header is `org.apache.camel.component.file.watch.constants.FileEventEnum`

|`CamelFileName` |Name of the consumed file as a relative file path with offset from the
starting directory configured on the endpoint.

|`CamelFileNameOnly` |Only the file name (the name with no leading paths).

|`CamelFileAbsolute` |A `boolean` option specifying whether the consumed file denotes an
absolute path or not. Should normally be `false` for relative paths.
Absolute paths should normally not be used but we added to the move
option to allow moving files to absolute paths. But can be used
elsewhere as well.

|`CamelFileAbsolutePath` |The absolute path to the file. For relative files this path holds the
relative path instead.

|`CamelFilePath` |The file path. For relative files this is the starting directory + the
relative filename. For absolute files this is the absolute path.

|`CamelFileRelativePath` |The relative path.

|`CamelFileParent` |The parent path.

|`CamelFileLastModified` |A `Long` value containing the last modified timestamp of the file.
|===