CouchCocoa: An Objective-C API To TouchDB and Apache CouchDB™

CouchCocoa is a medium-level Objective-C API for working with TouchDB and CouchDB on iOS and Mac OS. By "medium-level" we mean:

• It doesn't require knowledge of the HTTP API, only of CouchDB's architecture. You won't have to remember special paths or URL query parameters.
• But it doesn't completely abstract away the fact that you're working with a database, the way CoreData does. You still work with CouchDB-style documents and queries, although there is a CouchModel class that does some of the dirty work of mapping between documents and native objects.

This API is not the only way to access CouchDB or TouchDB -- if you prefer, you can go down to the metal and talk to the HTTP API yourself using NSURLConnection.

Kick The Tires!

• Peruse some simple code snippets!
• Explore the API documentation!

Join Us

• You can discuss this API or ask questions at the Couchbase Mobile Google Group.
• You might also want to look at the issue tracker to see known problems and feature requests.

Build Instructions

Prerequisite

Xcode 4.3 or later, with the SDK for iOS 4.3 or later.

One-Time Repository Setup

If you cloned the CouchCocoa Git repository, aso opposed to downloading a precompiled framework, then you'll next need to initialize Git "submodules". This will clone the dependency JSONKit into the "vendor" subfolder:

cd CouchCocoa
git submodule init
git submodule update

Running The iOS Demo App

Our iOS demo, "Grocery Sync", has its own GitHub repository. Check it out and look at its README for instructions.

Running The Mac OS Demo Apps

There are two simple Mac demo apps included in the Demo/ subfolder. One lets you edit a simple list of names and email addresses, the other is a shopping list. (They actually share most of the same source code; all the differences are in their model classes and .xib files, thanks to the magic of Cocoa bindings.) To run them:

1. Start a CouchDB server on localhost. (You can use a package manager like HomeBrew to install CouchDB.)
2. Open CouchCocoa.xcodeproj (in Xcode 4.2 or later)
3. Select "Demo-Addresses" or "Demo-Shopping" from the scheme pop-up in the toolbar
4. Press the Run button

Building The Framework

(You only need to do this if you checked out the CouchCocoa source code and want to build it yourself. If you downloaded a precompiled framework, just go onto the next section.)

1. Open CouchCocoa.xcodeproj
2. Select "Mac Framework" or "iOS Framework" from the scheme pop-up in the toolbar
3. Product > Build

If you want to run the unit tests, first make sure a CouchDB server is running on localhost, then choose Product > Test.

The framework will be located at:

• Mac: build/CouchCocoa/Build/Products/Debug/CouchCocoa.framework
• iOS: build/CouchCocoa/Build/Products/Debug-universal/CouchCocoa.framework

(The exact location of build itself will depend on your Xcode preferences. It may be a subdirectory of the project folder, or it may be located down in an Xcode "DerivedData" folder. One way to find the framework is to open up the Products group in the project navigator, right-click on the appropriate CouchCocoa.framework, and choose "Show In Finder".)

Using The Framework In Your Apps

Mac OS:

1. Build the Mac framework (see above).
2. Copy CouchCocoa.framework somewhere, either into your project's folder or into a location shared between all your projects.
3. Open your Xcode project.
4. Drag the copied framework into the project window's file list.
5. Add the framework to your target (if you weren't already prompted to in the previous step.)
6. Edit your target and add a new Copy Files build phase.
7. Set the build phase's destination to Frameworks, and drag CouchCocoa.framework into its list from the main project file list.

iOS:

1. Build the iOS framework (see above).
2. Copy CouchCocoa.framework somewhere, either into your project's folder or into a location shared between all your projects.
3. Open your Xcode project.
4. Drag the copied framework into the project window's file list.
5. Add the framework to your target (if you weren't already prompted to in the previous step.)

You'll probably want to run a local database server on your iOS device, since it'll allow your app to work offline (and improves performance.) CouchCocoa.framework doesn't contain CouchDB itself, so you should also add the Couchbase Mobile framework to your app. Using the two together is very simple: when the CouchbaseMobile object calls your delegate method to tell you the server's up and running, just use the URL it gives you to instantiate a CouchServer object.

License

Released under the Apache license, version 2.0.

Author: Jens Alfke

With contributions from: J Chris Anderson, David Venable, Alex McArthur, Jonathon Mah, Pierre Metrailler, Sven A. Schmidt, Katrin Apel.

Copyright 2012, Couchbase, Inc.