More about the proposed API approach...
The Honeycomb fixed content system operates on object data, which is stored and retrieved in bulk operations, and on metadata, which is structured and searchable. Object data streams through the client library opaquely, and a well-defined data hash (SHA1) is returned for verification purposes. Metadata records are constructed and accessed by named fields. The stored representation of metadata records on the Honeycomb system is not exposed to the user, and no hash is returned when storing metadata.
The Honeycomb client API provides programmatic access to a Honeycomb system to store, retrieve, query and delete object data and metadata. The XAM API provides this same capability, but is on it's way to becoming a standard. The source code allows you to use either interface, however the XAM API is still changing up until the standard is released.
The Honeycomb server stores two types of data: arbitrary object data and structured metadata records. Every metadata record is associated with exactly one data object. Every data object has at least one metadata record. A unique object identifier (OID) is returned when a metadata record is stored. The OID can later be used to retrieve the metadata record or its object data. In addition, metadata records can be retrieved by a query:
OID <~----> Metadata Record ~----> Object Data
There are two types of metadata, system metadata and user metadata. The names and types of system metadata are predefined and cannot be overridden by the user.
A user metadata record consists of a set of attributes. The set of possible attributes is defined by the schema. There is only one schema per Honeycomb system. The Honeycomb emulator loads its schema from an XML file. The metadata_merge_config utility can be used to extend the default schema, generating a new XML file read by the emulator.
Metadata Records
You can associate structured data with object data in the form of metadata records. Each metadata record applies to one data object. There is a many-to-one relationship between metadata records and data objects. Each metadata record consists of a set of name and value pairs, where name is a string and value is typed. The available names and the types of their values are enumerated in the schema.
Honeycomb OIDs
When object data and metadata are stored, or when metadata is added to an existing data object, a 56-character hexadecimal OID is returned. This OID is unique on a particular Honeycomb server, and you can use the OID to retrieve the object data or metadata. You can also retrieve an OID using the query operations.
Delete Semantics
Calling delete on an OID deletes the corresponding metadata record from the Honeycomb server. When a data object's last metadata record is deleted, the data object is also deleted.
Query Syntax
The Honeycomb client API provides a query mechanism to find metadata records matching a query string. For simple queries, the mechanism returns the OIDs of matching metadata records. For query-plus queries, you supply a select clause, and the query mechanism returns those metadata attributes. Note that matches are on a per metadata record basis, so multiple metadata records for the same underlying data object might be returned. Also, all conditions must be satisfied inside a single metadata record?that is, metadata record attributes are not transitive across the metadata records for a given data object.
Honeycomb Client/Server Communication
The Honeycomb client communicates with the server over HTTP. The Java and C clients use the same protocol.
Query Language
The Honeycomb Query Language defines a subset of SQL for retrieving metadata records and their corresponding object data from a Honeycomb server. The Honeycomb Query Language is similar to the unified SQL that is supported through JDBC and contains many SQL-like features.