1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
CouchDB-glib is a GLib-based implementation of the client side protocol for
CouchDB (http://couchdb.apache.org), a replication and synchronization
database from the Apache project.
Building
========
To build it, the following dependencies are needed:
* json-glib >= 0.7.2
* glib and gobject
* libsoup >= 2.4
To actually build it, do the following:
./configure (or ./autogen.sh if there is no configure script)
make
make install
Testing
=======
To build couchdb-glib and desktop-couch-glib and the run all the tests do:
make test
The test results are writen in tests/report.html.
The testing database will be deleted after all tests are executed. To keep
the testing database do the following and access it at
http://test:test@127.0.0.1:5985/_utils/:
make test KEEP_COUCHDB=yes
To list all available tests:
make list-tests
To run only a subset from all tests:
make test TESTPATH="/couchdb-glib/Session"
API
===
The main entry point in the API is the CouchDB object, which is needed for all
operations involving access to the CouchDB databases. To create it:
couchdb = couchdb_new (hostname);
The only argument is to specify the hostname of the CouchDB instance you want
to connect to. If NULL, it will connect to the default, which is
http://localhost:5984.
Once you have a valid CouchDB object, you can perform several operations on
databases:
* List databases -> couchdb_list_databases()
* Create a database -> couchdb_create_database()
* Delete a database -> couchdb_delete_database()
* List documents in a database -> couchdb_list_documents()
There is also a polling mechanism, which allows your application to listen
for changes on a specific database on the CouchDB instance you're connecting
to. To start listening for changes, you just need to:
* Call couchdb_listen_for_changes
* And g_signal_connect the CouchDB object to the following signals:
- "database_created"
- "database_deleted"
- "document_created"
- "document_updated"
- "document_deleted"
Documents can easily be managed by using the CouchDBDocument object, which
provides an API for creating new documents in memory and save them on a
database on the CouchDB instance you're connected to:
* Create an empty, in-memory document -> couchdb_document_new()
* Get an existing document from the database -> couchdb_document_get()
* Delete an existing document -> couchdb_document_delete()
Documents' API provides meaningful functions to manage its contents. First of
all, there are standard fields on each document, which you can set/get easily:
* Unique ID -> couchdb_document_get_id() and couchdb_document_set_id()
* Revision -> couchdb_document_get_revision() and
couchdb_document_set_revision()
* Record type -> couchdb_document_get_record_type() and
couchdb_document_set_record_type()
* Application annotations (application-specific data) ->
couchdb_document_get_application_annotations() and
couchdb_document_set_application_annotations()
Apart from those standard fields, documents can have whatever fields you need
to, so the CouchDBDocument API provides functions for setting fields of
different types:
* Booleans -> couchdb_document_get_boolean_field() and
couchdb_document_set_boolean_field()
* Integers -> couchdb_document_get_int_field() and
couchdb_document_set_int_field()
* Doubles -> couchdb_document_get_double_field() and
couchdb_document_set_double_field()
* Strings -> couchdb_document_get_string_field() and
couchdb_document_set_string_field()
There are some structured field types which are also supported:
* Structs -> couchdb_document_get_struct_field() and
couchdb_document_set_struct_field(). These use a special type,
CouchDBStructField, which in turn provides the same get/set functions
than the CouchDBDocument functions explained above.
* Arrays (not yet supported)
There are also higher level documents management functions, that internally
deal with specific record types. They are just built on top of the
CouchDBDocument API but provide an easy way to deal with those specific
record types:
* Contacts -> couchdb_document_contact_*
|