CouchDatabase

CouchDatabase is an extension of CouchModel and represents the Business Object of a database instance in a CouchDB server. CouchDatabase has properties associated with its residence on a CouchDB server, and exposes methods to create, read, and delete the database instance, as well as a few convenience methods to access data related to the database.

CouchDatabase is meant as a base class and should be extended when working with a database on a CouchDB server. As an extension of CouchModel, CouchDatabase has an associated CouchModelEntity which resolves the business layers for making service requests from a CouchDatabase instance. As such, custom metadata needs to be added to any custom CouchDatabase 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 CouchDatabase. 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. CouchDatabaseActionMediator is available from the as3couchdb library and can be used, or extended as seen fit.

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

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 CouchDatabase

CouchDatabase is not used directly within a project utilizing the as3couchdb library. CouchDatabase is intended as a base class for a database instance on a CouchDB server, and it should be extended with 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 CouchDatabase that relates to 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.CouchDatabase;
    [DocumentService(url="http://127.0.0.1:5984", name="contacts")]
    [ServiceMediator(name="com.custardbelly.as3couchdb.mediator.CouchDatabaseActionMediator")]
    [RequestType(name="com.custardbelly.as3couchdb.service.HTTPCouchRequest")]
    public class ContactDatabase extends CouchDatabase
    {
        public function ContactDatabase()
        {
            super();
        }
    }
}

The ContactDatabase can be instantiated and interacted with as in the following example which creates the database on a CouchDB instance. If the database already exists in the CouchDB instance, it is just read in. Else, it is created and read in. In both cases, clients are notified with a CouchEvent event object with an action type of CouchActionType.CREATED:

…

var database:CouchDatabase = new ContactDatabase();
database.addEventListener( CouchActionType.CREATE, handleCouchDatabaseReady );
database.createIfNotExist();

…

private function handleCouchDatabaseReady( evt:CouchEvent ):void
{
    database.addEventListener( CouchActionType.READ_ALL, handleReadAllDocuments );
    // Pass the class type to resolve payload documents to.
   database.getAllDocuments( "com.custardbelly.couchdb.model.ContactDocument" );
}

Along with creation, you can request a simple read in of a database instance and also delete directly from the CouchDatabase model extension. There are also a couple convenience methods on CouchDatabase that relate to documents associated with the database, such as requesting documents from a specific view of to request them all in bulk, such as is seen in the example on a request for CouchDatabase:getAllDocuments. With that invocation, a fully qualified classname of the document type class to resolve results to is passed.

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.