org.mule.extension.file.internal

Class DirectoryListener

java.lang.Object

org.mule.runtime.extension.api.runtime.source.Source<InputStream,ListenerFileAttributes>

org.mule.extension.file.internal.DirectoryListener

All Implemented Interfaces:

FlowConstructAware

@Alias(value="directory-listener")
public class DirectoryListener
extends org.mule.runtime.extension.api.runtime.source.Source<InputStream,ListenerFileAttributes>
implements FlowConstructAware

Listens for near real-time events that happens on files contained inside a directory or on the directory itself. The events are not acquired by polling the filesystem but rather actually listening for operating system events.

Whenever a file (or the directory) is created, updated or deleted, this Source will fire a Message which payload reference the affected file and the attributes will be a ListenerFileAttributes instance.

There're however some special cases to be considered:

• If the file has been deleted, then it's not possible to obtain its content so the message payload will be null
• Also in the case of file deletion, all its attributes are also not available. Thus, the message attributes will actually be an instance of DeletedFileAttributes which throws IllegalStateException whenever a non available attribute is requested
• When the event references a directory, then the payload is also a null

When to use it

This source is useful in cases in which a flow should respond to changes done on the filesystem, examples being trigger files, transaction files being added on a drop folder, settings files updated, etc. All of the above cases could be done using a <file:list> operation inside a poll scope (maybe also combined with a <watermark>.

However, although polling is a powerful and reliable solution, it's not an efficient one. Because this listener relies on operating system notifications, it's much more efficient in terms of resources.

Reliability

The trade-off between a poll reliability and this listener's performance is reliability. Because operating system events don't generally include the concept of transaction or replay, there's no way to guarantee that no event is going to be lost in case of failure or server crash. Although you can always use mule to implement a reliable acquisition pattern, there's no fallback is such acquisition fails. What this means is that this listener is no silver bullet and it should not been seen as the recommended approach over a poll+list+watermark approach. Users should analyse each use case and environment to determine which the best option is.

Operating system limitations

This component's behaviour might be slightly different depending on the OS on which it is deployed. The main differences are usually (but not exclusively) related to:

• Overflows: In highly concurrent scenarios a given file might be associated to hundreds of events per second. Some OS might not be able to handle that gracefully and decide to drop some of those events or even fail.
• Polling: Some operation systems (like older versions of OSX) don't actually support file system notifications. In those cases, the JRE decides to compensate by using a high frequency poll, in which case the listener becomes pretty much the same as using a poll element

Since:

4.0

Constructor Summary

Constructors

Constructor and Description
DirectoryListener()

Method Summary

Modifier and Type	Method and Description
boolean	isStarted()
void	onStart(org.mule.runtime.extension.api.runtime.source.SourceCallback<InputStream,ListenerFileAttributes> sourceCallback)
void	onStop()
void	setFlowConstruct(FlowConstruct flowConstruct)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DirectoryListener

public DirectoryListener()

Method Detail

onStart

public void onStart(org.mule.runtime.extension.api.runtime.source.SourceCallback<InputStream,ListenerFileAttributes> sourceCallback)
             throws org.mule.runtime.api.exception.MuleException

Specified by:

onStart in class org.mule.runtime.extension.api.runtime.source.Source<InputStream,ListenerFileAttributes>

Throws:

org.mule.runtime.api.exception.MuleException

onStop

public void onStop()

Specified by:

onStop in class org.mule.runtime.extension.api.runtime.source.Source<InputStream,ListenerFileAttributes>

setFlowConstruct

public void setFlowConstruct(FlowConstruct flowConstruct)

Specified by:

setFlowConstruct in interface FlowConstructAware

isStarted

public boolean isStarted()

Returns:

whether this source is actually started