File Monitor Input Adapter

Contents

Introduction
File Monitor Properties
Description of This Adapter's Ports
Typechecking and Error Handling
Related Topics

Introduction

The TIBCO StreamBase® File Monitor adapter monitors the file system for creation, modification, and deletion of directories and files. For each such event, the adapter emits tuples that specify the path name and the type of change that occurred.

Note

Operating systems do not all use the same reporting and monitoring protocols. As a result, certain events may be reported by one operating system but not by another. For example, when you modify a file, your system may issue you a modified event for both the file and the folder containing that file, but another system would inform you of the file modified event alone.

Caution

This adapter has the ability to monitor folder structures for changes but it is not recommended to monitor large folder structures, for example trying to register the root folder with Watch Sub directories enabled. Trying to do this will cause large slowdowns on most, if not all, systems.

Tip

In some cases, depending on the operating system, the adapter may not receive notification of events (such as deletion) performed against a watched folder. If you require such notifications, consider watching its parent folder instead.

The adapter has a sample, described in File Monitor Input Adapter Sample.

File Monitor Properties

This section describes the properties you can set for this adapter, using the various tabs in its Properties view.

General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Adapter: A read-only field that shows the formal name of the adapter.

Class: A field that shows the fully qualified class name that implements the functionality of this adapter. Use this class name when loading the adapter in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this adapter starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the adapter does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Adapter Properties Tab

Property Data Type Default Description StreamSQL Property
Enable Control Port check box Selected If enabled, a control input port is present for enqueuing tuples with the path (file or directory) to monitor. EnableControlPort
Enable Status Port check box Selected If enabled, a status output port is present on which tuples are emitted to convey important events within the adapter. EnableStatusPort
Path String None The default path to monitor when no path is provided on the control input port. If this field has a value, the adapter will watch this path when it starts. WatchPath
Notify On Create Boolean true If enabled, the the file monitor watches for create events on the given path. This value is used as the default for incoming control tuples if Notify On Create Field Name is not supplied or is null. WatchCreate
Notify On Delete Boolean true If enabled, the the file monitor will watch for delete events on the given path. This value is used as the default for incoming control tuples if Notify On Delete Field Name is not supplied or is null. WatchDelete
Notify On Modified Boolean true If enabled, the the file monitor will watch for modify events on the given path. This value is used as the default for incoming control tuples if Notify On Modified Field Name is not supplied or is null. WatchModified
Watch Sub directories Boolean false If enabled, the file monitor will recursively watch all sub directories of the given path. Only valid for paths that are directories. This value is used as the default for incoming control tuples if Watch Sub Directories Field Name is not supplied or is null. WatchSubDirectories
Output File Names On Monitor Boolean false If enabled the system will output all file names and directories for the path being monitored when the initial monitoring begins.\nWARN: If given a root path, and watching sub directories, can cause long delays traversing the file system. OutputFileNamesOnMonitor
Ignore Duplicate Updates Boolean true If enabled, the file monitor will ignore duplicate updates for a set amount of time. Some file systems generate multiple updates for a single file update or directory name change; this option enables basic filtering of such duplicates, defined as any update with the same event type and path within the period specified by Timespan In Milliseconds. Two different update events within that period, for example a create event followed directly by a modify event, would not be ignored as duplicates. IgnoreDuplicateUpdates
Timespan In Milliseconds int 5000 The time in milliseconds within which updates on the same path can be regarded as duplicates. IgnoreDuplicateUpdatesMilliseconds
Path Field Name String Path The field in the incoming control port tuple which represents the path to monitor. PathFieldName
Notify on Create Field Name String NotifyOnCreate The field in the incoming control port tuple which represents the boolean flag determining if the path should be monitored for create events. If this value is empty or evaluates to null the default value will be used. NotifyOnCreateFieldName
Notify on Delete Field Name String NotifyOnDelete The field in the incoming control port tuple which represents the boolean flag determining if the path should be monitored for delete events. If this value is empty or evaluates to null the default value will be used. NotifyOnDeleteFieldName
Notify on Modified Field Name String NotifyOnModified The field in the incoming control port tuple which represents the boolean flag determining if the path should be monitored for modify events. If this value is empty or evaluates to null the default value will be used. NotifyOnModifiedFieldName
Watch Sub Directories Field Name String WatchSubDirectories The field in the incoming control port tuple which represents the boolean flag determining if the file monitor should recurse all sub-directories. If this value is empty or evaluates to null the default value will be used. WatchSubDirectoriesFieldName
Output File Names On Monitor Field Name String   The field in the incoming control port tuple which represents the flag to output field names on monitor. If this field is not assigned or is null the default value will be used. OutputFileNamesOnMonitorFieldName
Log Level drop-down list INFO Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL. LogLevel

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Description of This Adapter's Ports

The File Monitor adapter's ports are used as follows:

  • Control (input): Tuples enqueued on this port cause the adapter to monitor a directory on the file system. The schema for this port has the following field:

    • Path, string, the path on the file system to monitor. If null, the path is taken from the adapter's Path property.

    • NotifyOnCreate, boolean, the flag that determines if create events should be monitored on the file system. If null, the value is taken from the adapter's Notify On Create property.

    • NotifyOnDelete, boolean, the flag that determines if deleteuses events should be monitored on the file system. If null, the value is taken from the adapter's Notify On Delete property.

    • NotifyOnModified, boolean, the flag that determines if modify events should be monitored on the file system. If null, the value is taken from the adapter's Notify On Modified property.

    • WatchSubDirectories, boolean, the flag that determines if file monitor should also watch all sub directories of the given path. If null, the value is taken from the adapter's Watch Sub Directories property.

  • Status (output): The adapter emits tuples from this port when significant events occur, such as when an attempt to monitor the file system starts,stops, or fails. The schema for this port has the following fields:

    • Type, string: Always returns 'Monitor'

    • Action, string: returns an action associated with the event Type:

      • Error

      • Register

      • Unregister

    • Object, string: returns the path associated with this event.

    • Message, string: Returns a human-readable description of the event.

  • Data (output): Tuples are emitted on this port when path events are available. The schema for this port has the following fields:

    Note

    If Enable Control Port is selected, then this schema adds an additional tuple field 'PassThroughFields' which contains all the values from the control port.

    • Path, string, The full path associated with the event.

    • Context, string, The context path associated with the event, usually just the file name or folder name.

    • Event, string, One of the following event types:

      • Created

      • Deleted

      • Modified

    • PassThroughFields, tuple, If the control port is enabled this field will contain all the values from the last incoming control port tuple.

Typechecking and Error Handling

The File Monitor adapter issues typecheck messages to help you configure the adapter within your StreamBase application, principally for the following reasons:

  • The Control Input Port does not contain the field name specified in the Path Field Name property, or that field is not of type string.

  • The Control Input Port does not contain the field name specified in the Notify On Create Field Name property, or that field is not of type boolean.

  • The Control Input Port does not contain the field name specified in the Notify On Delete Field Name property, or that field is not of type boolean.

  • The Control Input Port does not contain the field name specified in the Notify On Modified Field Name property, or that field is not of type boolean.

  • The Control Input Port does not contain the field name specified in the Watch Sub Directories Field Name property, or that field is not of type boolean.

  • The Path property contains the name of an invalid path.

The adapter generates warning messages at runtime under various conditions, including:

  • A control tuple is received with a null value in its Path field and a value for the adapter's Default Path property has not been specified.

  • An error occurs attempting to monitor the path.

Related Topics