DirPoll

Not every integration looks like a clean TCP connection. Sometimes a legacy acquirer, a retail back-office system, or an overnight batch job communicates by dropping files into a shared directory and expecting a response file to appear alongside. DirPoll handles exactly that pattern.

org.jpos.util.DirPoll watches a request directory and, for every file that appears there, delegates to a processor you provide. It manages the entire file lifecycle so your processor code only has to focus on the business logic.

Directory structure

DirPoll operates on six directories that all share a common base path:

<base>/
  request/   ← incoming files arrive here
  run/       ← file is moved here before processing begins
  response/  ← response file appears here (Processor interface only)
  tmp/       ← callers should stage files here before moving to request/
  bad/       ← file lands here when processing throws an unretriable error
  archive/   ← processed files are kept here (when archiving is enabled)

The names are configurable via <property> elements, but the defaults cover the vast majority of use cases.

How a file is processed

1. A file appears in request/.
2. DirPoll moves it to run/ — the file is now owned by the processor.
3. Your processor runs.
4. On success: the file is moved to archive/ (if archiving is on) or deleted. A Processor response is atomically written to response/.
5. On error: the file is moved to bad/. If your exception signals retry, the file is moved back to request/ after a back-off delay.

Deploy descriptor

<dir-poll class="org.jpos.q2.iso.DirPollAdaptor"
          logger="Q2" name="dirpoll" realm="dirpoll">
  <attr name="path">dirpoll</attr>
  <attr name="pollInterval" type="java.lang.Long">1000</attr>
  <attr name="priorities">.req *</attr>
  <attr name="processor">org.jpos.tutorial.EchoProcessor</attr>

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

The <attr> elements configure the adaptor (path, polling rate, priorities, processor class). The <property> elements are forwarded to DirPoll itself and control archiving, directory name overrides, and other runtime options.

note

DirPollAdaptor is the Q2 QBean wrapper around DirPoll. The adaptor takes care of lifecycle (start/stop) and wires your processor through Q2's QFactory.

What's next

• Processor interface — byte-in / byte-out; DirPoll writes the response for you.
• FileProcessor interface — full control; you receive the File handle directly.
• Priorities & options — file extension priority queues, archiving, retry, and the safe handoff pattern.