CouchDocument

bustardcelly edited this page Sep 14, 2010 · 3 revisions

CouchDocument is an extension of CouchModel and represents the Business Object of a document instance held in a database on a CouchDB server. CouchDocument has id, revision and attachment properties associated with its residence on a CouchDB server, and exposes methods to create, read, update and delete the document instance from a databse, as well as work with attachments associated with the document.

CouchDocument is meant as a base class and should be extended when working with a document on a CouchDB server. As an extension of CouchModel, CouchDocument has an associated CouchModelEntity which resolves the business layers for making service requests from a CouchDocument instance. As such, custom metadata needs to be added to any custom CouchDocument in order to auto-wire the instance to properly make requests.

Custom Annotations

The following details are a cross post from the Custom Annotations page

CouchModelEntity attempts to auto-wire Business Object models by parsing metadata related to the target database and its location, and resolving the concrete implementations of the Service Mediator and Request objects. As such, there are three custom annotations that need to be declared on any custom extension to CouchDocument. These metadata are:

  1. DocumentService
  2. ServiceMediator
  3. RequestType

DocumentService

The DocumentService metadata declares to the url of the CouchDB and the target Database name.
In the following example, the url points to the localhost at port 5984 (the default for CouchDB) and the database ‘contacts’. Any requests made will be perfomed on the ‘contacts’ database at the CouchDB location.

[DocumentService(url="http://127.0.0.1:5984", name="contacts")]

ServiceMediator

The ServiceMediator metadata declares the mediating class between a model and the service. The name argument takes a fully qualified classname of the concrete IServiceMediator implementation. CouchDocumentActionMediator is available from the as3couchdb library and can be used, or extended as seen fit.

[ServiceMediator(name="com.custardbelly.as3couchdb.mediator.CouchDocumentActionMediator")]

RequestType

The RequestType metadata delcares the interfacing request class with the service. The ICouchRequest implementation is handed to the Service Mediator in order to establish the proper handling of requests from the service.

The main purpose of the RequestType is to handle multiple runtimes and there URLRequest restrictions. The Flash Player for AIR supports PUT and DELETE requests, but such requests are not available in the web-based Flash Player. As such, HTTPCouchRequest is available in as3couchdb and uses the as3httpclientlib library to make the requests over a socket. Other implementation are ExInCouchRequest which uses ExternalInterface, and CouchRequest which makes requests without a proxy.

[RequestType(name="com.custardbelly.as3couchdb.service.HTTPCouchRequest")]

Custom CouchDocument

CouchDocument is not used directly within a project utilizing the as3couchdb library. CouchDocument is intended as a base class for a document instance within a database on a CouchDB server, and it should be extended with relative properties and custom annotations in order to be auto-wired to make service requests directly from within the Business Object.

The following is an example of an extension of CouchDcoument that relates to a document within a database named contacts on a CouchDB instance located on the localhost at port 5984 (the default CouchDB configuration):

package com.custardbelly.couchdb.example.model
{
    import com.custardbelly.as3couchdb.core.CouchDocument;
    [DocumentService(url="http://127.0.0.1:5984", name="contacts")]
    [ServiceMediator(name="com.custardbelly.as3couchdb.mediator.CouchDocumentActionMediator")]
    [RequestType(name="com.custardbelly.as3couchdb.service.HTTPCouchRequest")]
    public class ContactDocument extends CouchDocument
    {
        public var firstName:String;
        public var lastName:String;
        public var email:String;
        public function ContactDocument()
        {
            super();
        }
    }
}

The ContactDocument declares properties relevant to contact documents and, as an extension of CouchDocument, can be instantiated and interacted with to read, update and delete the document as well as any attachments associated with the document on the CouchDB server. The following example shows how you would create a new document and save it to the database on a CouchDB instance.

var contact:ContactDocument = new ContactDocument();
contact.firstName = firstNameField.text;
contact.lastName = lastNameField.text;
contact.email = emailField.text;
contact.addEventListener( CouchActionType.CREATE, handleContactSave );
contact.addEventListener( CouchEvent.FAULT, handleContactFault );
contact.create();

You can also read in a target document by passing the known unique id within the CouchDocument:read method as in the following example:

var contact:ContactDocument = new ContactDocument();
contact.addEventListener( CouchActionType.READ, handleContactRead );
contact.addEventListener( CouchEvent.FAULT, handleContactFault );
contact.read( ${known-id} );

You can also make modifications to a document and update the document on CouchDB instance as in the following example:

var contact:ContactDocument = new ContactDocument();
contact.addEventListener( CouchActionType.READ, handleContactRead );
contact.addEventListener( CouchEvent.FAULT, handleContactFault );
contact.read( ${known-id} );

protected function handleContactRead( evt:CouchEvent ):void
{
    var result:CouchServiceResult = evt.data as CouchServiceResult;
    var contact:ContactDocument = result.data as ContactDocument;
    contact.firstName = "Ted";
    contact.lastName = "Henderson";
    contact.update();
}

Deletion of a document from a database in CouchDB is also possible as in the following example:

var contact:ContactDocument = new ContactDocument();
contact.addEventListener( CouchActionType.READ, handleContactRead );
contact.addEventListener( CouchEvent.FAULT, handleContactFault );
contact.read( ${known-id} );

protected function handleContactRead( evt:CouchEvent ):void
{
    var result:CouchServiceResult = evt.data as CouchServiceResult;
    var contact:ContactDocument = result.data as ContactDocument;
    contact.delete();
}

When a CouchDocument is requested to be updated (or saved with modifications), the Service Mediator also goes about handling any modification to attachments that may have be made between reading in the document and requesting to update. You can also directly request to save all modification to documents without updating the document itself using the CouchDocument:saveAttachments method.

To learn more about attachments, visit CouchAttachment

Compilation Requirements

Due to the use of custom annotations to resolve and quto-wire business logic, some addition compilation requirements are needed.
These requirements are discussed in further detail at Compilation Requirements.