james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From b...@apache.org
Subject svn commit: r576223 - /james/jspf/trunk/README.txt
Date Mon, 17 Sep 2007 00:22:51 GMT
Author: bago
Date: Sun Sep 16 17:22:51 2007
New Revision: 576223

URL: http://svn.apache.org/viewvc?rev=576223&view=rev
Log:
Added some basic code documentation to README (is this the best place?).

Modified:
    james/jspf/trunk/README.txt

Modified: james/jspf/trunk/README.txt
URL: http://svn.apache.org/viewvc/james/jspf/trunk/README.txt?rev=576223&r1=576222&r2=576223&view=diff
==============================================================================
--- james/jspf/trunk/README.txt (original)
+++ james/jspf/trunk/README.txt Sun Sep 16 17:22:51 2007
@@ -46,5 +46,70 @@
 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 2 stacks: the "checkers" Stack and the "catchers" Stack. The former
contains
+the "to be processed" SPFChecker, the latter contains SPFCheckerExceptionCatcher.
+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 an SPFCheckerExceptionCatcher is retrieved from the
catcher
+stack and executed to handle the 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



---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org


Mime
View raw message