README.txt - james-jspf - Git at Google

 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
	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