File kicker and receiver

Overview

The file kicker and receiver components are used together to allow an application to be notified of a change to a specified file or directory.

File kicker

The file kicker component periodically examines a specified file or directory. When a change is detected, it sends an HTTP POST request to another application which hosts the corresponding file receiver.

File receiver

The file receiver fires the fileUpdate event when notified by the file kicker. The application logic to be carried out when the resource is updated is placed in a fileUpdate event handler.

The file kicker and file receiver typically reside in separate applications. The remainder of this topic describes how the file kicker and file receiver applications are configured.

File kicker configuration

Create a new application to host the file kicker and add dependency zero.file.kicker to provide the file kicker function. A single file kicker application can contain multiple kicker tasks monitoring different resources.

The following example contains a file kicker configuration:

/config/timer/tasks/myFileKicker = { "delay" : 1 }

/config/handlers += [{
    "events" : "timer",
    "handler" : "zero.file.kicker.FileKicker.class",
    "conditions" : "/event/_taskName =~ myFileKicker",
    "instanceData" : {
        "fileName" : "file1", 
        "receiverURL" : "http://localhost:8081/file/FileReceiver"
    }
}]

The file kicker functionality is specified with two configuration elements. A timer task configuration specifies the length of time to wait between checking for file updates. A timer event handler specifies the processing for the file kicker timer task in an instanceData map.

fileName

The name of the file or directory being monitored. This may be an absolute or a relative path name.

receiverURL

The URL of the file receiver which will be notified of changes.

reportMultipleFiles

This boolean value indicates whether or not the kicker responds to updates to multiple files in a directory with a single kick. The default is false meaning that if a directory is being monitored and updates to multiple files in that directory are detected, a single kick will be made for each updated file.

File receiver configuration

A file receiver resides in an application that includes the zero.file.receiver dependency and the fileUpdate event handler implementation that will handle the file change notification.

The application must include POST handler configuration for the file receiver, matching the receiverURL specified to the corresponding kicker. The following example configures a file receiver at contextRoot /file/FileReceiver:

/config/handlers += [{
    "events" : "POST",
    "handler" : "zero.file.receiver.FileReceiver.class",
    "conditions" : "/request/path =~ /file/FileReceiver(/.*)?"
}]

The application logic required to process the update is implemented as a fileUpdate event handler. When the fileUpdate event is fired, the global context key, /event/kickData, contains a map of the kick data sent by the file kicker.

File kick data contents

The file kicker sends an HTTP POST request to the file receiver containing a JSON object. This object is presented as a map to the fileUpdate event handler in the global context, at /event/kickData.

appName

The name of the application containing the file kicker that sent the POST request.

kickerName

The name of the individual file kicker timer task in the sending application.

fileName

The name of the file or directory that has been updated.

lastModified

A timestamp (long) containing the last modifed time of the file when the update was detected.

msg

Indicates resource type ("file" or "directory") and state change ("found", "updated", or "not found").

files

List of file kicker data for updated files within a directory being watched.

The following example contains file kick data for a simple update in JSON format:

{
   "appName":"zero.file.kicker.tests",
   "fileName":"file1",
   "fileData":{
      "lastModified":1205413109109,
      "fileName":"file1",
      "msg":"file found"
   },
   "kickerName":"task2"
}

This second example contains a message resulting from two updated files within a directory being watched:

{
   "appName":"zero.file.kicker.tests",
   "fileName":"dir1",
   "fileData":{
      "lastModified":1205413120109,
      "files":[
         {
            "lastModified":1205413120109,
            "fileName":"file11",
            "msg":"file updated"
         },
         {
            "lastModified":1205413120109,
            "fileName":"file12",
            "msg":"file updated"
         }
      ],
      "fileName":"dir1",
      "msg":"directory updated"
   },
   "kickerName":"task3"
}