Quino Data Driver architecture, Part II: Command types & inputs

In part I, we discussed applications—which provide the model and data provider—and sessions—which encapsulate high-level data context.

In this article, we’re going to take a look at the command types & inputs

1. Applications & Sessions
2. Command types & inputs[1]
3. The Data Pipeline
4. Builders & Commands
5. Contexts and Connections
6. Sessions, resources & objects

Overview

Major Components of the Data
DriverBefore we can discuss how the pipeline processes a given command, we should discuss what kinds of commands the data driver supports and what kind of inputs the caller can pass to it. As you can well imagine, the data driver can be used for CRUD—to create, read, update and delete and also to refresh data.

In the top-right corner of the diagram to the right, you can see that the only input to the pipeline is an IDataCommandContext. This object comprises the inputs provided by the caller as well as command-specific state used throughout the driver for the duration of the command.

Command types

A caller initiates a command with either a query or an object graph, depending on the type of command. The following commands and inputs are supported:

• Load: returns a cursor for the objects that match a query
• Count: returns the number of objects that match a query
• Save: saves an object graph
• Reload: refreshes the data in an object graph
• Delete: deletes an object graph or the objects that match a query

Queries

A query includes information about the data to return (or delete).

• Metadata: The meta-class represents the type of the root object for the command. For example, a “person” or “company”.
• Filtering: Filters restrict the objects to return. A filter can address properties of the root object, but also properties of objects related to the root object. A caller can query for people whose first names start with the letter “m”—FirstName %~ ‘m’[2]—or the caller can find all people which belong to a company whose name starts with the letter “e”—Company.FirstName %~ ‘e’. The context for these expressions is naturally the meta-class mentioned above. Additionally, the metadata/model can also include default filters to include.
• Ordering: Orderings that determine in which order the data is returned. Orderings are also specified with the expression language, but are usually simpler, like ordering first by LastName and then by FirstName. More complex expressions are supported—for example, you could use the expression “{LastName}, {FirstName}”, which sorts by a formatted string[3]—but be aware that many data stores have limited support for complex expressions in orderings. Orderings are ignored in a query when used to delete objects.

Queries are a pretty big topic and we’ve only really scratched the surface so far. Quino has its own query language—QQL—the specification for which weighs in at over 80 pages, but that’s a topic for another day.

Object graphs

An object graph consists of a sequence of root objects and the sub-objects available along relations defined in the metadata.

It’s actually simpler than it perhaps sounds.

Let’s use the example above: a person is related to a single company, so the graph of a single person will include the company as well (if the object is loaded and/or assigned). Additionally, the company defines a relation that describes the list of people that belong to it. The person=>company relationship is complementary to the company=>person relationship. We call person=>company a 1-1 relation, while company=>person is a 1-n relation.

The following code creates two new companies, assigns them to three people and saves everything at once.

var encodo = new Company { Name = "Encodo Systems AG" };
var other = new Company { Name = "Not Encodo" };
var people = new [] 
{
  new Person { FirstName = "John", LastName = "Doe", Company = other },
  new Person { FirstName = "Bob", LastName = "Smith", Company = encodo },
  new Person { FirstName = "Ted", LastName = "Jones", Company = encodo }
};

Session.Save(people);

The variable people above is an object graph. The variables encodo and other are also object graphs, but only to parts of the first one. From people, a caller can look up people[0].Company, which is other. The graph contains cycles, so people[0].Company.People[0].Company is also other. From encodo, the caller can get to other people in the same company, but not to people in the other company, for example, encodo.People[0] gets “Bob Smith” and encodo.People[0].Company.People[1] gets “Ted Jones”.

As with queries, object graphs are a big topic and are strongly bound to the kind of metadata available in Quino. Another topic for another day.

Determining Inputs

Phew. We’re almost to the point where we can create an IDataCommandContext to send into the data pipeline.

• We have an IDataSession and know why we need it
• We know what type of command we want to execute (e.g. “Load”)
• We have either a query or an object graph

With those inputs, Quino has all it needs from the caller. A glance at the top-left corner of the diagram above shows us that Quino will determine an IMetaClass and an IMetaObjectHandler from these inputs and then use them to build the IDataCommandContext.

An IQuery has a MetaClass property, so that’s easy. With the meta-class and the requested type of object, the data driver checks a list of registered object-handlers and uses the first one that says it supports that type. If the input is an object graph, though, the object-handler is determined first and then the meta-class is obtained from the object-handler using a root object from the graph.

Most objects will inherit from GenericObject which implements the IPersistable interface required by the standard object handler. However, an application is free to implement an object handler for other base classes—or no base class at all, using reflection to get/set values on POCOs. That is, however, an exercise left up to the reader.

At this point, we have all of our inputs and can create the IDataCommandContext.

In the next part, we’ll take a look at the “Data Pipeline” through which this command context travels.