Database

Data persistence services are provided by MongoDB on the server and accessed using the dojo.data interfaces on the client.

Links

API

Factory functions

uow.data.getDatabase(args) → dojo.Deferred

This method opens a database collection for use in your application. You can call this function any number of times to open connections to different databases and collections and with different modes of access (e.g., read, write, etc.)

The args parameter must have the following attributes configuring your access to the database:

database (string)
Name of the database to access.
collection (string)
Name of the collection in the database to access or * to list collections.
mode (string)
Permissions requested for accessing the database. If mode is left undefined, crudO is requested and granted for developers while non-developers get what they are allowed for the collection (see uow.data.setAccess). The mode string can contain one or more of the following characters representing permissions:
  • c : Create records
  • r : Read records with any query
  • R : Restricted read that allows only simple equality queries that return a single record
  • u : Update existing records
  • d : Delete records
  • O : Override ownership checks on delete and update operations

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive a uow.data.MongoStore instance for your use.

Note: The modes granted may not match the modes requested. The intersection depends on the permissions allowed for the user role using uow.data.setAccess or an equivalent function. You can invoke the getMode method on the uow.data.MongoStore instance to determine what permissions were actually granted.

Create operations record the current user's id in the _owner field. Delete and Update operations fail unless the _owner is equal to the current user id or _owner is null or Override has been granted.

Records are checked in two ways on create and update operations. First they are checked against the schema if one is provided. Then, any strings values are filtered to protect against common XSS attacks. If the field name ends with HTML, the content is filtered against a white list that only allows a subset of tags and attributes. In all other string valued fields, the characters <, >, ", ' and & (outside of entities) are replaced with HTML entities. If you have some very rare case where these transformations will be a problem, you should encode your data before saving it to the db.

uow.data.manageDatabase(args) → dojo.Deferred

This method allows you to list and delete the collections in a database. You can call this function any number of times to manage different databases.

The args parameter must have the following attribute identifying which database you want to manage:

database (string)
Name of the database to access.

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive a uow.data.MongoStore instance with delete and read permissions for your use in listing and dropping collections in the database.

uow.data.setAccess(args) → dojo.Deferred

This function sets the permissions allowed for a user role when accessing a given database and collection. Only those permissions allowed here will be granted to a user in the named role when accessing the database / collection pair using uow.data.getDatabase.

The args parameter must have the following attributes identifying the database, collection, and user role to configure:

database (string)
Name of the database.
collection (string)
Name of the collection on which to set the allowed permissions.
role (string)
User role name on which to set the allowed permissions.
permission (string)
Permission to allow user's of the role to request. The permission string can contain one or more of the mode characters defined for the uow.data.getDatabase function. Alternatively, it can be null to remove all granted permissions.

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive the record created, updated, or deleted in the Admin:AccessModes collection defining the allowed permission.

uow.data.setRole(args) → dojo.Deferred

This function assigns a associates a user's Open ID with a role. The association exists across all databases and collections on the server.

The args parameter must have the following attributes identifying the user and role:

user (string)
Open ID (i.e., email address) of the user
role (string)
One of the assigned role names defined by uow.getUser, namely author or admin, or null to remove the user / role association.

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive the record created, updated, or deleted in the Admin:AccessUsers collection defining the role association.

uow.data.setSchema(args) → dojo.Deferred

This function sets the JSON Schema for all future records in a given collection. When a schema exists, only those operations that produce items deemed valid by the schema are allowed. All other operations are denied.

The args parameter must have the following attributes identifying the database, collection, and schema:

database (string)
Name of the database.
collection (string)
Name of the collection.
schema (string)
JSON schema to enforce for future record creation and updates or null to remove the schema and allow items with arbitrary structure in the collection.

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive the record created, updated, or deleted in the Admin:Schemas collection defining the schema.

uow.data.touchCollection(args) → dojo.Deferred

This function creates a new, empty collection in a database. Normally, you do not need to invoke this function as the collection is brought into existence when you write the first record to it. This function is useful, however, if you need a collection to appear when fetched using uow.data.manageDatabase.

The args parameter must have the following attributes identifying the collection to create:

database (string)
Name of the database to access.
collection (string)
Name of the collection to create.

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive a uow.data.MongoStore instance for the new collection with crud permissions.

uow.data.MongoStore class

MongoStore is a subclass of dojox.data.JsonRestStore which implements the read, write, identity, and notification interfaces of dojo.data. MongoStore instances expose additional methods beyond those defined by the basic dojo.data interfaces. These convenience methods are listed below.

deleteOne(args) → dojo.Deferred

This method deletes one and only one record matching a query from the open collection.

The args parameter must have the following attributes identifying the item to delete:

query (object)
Name / value properties to match when searching for the item
save (bool)
True to commit the deletion to the server if successful, false to only perform the delete locally until a later save()

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive the deleted item or an error if zero or more than one items match the query.

fetchOne(args) → dojo.Deferred

This method gets one and only one record matching a query from the open collection.

The args parameter must have the following attributes identifying the item to fetch:

query (object)
Name / value properties to match when searching for the item

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive the matching item or an error if zero or more than one items match the query.

getMode() → string

This method returns the permissions actually granted on the opened collection. It takes no parameters.

The return value is a string containing a subset of the mode characters crRudO defined in the uow.data.getDatabase documentation above.

putOne(args) → dojo.Deferred

This method updates one and only one record matching a query in the open collection or creates it if no records match.

The args parameter must have the following attributes identifying the item to update or create:

query (object)
Name / value properties to match when searching for the item
data (object)
Name / value properties to replace or add to the exiting item, or the properties to include (along with the query properties) on the newly created item
save (bool)
True to commit the update or creation to the server if successful, false to only perform the update / create locally until a later save()

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive the updated or created item or an error if more than one items match the query.

updateOne(args) → dojo.Deferred

This method updates one and only one record matching a query from the open collection.

The args parameter must have the following attributes identifying the item to update:

query (object)
Name / value properties to match when searching for the item
data (object)
Name / value properties to replace or add to the exiting item
save (bool)
True to commit the update to the server if successful, false to only perform the update locally until a later save()

The return value is a dojo.Deferred. You should invoke then on the deferred to register a callback function that will receive the updated item or an error if zero or more than one items match the query.

Examples

Save a new person object in the rolodex collection of the catalog database

var def = uow.data.getDatabase({
  database: 'catalog', 
  collection : 'rolodex', 
  mode : 'c'
});
def.then(function(db) {
  var fn = dojo.byId('db_ex1first');
  var ln = dojo.byId('db_ex1last');
  db.newItem({firstName : fn.value, lastName : ln.value});
  db.save();
  fn.value = ln.value = '';
});

Get 5 person objects from the rolodex collection in the catalog database

var def = uow.data.getDatabase({
  database: 'catalog', 
  collection : 'rolodex', 
  mode : 'r'
});
def.then(function(db) {
  var i = 1;
  db.fetch({
    count: 5,
    onBegin: function() {
      dojo.byId('db_ex1log').innerHTML = 'Fetching.\n';
    },
    onItem: function(item) {
      var text = dojo.replace('{i}. {item.lastName}, {item.firstName}\n', 
        {i: i++, item : item});
      dojo.byId('db_ex1log').innerHTML += text;
    },
    onComplete: function(items) {
      dojo.byId('db_ex1log').innerHTML += 'Done.\n';
    },
    onError: function(e) {
      dojo.byId('db_ex1log').innerHTML += 'Kaboom. Bad things happened.\n';
    }
  });
});