Models in 2.0

Some design notes for re-implementing model objects in CBL 2.0.

Goals

• Don't require a fixed base class — developers may want to have their own.
• Allow nested models — models based on subdocuments.
• Better performance.
  • Read/write Fleece directly without expanding the entire doc to an Obj-C object tree.
  • Make models independent of CBLDocuments, at least for property access.

Design

CBLModel

Models are declared as protocols, inheriting from a base CBLModel protocol we provide. All properties declared in model protocols are considered persistent.

Any class that implements a model protocol can be used as a model class. (But we could supply a CBLModel base class, if it makes development simpler for clients who don't care about custom base classes.)

The persistent properties must be synthesized, as they will automatically by default. If the @synthesize statement specifies an instance variable name, then that name (minus any "_" prefix) will be used as the document property name, instead of the Objective-C property's name. (This is a bit of a hack, but it's an easy way to let developers use different property names, which is essential if the JSON property name is not a valid C identifier.)

Using @synthesize instead of @dynamic is a change from 1.x. It lets us take advantage of the efficient getter/setter methods created by the compiler, which access an instance variable. Otherwise we'd have to provide side storage of our own, or dynamically translate the Fleece value into Objective-C every time the getter is called.

Properties declared in a model class are not persistent. (This might be confusing, but I think model classes will often have transient properties, and there's no clear way to tell whether a property declared in a class is meant to be persistent or not.)

Inheritance is supported:

• Model protocols can inherit from (one or more) other model protocols, not just directly from CBLModel.
• Model protocols can inherit from non-model protocols as well; properties inherited from them are not persistent.
• Model classes can implement more than one model protocol.

CBLModelFactory

As in 1.x, the class CBLModelFactory manages models for a database. It's reachable from the database's modelFactory property.

In 2.0 the factory has additional responsibilities: models with custom base classes won't inherit methods like -save: or -revert:, so the factory needs to provide them.