svn commit: r576223 - /james/jspf/trunk/README.txt

[ba...@apache.org]

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