Skip to content

1. DAO

Jump to bottom
shturec edited this page Oct 26, 2017 · 26 revisions

Class: DAO

Module: daoism/dao

Usage

The DAO is designed to build upon a configuration describing your entities and the relations between them and then expose the CRUD operations that you might need to manage and query these entities.

To illustrate how to use DAOs in DAOism, let's use a domain model for forums and first start with the concept forum Topic. A relational model description for a very simple topic would look like this:

Table: TOPIC
Fields: { Name:"ID", Type: "BIGINT", PK: true, Not Null: true},
        { Name:"DESCRIPTION", Type: "VARCHAR", Size: 255, Not Null: true}

In our application we want to work with Topic JSON entities that represent the data records in table TOPIC that will have the following Json Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "type": "object",
      "properties": {
         "id": {"type": "integer"},
         "description": {"type": "string"}
     },
     "required": ["id","description"]
   }

To create a DAO that will automatically provision and manage the data records from TOPIC as JSOn objects in our application we supply the following configuration

var topicORM = {
	"dbName": "TOPIC",
	"properties": [{
		"name": "id",
		"dbName": "ID",
		"type": "Long",
		"id": true
	}, {
		"name": "description",
		"dbName": "DESCRIPTION",
		"type": "String",
		"size": 255,
		"required": true
	}]
}

We are ready to create a DAO with this configuration

var topics = require('daoism/dao').get(topicORM);

And now, let's put it to good use:

//create a new topic
var topicId = topics.insert({"description": "my topic description"});

//get a topic by id
var topic = topics.find(topicId);

//list all topics
var topicsArr = topics.list();

// update a topic
comments.update({"description": "updated description"});

// delete a topic
topics.remove(topicId);

That was easy!

However, normally you have related entities in your model. And automating relationships is one of the outstanding things about DAOism too.

Let us now add another concept in our domain model - Comment. Each Topic composes a set of zero or more Comments. A generic description of the Comment model in terms of Relational Model would be the following:

Table: COMMENT
Fields: { Name:"ID", Type: "BIGINT", PK: true, Not Null: true},
        { Name:"TOPIC_ID", Type: "BIGINT", Not Null: true},
        { Name:"TEXT", Type: "VARCHAR", SIZE:255, Not Null: true}

The JsonSchema of Topic application entity will change accordingly to allow an array of comments as one of its properties:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "type": "object",
      "properties": {
         "id": {"type": "integer"},
         "description": {"type": "string"},
         "comments": {
           "type": "array",
           "items": {
             "type": "object",
             "properties": {
                  "id": {"type": "integer" },
                  "topicId": {"type": "integer"},
                  "text": {"type": "string"}
             },
             "required": ["id","topicId","text"]
           }
         }
     },
     "required": ["id","description"]
   }

And the JSON schema for Comment is the following:

{
   "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
   "properties": {
      "id": {"type": "integer"},
      "topicId": {"type": "integer"},
      "text": {"type": "string"}
  },
  "required": ["id","topicId","text"]
}

The DAOism configuration for Topic will also change to comprise some settings about its relationship with Comment and we need to add another one for Comment too:

  • Topic
var topicORM = {
	"dbName": "TOPIC",
	"properties": [{
		"name": "id",
		"dbName": "ID",
		"type": "Long",
		"id": true
	}, {
		"name": "description",
		"dbName": "DESCRIPTION",
		"type": "String",
		"size": 255,
		"required": true
	}],
	"associations": [{
		"name": "comments",
		"type": "one-to-many",
		"joinKey": "topicId",
		"targetDao": function(){ ...}
	}]
}
  • Comment
var commentORM = {
  "dbName": "COMMENT",
  "properties": [
    {
      "name": "id",
      "dbName": "ID",
      "type": "Long",
      "id": true
    },
    {
      "name": "topicId",
      "dbName": "TOPIC_ID",
      "type": "Long",
      "required": true
    },
    {
      "name": "text",
      "dbName": "TEXT",
      "type": "String",
      "size": 255,
      "required": true
     }
   ]
}

With these two configurations now we can create the corresponding DAOs again:

  • Topic DAO
var topics = require('daoism/dao').get(topicORM);
  • Comment DAO
var comments = require('daoism/dao').get(commentORM);

And make use of them:

//create a new topic
var topicId = topics.insert({"description": "my topic description"});

//create a comment for topic
var commentId = comments.insert({"topicId": topicId, "text": "my comment for topic 1"});

//list all topics with their comments inline in the topic objects. Note that the DAO will automatically find the related entities and provide them inline as 'comments' arrays
var topicsWithComments = topics.list({expand:true});

// delete a topic and its comments. Note that the DAO will automatically cascade the delete command to the depending comment entities
topics.remove(topicId);

Class API

Constructor

  • DAO

Properties

  • $log
  • datasource
  • orm
  • ormstatements

Methods

  • createSQLEntity transformation factory that creates a db record entity out of application entity. Invokes the dbValue callbacks configured for each property if any.

  • createEntity transformation factory that creates an application entity out of db record

  • validateEntity Utility function used by methods that take entity as input to validate it for availability of mandatory fields. Allows for skipping some fields as instructed e.g. for the insert use case where an id property is not expected although it is marked as implicitly required in the configuration.

    • entity
    • skip Array[String] array of names of the properties that should be excluded from availability validation in this entity

  • insert

    • entity Object | Array

      Insert a new data record for the argument entity (or data records if the supplied argument is an array of entities).

      Returns Object | Array

      The id of the created entity or an array of ids for the created entities if the function argument is an array.

  • update

    • entity

  • remove

    • ids

  • expand

    • expansionPath
    • contextEntity

  • find

    • id

  • count

  • list

    • $expand
    • $filter
    • $select
    • $sort
    • $order
    • $limit
    • $offset

  • createTable Creates a database table based on this DAO configuration

  • dropTable Drops the database table referenced by this DAO configuration

Clone this wiki locally