Api

The Fressian API is a logical API, and should be implementable in most modern languages. For ease of exposition, this documentation here uses the concrete reference implementation language (Java).

Reading and Writing

The primary interface to Fressian is the Reader and Writer interfaces. These interfaces will have concrete instantiations in a host language, e.g. in Java they are named FressianReader and FressianWriter. The concrete classes should be used only for their construction/factory methods.

Extensibility

Fressian can be extended to custom types by implementing ReadHandler and WriteHandler. WriteHandlers are made available to the Writer via an ILookup implementation that takes the class of the object being written, and returns a map from the tag string to the WriterHandler. ReadHandlers are made available to the Reader via an Ilookup implementation that takes the object being read, and returns a ReadHandler for that object.

Handling Unknown Tags

If a Fressian reader encounters a tag it does not recognize (i.e. no ReadHandler is available), it must return an instance of TaggedObject.

Caching Objects

There are two way to request than an object be cached. You can call the writeAs method with cache set to true to explicitly cache an object. Or, you can wrap an object in an instance of Cached, which will cause the wrapped object to be cached. The Cached wrapper is intended for the case where an object is nested inside some other object or collection, to request caching even when the writer for the container did not request it.