Hi! I am trying to untangle the jsieve API in order to try to document it.
Apparently, a good place to start looks like the org.apache.jsieve.SieveFactory class because: > SieveFactory is the primary invocation point for all Sieve operations. So to start me on this journey: SieveFactory has an “evaluate" method. According to the javadoc [2]: > "Method evaluate evaluates an RFC 822 [3] compliant mail message wrapped in a > MailAdapter”. (Though RFC882 is obsolete…) Ok, fine. So what is a “MailAdapter”? When I look at the javadoc of org.apache.jsieve.mail.MailAdapter [4], I see: > "Interface <code>MailAdapter</code> defines the minimum functionality > required of of a class implementing a mail message. This is the functionality > necessary to implement the Commands and Tests that RFC32028 mandates MUST be > implemented.” (I am assuming that “RFC32028” is actually RFC3028 [5], which should be updated to RFC5228 [6]). So I gather than the email must be RFC882 compliant, which means that its implementing class must also be RFC882 compliant. Further, the implementing class must also be RFC5228 compliant. So the email object must effectively be both RFC882 **AND** RFC5882 compliant. First, what is the relationship with RFC882? This is the spec for "DOMAIN NAMES - CONCEPTS AND FACILITIES”, so I’m having trouble understanding why it is relevant here. Also, for some reason the name “MailAdapter” is throwing me off. Yes, it is adapting a “mail” object, but in a way that it can be tested by a filter. So am I correct to think of “MailAdapter” as a “SieveTestAdapter” that takes a Mail as an argument? I live in Japan, where electricity is 100V. If I were to go to France, for example, where the voltage is 240V, I would not take a “100V” adapter because I already have a product that works with 100V. Rather, I would need a “240V” adapter because I want to convert my 100V product to be used with a 240V grid. So for me it is more natural to name the adapter with the thing I am adapting it to, not the thing that gets adapted. Am I understanding all this correctly? If so, then the next step to be able to explain to others how to use this library is to explain how to validate the email (and get a “RFC882CompliantMail” object, then adapt that to a “RFC5228Compliant” object). The only example I can find is org.apache.james.transport.mailets.jsieve.SieveMailAdapter, but that is bringing together so many other things that it is diverging, rather than converging, making this task much more complicated than I expected it would be. I don’t need to understand the innards of the library, just like any user of the library does not need to know every line of code. However, it would be nice to understand how to use it. Any pointers would be useful, else I will soon run out of time and energy and will have to move on to the next task. I was expecting that the code would be written in a way to make it easier to understand. Am I missing something obvious, or am I going down the wrong track? Cheers, =David [1] https://github.com/apache/james-jsieve/blob/1052708f5b00764b5e3fec39016e0abfc0bbadd4/core/src/main/java/org/apache/jsieve/SieveFactory.java#L40 [2] https://github.com/apache/james-jsieve/blob/1052708f5b00764b5e3fec39016e0abfc0bbadd4/core/src/main/java/org/apache/jsieve/SieveFactory.java#L119 [3] https://tools.ietf.org/html/rfc882 [4] https://github.com/apache/james-jsieve/blob/1052708f5b00764b5e3fec39016e0abfc0bbadd4/core/src/main/java/org/apache/jsieve/mail/MailAdapter.java#L30 [5] https://tools.ietf.org/html/rfc3028 [6] https://tools.ietf.org/html/rfc5228 --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org
