Sedona

Index | Prev | Next

Schema

Overview

Because the Sedona Framework is designed to work in very constrained embedded environments, we have to make design tradeoffs. One of the biggest tradeoffs is using a low level binary format for Sedona Framework application files and the Sox protocol. These binary formats require out-of-band information for encoding and decoding. For example the binary formats assume you know how kit, type, and slot ids map to their definitions. We must also design for versioning since kit schemas evolve over time to include new types and new slots.

Kit Checksums

Every kit contains zero or more named types. Each type declares zero or more slots. For a given version of a kit, there is a fixed list of types and their declared slots. Each slot has a fixed name, flags, and type. When a kit is compiled from source into a kit zip file, the compiler generates a checksum for this fixed list of types and slots. The combination of a kit name and checksum is called a kit part.

The kit meta-data, checksum, and list of types and slots is included in the kit file as an XML file called "manifest.xml". Here is an example manifest file: 

<?xml version='1.0'?>
<kitManifest
   name="sysTest"
   checksum="da52f78f"
   version="1.0"
   vendor="Tridium"
   description="Test suite for core language and sys APIs"
   buildHost="BLAZE"
   buildTime="2007-05-17T16:21:08.030-04:00"
>

<type id="0" name="AbstractTestComp" base="sys::Component">
  <slot id="0" name="az" type="bool"/>
  <slot id="1" name="ai" type="int"/>
</type>

<type id="1" name="TestComp" base="sysTest::AbstractTestComp">
  <slot id="0" name="z1" type="bool"/>
  <slot id="1" name="b1" type="byte"/>
  <slot id="2" name="addF1" type="float" flags="a"/>
</type>

<type id="2" name="SubTestComp" base="sysTest::TestComp">
  <slot id="0" name="sb" type="byte"/>
  <slot id="1" name="si" type="int"/>
</type>

</kitManifest>

The checksum is based only on the kit's types and slots. The checksum is not based on variable meta-data such as the kit's version number. This means that multiple versions of the same kit might share the same checksum if no types or slots have been modified. Don't confuse version with checksum. Version represents a revision of the whole kit including its code, algorithms, and when it was built. Checksum represents a revision of the declared types and slots.

Kit Database

Within a Sedona Framework installation we store all the local copies of kits with the file pattern: 

{home}/kits/{kit}/{kit}-{checksum}-{version}.kit
{home}/kits/control/control-cdf5f0f0-1.0.29.kit

We call this directory the kit database. It can store multiple concurrent versions of each kit. The sedona.kit.* APIs are used to work with the kit database.

Manifest Database

Kits always contain the manifest information we need when working with schema. However, to interface with the kit we don't need the full kit file, only the XML manifest inside of it. So in addition to the kit database, we also store a manifest database with the file pattern: 

{home}/manifests/{kit}/{kit}-{checksum}.xml
{home}/manifests/control/control-cdf5f0f0.xml

By pulling the manifests out into a separate database, we don't require the full kit file to work with the kit's types. This is typically more efficient, and it allows a manufacturer to only publish the manifest versus the whole kit file.

The sedona.manifest.* APIs are used to work with manifests and the manifest database via the Java toolkit. The KitManifest class represents the information stored a kit manifest file and provides methods for encoding and decoding from XML. The ManifestDb class is used to load and save KitManifests to the file system.

Schemas

A Sedona Framework runtime image or application is composed of multiple kits. A specific list of kit parts (kits at a specific checksum revision) is called a schema. Matching schemas guarantee binary compatibility.

Only when a kit manifest is pulled into a specific schema do we know information such as kit id and slot id. For example the kit id for "control" might be 3 in one schema, and 5 in another schema that has a different list of kit parts. Slot ids might also change for a given kit part across schemas depending on the slots inherited from base types.

The sedona.* APIs are used to work with schemas via the Java toolkit. Schemas are built with the sedona.Schema class from a list of KitParts that are resolved against the manifest database. Assuming all the kit parts can be resolved to kit manifests, we can build a complete representation of the schema including the full list of kits, types, and slots along with their respective ids. The Schema is then used to work with binary formats such as ".sab" files and Sox messages.

Resolving Manifests

The recommended rules for resolving a given kit name and checksum to a manifest:

  1. Check the local manifest database first, if found use it;
  2. Check the local kit database, if found then copy the manifest to the local manifest database for the next time around;
  3. Download the manifest from Internet via sedonadev.org to the local manifest database;

Steps 1 and 2 are automatically implemented by the ManifestDb API.

Kits versus Manifests

So when do you need a kit and when do you only need a manifest? This table helps summarize the differences:

Encapsulates Versioned By Uses
Manifest type and slot schema checksum sax, sab, and sox
Kit code version number compiling dependencies and scode images

For example when working with an application file or Sox, only the type schemas are needed. No knowledge of the internal code is required. However when compiling, you need the full kit that contains the actual code. So a manifest is somewhat analogous to a C header file, which declares function prototypes but does not contain any code for the functions.

Manifests are versioned with a checksum each time a type or slot definition is modified. Kits are versioned with a version number typically whenever code is modified.

Review

To summarize the schema pipeline:

  1. Checksum: Generated by the compiler when compiling a kit file from source, the checksum is based on the declared types and slots in the kit.
  2. Kit Part: The combination of kit name and kit checksum that uniquely identifies a kit for a specific schema revision.
  3. Kit Manifest: A file containing a kit's checksum and type definitions, stored as a zip archive entry named "manifest.xml".
  4. Kit Database: A database of all local kit versions, created and maintained by the Sedona Framework Java toolkit.
  5. Manifest Database: A database of all the different kit manifests that have been accumulated, created and maintained by the Sedona Framework Java toolkit. These manifests are XML files keyed by kit name and checksum.
  6. Schema: A list of kit parts aggregated by the Sedona Framework Java toolkit. A schema defines the full meta-data required to work with binary format entities with matching schemas. Each Sedona Framework runtime and application file has a single, fixed schema. The Java toolkit can model multiple schemas simultaneously via the sedona.Schema API.
Index | Prev | Next