Hi David.
It looks like you struggled much with badly written javadoc...
> (I am assuming that “RFC32028” is actually RFC3028 [5], which should be
> updated to RFC5228 [6]).
That typo needs to be fixed.
> 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.
Likely none.
Reading "RFC3028"
```
This document describes a language for filtering e-mail messages at
time of final delivery.
```
Emails refers to SMTP here, and the closer relevant RFC number I can get is
RFC-821 SIMPLE MAIL TRANSFER PROTOCOL
RFC-822 STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES seems
related to too. And given the "one number mistake rule" is likely what
the javadoc author intended to reference.
Clearly I would advocate referencing a "modern" SMTP RFC like RFC-5321,
with the wording "represent a e-mail messages at
time of final delivery as per RFC5321"...
> 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?
+1
> 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?
I think you proved the current JSieve API to be badly designed.
We would need to rework it to make its usage easier.
And this should be likely done before documenting it (why invest in
documentation that will outdate itself?)
Given our previous exchanges I **propose** a first step:
- As part of JSieve provide a `MailAdapter` class, that "just
represent" a mail. It would be a Plain Old Java Object (POJO) along with
it's builder. (it adapts a mail within JSieve context)
- The SieveFactory takes a SieveScript inputstream, and a Mail adapter,
and returns a list of Action that results from the sieve script
execution against the supplied email.
-
Given the following proposal a usage examples would look like:
```
void runSieveScript(JamesMail jamesMail, InputStream sieveScript) {
MailAdapter mailAdapter = MailAdapter.builder()
.subject(jamesMail.getSubject)
.to(jamesMail.headers().to())
...
.build();
List<Action> actions = sieveFactory.evaluate(sieveScript, mailAdapter);
// Do stuff with the actions
}
```
That way library users don't need to extend anything, interacts with a
simple POJO they need to populate, and can implement the actions they
want to support. This makes the entire API easier to discover. And it
looks achievable with limited investment.
I also believe documenting that will be easier.
If there is no objection, I will create a JIRA as an output of this
discussion.
I just want to conclude that, by challenging what exists, you are far
from loosing your time. You might very well have been initiating the
most important contribution to the JSieve library in the past few years.
Cheers,
Benoit
>
> 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: [email protected]
> For additional commands, e-mail: [email protected]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
