On 19/05/2020 09:14, David Leangen wrote: > Hi, > > I am having a bit of trouble distinguishing the jsieve API from its > implementation. It is my intention to document this project, but I find it > more difficult to understand than it ought to be because of this problem. > > If the library is small enough and the integration simple enough, then > perhaps it really doesn’t matter. However, for somebody like me who wants to > understand the library, reducing the API surface area is really helpful. > Honestly, I take a glance at the code and it is not immediately obvious to me > what this is about, or how I could use it. I don’t want to have to spend too > much time trying to document it. This is way more difficult than it ought to > be for such a “simple” library. 😅 > > Perhaps if users only need to create an actual sieve filter an never interact > with the code, then maybe it doesn’t matter, but the library still needs to > be integrated somehow with a system. How the heck is that done?
Well, I worked several years ago on refreshing the JSieve <=> James server code, thus I have a quite good idea of how to integrate the JSieve library. The SieveFactory class allows to parse a Sieve script. (We miss an intermediate form, "DOM" object that is domain oriented, clearly, in order not to 'leak' the underlying parsing to the end user...) First, you need JSieve (which is system agnostic) to understand what you define as a Mail. Then you need to specify how to perform some actions. One need to implement the given actions as part of its "mail server. This is done through the MailAdapter class, and the EnvelopeAccessors class. An example can be found in James code: SieveMailAdapter. Given a SieveMailAdapter, and a parsed Sieve script, the SieveFactory `evaluate` method will trigger the actions. James usage can be found in `SieveExecutor::sieveMessageEvaluate` method. Also, you might be interested by the Sieve scripts part of James test suite, which might be good examples of Sieve scripts: SieveIntegrationTest & server/mailet/mailets/src/test/resources/org/apache/james/transport/mailets/delivery content could help. > > My “dumb” understanding is that it is just an implementation of a spec [1]. > So, shouldn’t this library then just have an API that matches the spec, and > then an implementation against the API? (Indeed, likely the only, but it is > still usually worthwhile to have a clean separation between API and > implementation. I guess this would like be the reference implementation for > the Java API.) As stated above we in my opinion miss an intermediate "DOM" structure describing the SIEVE script. Then the script evaluation is server dependant as we need indirection on what a mail is, and how to carry out the actions. Maybe the right model to make the evaluate method friendlier here would be to : - Parse the Sieve script as a DOM object - Given a DOM object, and a Mail representation, then JSieve returns a List of actions that the callers would need to carry out. Then we don't need to "push" knowledge of how to execute Sieve scripts actions to JSieve, and would likely makes integration friendlier. > > Is there anybody here who knows this library well who can comment and give me > some direction? Did the above examples and thoughts helped you? > Refactor to better separate API from implementation to allow easier use of > this library? > > — OR — > > Don’t touch this! Leave as is because nobody needs to know anyway? Well, this is in my opinion not critical at all. I would open a JIRA about API evolution discussion, and avoid touching this in the meantime. After what I just wrote, promoting JSieve to 1.0.0 might be too early... > Cheers, > =David > > [1] 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 > --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org
