[[dirpoll]]
== DirPoll

Some jPOS-based applications have to interact with third-party legacy software
(e.g., batch files coming from acquirers, retail applications, etc). Most of 
the time one can be lucky enough to deal with legacy applications capable of 
sending transactions over decent protocols but sometimes you are not
that lucky and the best thing you can get is a disk-based interchange, i.e.,
they place a request in a given directory, you process that request and provide
a response. 

*org.jpos.util.DirPoll* uses the following directory structure (whose names are
self explanatory):

----
     ..../archive
     ..../request
     ..../response
     ..../tmp
     ..../run
     ..../bad
  
----

and defines the following inner interfaces: 

[source,java]
----

    public interface Processor {
        public byte[] process(String name, byte[] request)
            throws DirPollException;
    }
    public interface FileProcessor {
        public void process (File name) 
            throws DirPollException;
    }
  
----

You can either create a Processor or a FileProcessor to handle incoming traffic. 

Whenever a legacy application places a file in the +request+ directory, your
Processor (or FileProcessor) gets called, giving you a chance to process the
given request and provide a response (if you're using a Processor, the response
will be placed in the +response+ directory). 


.DirPoll Processor
====
[source,java]
----

    public class DirPollProcessor implements DirPoll.Processor {
        DirPollProcessor () {
            super ();
            DirPoll dp = new DirPoll ();
            dp.setLogger (logger, "dir-poll");
            dp.setPath ("/tmp/dirpoll");
            dp.createDirs ();
            dp.setProcessor (this);
            new Thread (dp).start ();
        }
        public byte[] process (String name, byte[] b) {
            return ("request: " + name + " content="+ new String (b)).getBytes();
        }
    }
  
----

====

DirPoll has provisions to handle different kind of messages with different
priority based on its file extension, so you can call: 

[source,java]
----

    ...
    ...
    dp.addPriority (".A");
    dp.addPriority (".B");
    dp.addPriority (".C");
    ...
    ...
  
----

in order to raise ".A" priority over ".B" and ".C" requests (you can use any extension name). 

Before processing a given request, +DirPoll+ moves it to the +run+ directory,
and then either to the +response+ directory or to the +bad+  directory (in
case something goes wrong and a +DirPollException+ has  been thrown). 


[NOTE]
======

If your application crashes, you have to take care of possible requests 
left sitting in the +run+ directory. It is very important that your 
application writes the requests in the +tmp+ directory (or any other 
temporary directory in the same file system) and then moves them (after a 
proper operating system close operation) to the +request+ directory in order  
to guarantee that once a request is present in the +request+ directory, it 
is ready for DirPoll to process. 

======

[WARNING]
========
Don't trust your legacy application programmer. Please double check that the
previous note has been taken into account.
========


