Zoe Developers FAQ

How does Zoe process a new message?
What command Line options are available?
Why Tapestry?
What about using a database instead of the current flat file system?
Where can I find documentation on the APIs of the tools Zoe relies upon?

What needs to be done?
While Zoe is a fully functional product there is a great deal of work we have planned for it.
Why Tapestry? Why not Velocity or some other template system / web application framework?
Shortly after development on Zoe was opened up to the world we explored the various technologies that could be used to replace WebObjects.  While there are many good apps out there we all pretty much agreed that Tapestry had a lot of good features and, because of its similarity to WebObjects, using it would make the port as painless as possible. We understand that most developers out there aren't familiar with Tapestry or WebObjects and that Tapestry can seem rather imposing at first, but it what we've chosen and we're sticking with it.  

How does Zoe process a new message?

Here is a little overview of how messages get processed in Zoe and who does what. I thought that might be useful when tracking down "issues"...

(1) When the application get started, the first thing that get setup is the SZServiceAgent. The service agent is the beast that will poll your emails accounts to retrieve messages. There is one service agent per "identity" (an identity being the equivalent of an user). The service agent is triggered by a Timer to do its things every now and then.

(2) When triggered, the service agent will iterate through all the SZAccount (aka email account) attached to a given identity. First, it will ask for a message uid and check if it already knows about it. If the service agent think that this is a new message it will pull it from the account and create a SZMail out of it. A SZMail is simply a thin wrapper around most JavaMail methods. It also knows how to store itself with the help of a SZMailStore. This is the only time a message is written to the file system. The message will be stored in a time line structure reflecting the message sent date. The name of the file itself is the message uuid. Once the SZMail is written is the SZMailStore, the SZMail is enqueued in an incoming queue. There is one incoming queue per identity.

(3) The SZMailProcessor kick in at that point. That's the beast that does the bulk of handling the messages and transforming them into something more structured. Once again, there is one mail processor per identity. The mail processor is an "observer" of a queue. When something get added to the queue, the processor get notified and starts doing its things. The first thing the mail processor will check is to see if there is already an SZEnvelope for a given SZMail. If there is none, the processor will create an envelope out of the mail. The envelope get created in the identity's object store. There is one object store per identity.

(4) Creating an envelope out of a mail triggers a chain of events that will decompose the original mail into its constituent parts. This is where the bulk of the work is done. A mail will get split into a dozen or so different objects. And all of those objects will get automatically indexed along the way. With all their relationships interconnected.

The End.
What command Line options are available?
What about using a database instead of the current flat file system?
This issue has come up a number of times. The main problem with using a database system is that Lucene (our search engine) can't read or write to a database. Add to that the fact that Zoe has a number of tools that make working with its files very easy and were left with 2 camps one saying "lets use a database" and one saying "why bother?" and nobody wanting to tackle the problem of Lucene not playing well with databases. So, while we're open to the idea we haven't been convinced enough to actually change the current system.  If we do however it will be with somethign like hsqldb  or maybe an object db which is lightweight and can be incorporated into the system without requiring a seperate install and configuration by users.

Where can I find documentation on the APIs of the tools Zoe relies upon?

For Tapestry, which is very similar to WebObjects and will be replacing it:

For WebObjects (which we're abandoning), there is Apple's documentation:

Lucene (the zearch engine we utilize):
There is only one class really interacting directly with Lucene:  alt.dev.szobject.SZIndex, so one could safely ignore Lucene for the  moment.