Property Sets

All applications need a way to define the data structures they use. This definition can be more or less formal depending on the needs of the application, how widely it will be used, what other systems will interact with it, and so on.

Data in the Casbah Virtual Namespace ranges from having no predefined semantics, i.e., just some dictionary at some Casbah Virtual Namespace path, to being very strictly defined by a class definition in Java or another language. We borrow the term "property set" to describe the structure of the data you expect to be at a path that is more well defined than nothing and much less strict than an object class definition.

A property set, then, is just a way to describe what someone should expect to find at a path in Casbah Virtual Namespace or in a CaDict passed to a method.

A common Casbah property set would be the definition of the result of calling __cb_info__ on some Casbah driver:

If we called this set of properties the "driver-info property set" then we could discuss the result of calling __cb_info__ simply as the "driver-info object", while still knowing that this is not a real language object (in fact, it's a CaDict or equivalant).

The expected values of properties can include dictionaries, lists, atomic or primitive values, objects, or other property sets. It's perfectly acceptable that the type of the value of a property may be different in different circumstances; for example, the From property of a mail message may be "either a string in RFC-822 format or a person or organization object containing at least an email property and optionally a name property".

Property sets may also be objects in the sense that they may have a class and methods available with them. An important characteristic of this type of object is that it may have additional properties beyond the typical class, and it's possible that required properties are in fact undefined or missing (most Natroun drivers won't do instance member validation on objects created in the Casbah Virtual Namespace).

What follows is a definitive list of the characteristics of property sets that set them apart from objects and otherwise undefined dictionaries:

1. property sets may or may not have behavior associated with them (object methods)

2. property sets have required and optional properties

3. property sets are not validated at creation or modification time, and may or may not be fully populated when they are initially created (it's up to called routines to verify that properties they require are present and of the correct type)

4. instances of a property set can be created by just creating tables in the Casbah Virtual Namespace, in addition to methods that may be able to build them

5. instances may be conform to multiple property sets at the same time (i.e. a table containing a person's info may conform to the "email user" and "employee" property sets)

6. instances may or may not be explicitly typed (i.e. a dictionary passed as a mail message to a send routine doesn't need an explicit type)

   1. it's not yet defined what attribute would be used to hold the type(s) of property sets an instance conforms to, since it may be more than one. How would that be handled if the property set was an object?

   2. A convention we can use for documenting standard property sets will look a lot like a class defintion:

      NAME
      
       mail-message -- a property set for holding mail messages
      
      SYNOPSIS
      
       # Properties common (inherited) from `message'
          from     -- string or person object
          date     -- date message was sent
          subject  -- subject of message (plain text)
      
       # Properties specific to mail messages
          to       -- string or person objects
          received -- ordered list of sites this message passed through
      
      DESCRIPTION
      
       Mail messages . . .