Priorities & options

File extension priorities

When multiple request types arrive concurrently you can assign priority by file extension. DirPoll processes higher-priority files first within each poll cycle.

<attr name="priorities">.req *</attr>

Extensions are listed left-to-right, highest to lowest. The special token * matches any extension (or no extension) and acts as a catch-all.

In the example above, files ending in .req are processed before all others. With three priority levels:

<attr name="priorities">.urgent .normal *</attr>

DirPoll scans the request/ directory three times per cycle — first for .urgent, then .normal, then everything else.

Regex matching

If you need more expressive patterns, enable regex mode:

<property name="priority.regex" value="true" />

With regex mode each token is treated as a regular expression matched against the full file name:

<attr name="priorities">.*\.urgent\.req .*</attr>

Archiving

By default, processed request files are deleted. Enable archiving to keep them:

<property name="archive"           value="true"  />
<property name="archive.timestamp" value="true"  />
<property name="archive.compress"  value="false" />

Property	Default	Description
archive	false	Move processed files to archive/ instead of deleting
archive.timestamp	false	Append a timestamp to archived file names
archive.dateformat	yyyyMMddHHmmss	SimpleDateFormat pattern used for the timestamp
archive.compress	false	Zip the archived file

Other options

Property	Default	Description
zero-length	false	Accept zero-length files (skipped by default)
response.suffix	(same as request)	Suffix substitution for response file names
request.dir	request	Override the request subdirectory name
response.dir	response	Override the response subdirectory name
tmp.dir	tmp	Override the tmp subdirectory name
run.dir	run	Override the run subdirectory name
bad.dir	bad	Override the bad subdirectory name
archive.dir	archive	Override the archive subdirectory name

Retry on transient errors

If processing fails for a transient reason (network hiccup, downstream service temporarily unavailable) you can ask DirPoll to requeue the request:

@Override
public byte[] process(String name, byte[] request)
        throws DirPoll.DirPollException {
    try {
        return callDownstream(request);
    } catch (TimeoutException e) {
        DirPollException dpe = new DirPoll.DirPollException("downstream timeout", e);
        dpe.setRetry(true);          // requeue after back-off
        throw dpe;
    }
}

When retry is true, DirPoll moves the file back to request/ after waiting pollInterval × 10 milliseconds. Permanent errors (retry not set) move the file to bad/.

The safe handoff pattern

warning

A file must be complete before it appears in request/. If your upstream writer creates files directly in request/, DirPoll may pick them up while they are still being written.

The correct pattern is:

1. Write the file to the tmp/ directory (or any directory on the same filesystem).
2. Close the file handle (flush to disk).
3. Rename/move it atomically into request/.

# shell example
cp payload.bin dirpoll/tmp/order-123.req
mv dirpoll/tmp/order-123.req dirpoll/request/

Because rename(2) is atomic on POSIX filesystems, DirPoll will either see the complete file or nothing at all — never a partial write. This guarantee breaks down across different filesystems (e.g., NFS mounts), so keep tmp/ and request/ on the same volume.