Zoe's Frameworks

 Here is a quick introduction to the main 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.

- 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:
doc 1
doc 2


- SZQualifier. Clone of EOQualifier, but generalized for Java. Build on
top of SZKeyValue. Check Apple's documentation for a description.


- 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.

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 obj