Welcome to Apache James jSPF
============================

Apache James jSPF is an Apache 2.0 licensed java library that implements the SPF specification.

There are 2 main entry points to the library:
1) The SPFQuery command line tool
2) The SPF class, for programmatic use


SPFQuery
--------
You need jspf library, dnsjava and log4j libraries in your classpath, then you run
> java -jar jspf-version.jar
to get the usage.


SPF
---
Here is a simple usage of the library:

DefaultSPF spf = new DefaultSPF();
SPFResult res = spf.checkSPF("192.168.0.1", "from@example.com", "example.com");
if (res.getResult().equals(SPF1Utils.FAIL_CONV)) {
 ... do something ...
} else if (res.getResult().equals(SPF1Utils.PASS_CONV)) {
 ... something else..
} else .....
Further results are:

PERM_ERROR_CONV = "error";
NONE_CONV = "none";
TEMP_ERROR_CONV = "temperror";
PASS_CONV = "pass";
NEUTRAL_CONV = "neutral";
FAIL_CONV = "fail";
SOFTFAIL_CONV = "softfail";


Links
-----
http://www.openspf.org/ for the latest informations about SPF
http://james.apache.org/jspf/ for the jSPF website, javadocs, xdocs and more.


Please help us make jSPF better - we appreciate any feedback you may have.
Enjoy!


Developer notes
===============

*Module Dependencies Layers*
----------------------------

jSPF source code is structured in 4 layers. The topmost layer is the org.apache.james.jspf.impl
package and it depends on every other package in the sources.

Then we have a second layer including the "executor" package, the "policy"+"policy.local" packages, 
the "parser" package and the "wiring" package. "executor", having no dependencies in the third 
layer could be included in both the second and the third layer. "wiring" does not have dependencies.

The third layer includes only the "terms" package. It depends on "core" (the fourth layer).

The fourth layer includes "core"+"core.exceptions" packages. They have no dependencies on other
packages. Instead every other package depends on this code.

*Mixed Synchronous/Asynchronous Implementation*
-----------------------------------------------

jSPF born as a synchronous implementation, but soon introduced asynchronous support via dnsjnio
asynchronous dns resolver library. The "Continuation" pattern has been used to support asynchronous
operations.

The whole processing is defined by "SPFChecker"s. An SPFChecker is an object that takes an SPFSession and 
applies the needed transformations. Whenever a DNS lookup is needed an SPFChecker is allowed to return 
a DNSLookupContinuation. A DNSLookupContinuation simply tells the executor that a given DNSRequest should  
be resolved and the DNSResponse should be returned to the given SPFCheckerDNSResponseListener (that in  
turn is allowed to return DNSLookupContinuation if it needs DNS lookups). When an SPFChecker (or the 
SPFCheckerDNSResponseListener) completed the processing it will return null.

The SPFSession includes a checkers stack: A checker can also implement the SPFCheckerExceptionCatcher
interface to be able to intercept exceptions from the nested checkers.
The SPFExecutor role is to pop an SPFChecker from the SPFSession and execute it, by processing the
DNSRequests included in the returned DNSLookupContinuations until a null is returned. If an exception
is thrown by the current checker then the executor will poll every checker from the stack looking for
a checker implementing the SPFCheckerExceptionCatcher interface, will remove it from the stack and
will execute its onException method to handle the exception.
Please note that the SPFCheckerExceptionCatcher call wil often result in an additional exception to be
rethrown and the executor will take care to pop the chekers looking for another catcher that will handle
the new exception.

Terms, Policies and the Parser are all implementations of the SPFChecker interface. An SPFChecker
implementation can do every processing in the checkSPF method or can simply push more fine grained
SPFCheckers to the checkers Stack in the SPFSession.

*Packages*
----------

core: includes the core classes for the jSPF library.

wiring: an utility package used to "wire" components for the runtime. It has no dependencies.

terms: depends on core and defines basic Mechanism and Modifiers (Directive) terms. The terms simply
  implements one of the Mechanism / Modifier interfaces and contain a static property to define
  the regular expression used to parse the term from the record. 

parser: the RFC4408SPF1Parser is the core class and it creates an SPF1Record by parsing the spf record.
  the "grammar" is automatically created by reading the jspf.default.terms file that define the known
  Modifiers and the known Mechanisms. At startup every modifier/mechanism is analyzed and a big
  regexp is built to parse the records. Every time a record is parser the TermsFactory is used to
  obtain a Service-Wired instance of the term.

executor: an SPFExecutor (defined in the core package) is an object that process an SPFSession and 
  returns an SPFResult (when asynchronous executors are used the SPFResult returned will be a 
  FutureSPFResult). The executor 

---------------------
The Apache James team