HTML and CSS Reference
In-Depth Information
Storage Engine API
Our storage engine API will be capable of performing all the basic CRUD operations:
• Create
• Read
• Update
• Delete
The API will operate on JavaScript objects. The only constraint that will be placed on an
object to be storable is that it must have a property called
id
, which will be unique within
the specific type of object (e.g. tasks).
All objects will be stored according to their defined type; for instance, tasks will be stored
under the type of “task”. If the data store did not have a concept of object-type it would
not be able to differentiate related and unrelated objects, and all objects would need to be
stored together. For instance, if the web application supported calendar events and tasks, we
would want a way of retrieving all the calendar events without retrieving the tasks. It there-
fore makes sense to store them separate from one another.
Finally, the API will work with callback functions rather than direct return values. When
calling an API method, the invoker will pass a success callback function and an error call-
back function. When the processing completes, one of these callback functions will be in-
voked, and passed the result of the processing.
The use of callbacks will allow us to support both synchronous and asynchronous storage
mechanisms. A synchronous storage mechanism is one that performs storage operations on
the main browser thread, and blocks until it is complete. An asynchronous storage mechan-
ism on the other hand may utilize background threads using the Web Worker API that will
be introduced in later chapters, or via an AJAX call to the server.
If you are not familiar with callbacks, the examples below will provide a simple introduc-
tion. Callbacks will also be used in several other APIs in the chapters that follow.
The section below provides documentation on the API that will be implemented. Up until
this point we have largely ignored the importance of well-documented code. The section be-
low therefore also serves as an example of the way an API can be documented to make it
usable to an audience beyond its creator:
/**
* The client must call this to initialize the storage engine before using it.
* If the storage engine initializes successfully the successCallback will be invoked with a null object.
