bustardcelly edited this page Sep 14, 2010 · 14 revisions

as3couchdb Library

The as3couchdb project is a lightweight library for communicating with a CouchDB server. The library aims to address the following concerns when interacting with CouchDB while targeting the Flash Platform:

  1. Perform simple CRUD requests on Database and Documents held within a CouchDB instance.
  2. Implement a structure that resembles Data Access Objects to simply instantiate and modify Business Objects from which CRUD requests can be made.
  3. Still allow for direct service requests to be made without Business Objects.
  4. Provide a means to manage Session Cookies to enforce authentication when performing requests.
  5. Enjoy working with an open source NoSQL database.

Project Overview

The as3couchdb provides the ability to communicate with a CouchDB server directly using Business Objects. The Business Objects available in as3couchdb expose methods that relate to CRUD requests. The methods invoke a Data Access Object (referred to as a Service Mediator in as3couchdb) that communicates with a service proxy to make REST calls on CouchDB. On successful response of a request, the Business Object is updated with any appropriate data returned.

The core Business Objects of as3couchdb are to be extended with custom metadata to ensure the proper wiring of the Data Access layer. These core Business Objects are:


Please visit those pages for example code on how to extend them for a project that uses the as3couchdb library.

The construct of an as3couchdb Business Object is at its base a CouchModel that contains a CouchModelEntity used to auto-wire the Business Object based on custom metadata. The custom metadata, as well as compilation requirements, are discussed in:

Custom Annotations

Service Mediators (similar to Data Access Objects) are the middle tier in the service layer and are auto-wired into the document and database models when they are instantiated wither from a return result from the service or directly by the user. The ServiceMediator is responsible for requesting a command object related to HTTP request from the service proxy and executing the request with any appropriate Action Responders.

Action Responders are lightweight classes that know how to read and write proper JSON returned or passed, respectively, to the CouchDB in a request.

Custom extensions to the as3couchdb library can be made to provide custom Service Mediators and subsequent Action Responders with regards to the requirements of your project.

Within the service proxy layer, resides a context of a Request Type. Typed as an implementation of ICouchRequest the Request Object is responsible for forming a proper request and invoking the CouchDB server. This, as well, can be customized as requirements for your project dictate. The reason for its inclusion within the service layer is to allow you the ability to make true CRUD requests using the as3httpclientlib library when running your application in the browser player. Included in the as3couchdb library are the following ICouchRequest implementations:

  1. HTTPCouchReqest which uses the as3httpclientlib to perform CRUD requests over a Socket.
  2. ExInCouchRequest which is a very simple example on using External Interface as the proxy layer for the service.

Authentication and Sessions

Without authentication in place, anyone can access and modify documents and databases within a CouchDB instance. It is ultimately up to you to manage that validation of user context and access rights from within your CouchDB instance. However, as3couchdb allows for requesting a session for a user that is kept persistent (and updated in the background) between requests.

To read more about how as3couchdb handles sessions, visit CouchSession.

Library Dependencies

The following is a list of libraries that as3couchdb uses in order to reliably make a receive request on a CouchDB instance:

The as3couchdb library requires the as3corelib project.
The classes from the as3corelib project that as3couchdb utilizes is SHA1 for generating unique ids
on the client side, and JSON for serializing objects for CouchDB service communication.

The as3crypto library is used by the as3httpclient (see above requirement).

The as3couchdb library requires the as3httpclientlib project.
as3couchdb utilizes the as3httpclient API to make proper PUT and DELETE requests on the CouchDB instance.
as3httpclient has a dependency on the following libraries: as3corelib and as3crypto.

Road Map

The following is a list of items intended to be addressed in following releases:

  1. Ensure that as3couchdb works with latest release of CouchDB.
  2. Revision info and Conflicts for core models.
  3. Replication API refinement.
  4. Extensions for creation and upload of design view documents.
  5. AIR library to provide online/offline synchronization with CouchDB.