An Introduction To Zoe Frameworks

Note from David Medinets: I took this information from an email on the Zoe Developer Mailing List.

Here is a quick introduction to the different frameworks used across ZOE

SZFoundation

This is mostly plumbing related stuff: things that are missing from the Java API that I need. Here are a couple of more or less significant ones:

SZCache: A simple cache Map that uses soft references for its values on top of a LRU schema. Basically handle caching automatically based on the vm memory situation.
SZClassLoader?: This class mimic the "standard extension" mechanism by defining a classpath at runtime. It also allow one to "patch" existing Java class. Very handy. Allows one not to have to deal with classpath madness at all.
SZDate: A java.util.Calendar wrapper that play nicely along key value coding (see SZKeyValue?).
SZDBM: This is a class found at w3c that implement a dbm data structure in Java. A kind of persistent Map.
SZFormatter: Simple formatter class cluster (java.text.Format never did it for me...)
SZKeyValue?: A pure Java implementation of NSKeyValueCoding?. This one is important to understand as it is the backbone of many of ZOE's functionality. Check the Apple's documentation for an indepth explanation [1]
SZLog: A simple logging mechanism. Uses stack trace to provide the log context.
SZNotification: A notification mechanism (related conceptually to Observer/Observable but without the need to subclass anything). Check Apple's documentation for more details: [2] [3]
SZQualifier: Clone of EOQualifier, but generalized for Java. Build on top of SZKeyValue?. Check Apple's for a description: [4]
SZQueue: A persistent queue that uses the file system for storage. Implement Observable for change notification.
SZString: A bunch a pretty lame string manipulation.

SZObject

This is the persistency layer. Uses a mix of Java serialization and Lucene indexing to simulate a relational object graph. The persitency layer is conceptually related to EOF. Check Apple's documentation for more information: [5]

Here are some highlights:

SZDescription: Provides runtime information between the persistency layer and the objects to archive/index (eg which keys to index, what to serialize, time line inf and so on).
SZFinder: Internal class that query Lucene indexes given a SZQualifier. Mostly translate a qualifier info a Lucene query. Not for public consumption.
SZID: Persistent global id that uniquely represent an object. Think about it as a persistent object pointer.
SZIndex: Internal class handling Lucene IndexWriter/Reader?/Searcher and so on. Not for public consumption.
SZIndexer: Internal high level indexing helper class that extract values from an object for indexing purpose. Not for public consumption.
SZObject: Concrete implementation of SZPersistent interface. All the SZMail classes are subclass of this beast.
SZPersistent: Bare minimum interface that a persistent object needs to implement. See SZObject for an example. You basically need to know how to handle a SZID and a SZStore.
SZRecord: Internal object representation of an object: a Map and a SZID. This data is serialize in a SZStorage. Not for public consumption.
SZSpecification: This class define what to "fetch" from the persistency layer. It take a class and a qualifier and is resolved by SZStore. This is the only way to query object out of the object store.
SZStorage: Very private class that handles the storage of SZRecord in a SZDBM. Not for public consumption.
SZStore: An object store. Each persistent object lives in one and only one of this beast. The object store act as a facade to the rest of the persistency layer. This is the only public API for accessing/querying/manipulating persistent objects.
SZTimeline: An helper class to query object through a time line (eg give me some objects for a point in time).

SZText

This framework is not used in the open source version of ZOE. I build it to translate WordNet? structures into Lucene indexes and put an object facade on top of WordNet?. The only class used by the rest of ZOE is the SZText utility class. Mostly string manipulation based on java.text.

SZMail

This is the real "business logic" for ZOE. It simply turns every possible email elements (eg address, parts, and so on) into an object.

SZAccount: Represent account information: eg zoe@ma... + password + services information. That's what one edit in the "account" preference panel.
SZAddress: Represent an email address.
SZCard: Represent a vCard. Subclass SZDocument.
SZContentType?: Describe a mime content type.
SZDocument: Object wrapper for a "document". Email themself are document subclasses.
SZDocumentDecoder?: Utility class to decompose a javax.mail.Part into its different components. For internal use only.
SZDomain: The domain part of an email address (eg @mail.com)
SZEnvelope: The main class of SZMail. Modelize an email.
SZHTMLParser: An utility class to extract text from html. For internal use only.
SZIdentity: Define an "identity" for the system: eg a user and password. SZAccounts are attached to an identity. ZOE does not provide any UI to create identity for the moment. It only provide means to automatic create a default identity. You need an identity to be able to do anything in the system.
SZLink: Description a relation ship between two email address. The premiss of "social networking". This is used internally to show which email address is "related" to another. For internal use only.
SZList: Modelise a "mailing list".
SZMail: A lame wrapper around a lot of Java Mail functionality. Knows how to store itself in a SZMailStore? and retrieve its content. Private. The official API to access messages is SZEnvelope.
SZMailer: Object wrapper around user-agent info.
SZMailProcessor?: This is the workhorse of the system. It will process incoming messages and turn them into objects. There is a mail processor per identity. SZServiceAgent? populate the incoming queue and mail processor works on it.
SZMailStore?: This class handle the storage of SZMail objects.
SZName: Modelize the concept of a "person". Uses some heuristics to extract personal information from email addresses and attempt to consolidate them.
SZNote: A "note" object. Does not really belong to SZMail. Allow to "annotate" any persistent object. The UI for it is still missing in ZOE :-(
SZOrganization: The equivalent of SZName but for domains. Try to map domains to an "organization" using some lame heuristics.
SZPart: Equivalent of SZMail, but for a javax.mail.Part. Mostly used to access attachments. Private.
SZProvider: Abstract class that mimic Java Mail Provider: eg a service and transport like IMAP and SMTP.
SZReply: Handles "reply" management and message "threading". Very lame for the moment.
SZSearch: Place holder to access the GoogleAPI?. Not used because I don't know how to get a Google id automatically.
SZService: Wrapper around Java Mail different service type: IMAP, POP, ...
SZServiceAgent?: Utility class that will fetch message from a SZService: eg retrieve emails from your POP account. This class simply fetch the entire message, create a SZMail out of it and add it to the incoming queue. The message processing itself is done in SZMailProcessor?.
SZSMTP: Light weight SMTP server. Can be used to import messages by simply sending them directly to ZOE and/or forward messages to a real SMTP server and keep ZOE in the email loop. Used mostly to integrate ZOE with your existing SMTP server as to capture outgoing messages. Interact an outgoingQueue and SZTransportAgent? for messages processing.
SZURL: Lame class to wrap and extract URLs from random text. Pretty ugly. Needs to be reworked from the ground up.

mbox