DB8 Basics

DB8 is a storage method of webOS TV. DB8 is designed to meet the needs of robust, high-performance apps. DB8 is a service available on Luna Bus, and interfaces to an embedded JSON database. To find out information on how to call this service from an app or service, see Database API or Media Database API

Forgive us, we will assume that you have a basic knowledge of database concepts and SQL in our explanation about the following topics:

Main DB8 Features

Main DB8 features include:

  • Enabling high speed access and queries.

  • Storing JSON objects. JSON (JavaScript Object Notation) is derived from JavaScript and is the de facto web app standard for persisting data (more compact than XML).

  • App-aware access control.

  • Paging support for queries that can retrieve up to 500 objects at a time.

  • Support for change notification.

  • Data object validation through schema enforcement.

Getting Started

To use DB8 storage in your code, follow the steps provided below.

  1. Determine what you are going to store in DB.
  2. Determine what your indices are going to be. This is very important, as the indices you create determine the type of queries you can make.
  3. Use the putKind() method to create a kind. Now your app can store data objects in the kind created.
  4. Start storing your data with the put() method.

DB8 JSON Objects

DB8 stores two types of JSON objects:

  • Kind object: Think of this as what we casually call 'table' in DB. This object defines the owner, schema, and indexes for JSON data objects. In DB8, these objects are known as kinds. Before a data object can be saved, its defining kind object must be stored and registered with the putKind() call.
  • Data object: JSON object of a particular kind that contains data. It is similar to objects that are instances of classes in object-oriented programming.
JSON is a lightweight data-interchange text format based on a subset of the JavaScript programming language that is easy for humans to read and write and for machines to parse and generate. Like XML, JSON contains name/value pair collections and ordered list of values (i.e., arrays).

For JSON object format and more information about JSON, see the following websites:

JSON object format in brief:
  • Curly brackets ('{', '}') are used to enclose objects.
  • Angle brackets ('[', ']') are used to enclose arrays.
  • Colons (':') are used as name/value delimiters.
  • Quotes (") are used for string values. Numeric and boolean values do not require quotes.

Example

Let's see some object examples to help your understanding. Before creating a kind object, we will determine what we will store in DB, as guided in the Getting Started. Let's create a DB for contacts. We will store contact information in DB.

Data Object

After a thorough discussion, we have decided to store a contact information that would look like this:

{
    "displayName"  : "John Doe",
    "name"         : {"familyName":"Doe", "givenName":"John"},
    "nickname"     : "Skippy",
    "emails"       : [ "jdoe@gmail.com", "john.doe@palm.com", "jdoe99@gmail.com" ]
}

The definition of the above JSON object would look like this:

{
    "displayName" : string,
    "name"        : {
        "familyName" : string,
        "givenName"  : string
    },
    "nickname"    : string,
    "emails"      : string array
}

Kind Object

Before we store data objects we defined above, we need a "table" to store the data objects. You can create a kind object using the putKind() method. The parameter of this method would look something like this:

{
    "id"      :  "com.yourdomain.contact:1",
    "owner"   :  "com.yourdomain.contacts",
    "extends" :  ["PimObject:1"],
    "indexes" :  [{"name":"dname", "props":[{"name":"displayName"}]}]
}

The properties of the kind object are as follows. These properties can be defined when registering a kind with putKind() method.

Property Description
id Version number and is required. A number (i.e., ":1")  is appended to the end of the property value field. Initially, this number should be "1" and DB Service would increment it whenever a version of this kind is updated that is not backward-compatible with previous versions.
extends For inheritance. Kinds can extend other kinds. In the above example, the contacts kind extends from PimObject kind.
owner Owner app ID. Only the owner has permissions to modify the kind.
indexes Determines the type of queries you can make. Refer to DB8 Index for more information. In the above example, only one index is defined.

Special Properties

There are some special properties that DB8 assigns to objects. These are delineated with an underscore ('_') based on JSON DB conventions. Because of this, apps cannot create properties that start with an underscore.

Currently, the following special properties are assigned to stored objects. 

Special Property Description
_id An object's globally unique identifier. This is assigned even if an object is contained in another object. If not already assigned, the database assigns one. Meant to be an opaque object within a JSON object and it is, therefore, advised your code not make any assumptions about this field.
_rev Each object instance (regardless of object type) in DB8 database maintains a globally-unique revision counter that is incremented after every object update or change. DB8 service assigns this counter to an object everytime the object is modified. No two objects can ever have the same value for this property. You can use this number as a base point for syncing and in your queries, i.e., "Give me all the changes that were made to contacts since the revision number from yesterday's update."
_kind Your are required to assign this string kind identifier. Common practice is using the owner app id.

Here is a sample contacts object assigned with the special properties:

{
    "_id"          : "2+n4",
    "_rev"         : 276,
    "_kind"        : "com.yourdomain.contact:1",
    "displayName"  : "John Doe",
    "name"         : {"familyName":"Doe", "givenName":"John"},
    "nickname"     : "Skippy",
    "emails"       : [ "jdoe@gmail.com", "john.doe@palm.com", "jdoe99@gmail.com" ]
}

Atomicity & Optimistic Concurrency

For updating an object, atomicity means that either all of it takes place and is committed to the database, or none of it is. 

 

In DB8, all updates (i.e. inserting or deleting multiple objects) done in a single method call are atomic. Batch operations that combine multiple operations atomically are NOT supported.

 

App-level transactions are not supported. Doing so would allow database locks to be held for a long period of time, potentially blocking other applications, including those the user is waiting on.

 

You can implement a form of optimistic concurrency to ensure atomicity. This would involve the following steps:

  1. Get an object and note its revision value (_rev).
  2. Modify the object.
  3. Perform a conditional merge operation with a query that specifies the object's id and revision values (_id and _rev).
  4. If the revision number has changed, indicating it has been modified, repeat the cycle and try again.

 

Navigation