Diligence is still under development and incomplete, and some this documentation is wrong. For a more comprehensive but experimental version download the Savory Framework, which was the preview release of Diligence.
Discussion Feature
This feature lets you attach a "forum" to any MongoDB document. It could be a Page from the Wiki Feature, a blog post, or just anything in your application. Of course, permissions apply, and you can allow, for example, for registered users to post new threads and have "visitor" users (Facebook, Twitter, etc.) only the right to comment. The discussion is threaded, in that comments can have any level of depth. It's very easy to drop in, and makes a lot of web application features instantly sociable.
Usage
Make sure to check out the API documentation for Diligence.Discussion.
Editable Graph Structures in MongoDB
If you'll take a look at Diligence's Ext JS tree integration, you'll see it's pretty neat. It's literally neat because the trees for Ext-JS are immutable, and easily stored in a MongoDB document, which can hold a structure of arbitrary depth. However, if you want your tree to change by multiple users and threads, document databases such as MongoDB begin to show some of their limitations. (Graph databases, such as neo4j, are of course perfect for this use case.)
Nevertheless, it's not impossible, and can get excellent all-around performance for mutability. How is this solved for the Discussion Feature? MongoDB's atomic operations do not support such recursion, so we needed a different method. You can see ideas on the MongoDB trees page.
After some consideration, we used a variation of the "materialized paths" pattern. We have the forum posts stored as plain array, with each having a path as well as a parent field. We parse this document on load, to give it a tree-like structure more amenable to work with. The flat storage structure, however, allows for easy use of MongoDB's atomic update operation. For each post, we store a "nextResponse" running serial. We update it atomically with $inc for each new post, to make sure it's unique, and append that number to the parent's path to create the new path. We then add the new response using MongoDB's $push. The result is that any number of users can respond at the same time to the same forum, and each response takes only two MongoDB write operations, only one of which waits for the response. We're guaranteed atomicity and uniqueness of each path ID.
A graph DB would do this better, but the real comparison would be to a relational database. Just two writes, but the whole forum is read with one read. We think this counts as a smashing success!
You'll notice a rule of thumb we've applied here, useful in general when working with MongoDB: if in relational database you always want your tables to be normalized, in document databases your goal is to use as few documents as possible. In this case, the entire forum is embedded into one document (together with the document's other data, if there is any). The document limit in MongoDB is 4MB, easily adequate for such discussions. But, what if you want a more open forum, with no limitations on size? Well, the Discussion Feature also comes with a forum implementation that stores each thread in post in its own document, or even each post in its own document. All use the same API. Mix and match for the best performance and growth ability suitable for your needs.
The Diligence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.
