Commits

David Carr committed dc0d44f

docs: add some package-level documentation

Comments (0)

Files changed (1)

src/main/java/org/bitbucket/davidm24/mongodb/aggregate/package-info.java

+/**
+ * Extends the MongoDB Java Driver to provide an easier syntax for working
+ * with the
+ * <a href="http://docs.mongodb.org/manual/applications/aggregation/">Aggregation Framework</a>.
+ * 
+ * <p>For example, the
+ * <a href="http://docs.mongodb.org/manual/tutorial/aggregation-examples/">Aggregation Framework Examples</a>
+ * include the following "Largest and Smallest Cities by State" JavaScript
+ * example:
+<pre>db.zipcodes.aggregate(
+        { $group: {
+                _id: { state: "$state", city: "$city" },
+                pop: { $sum: "$pop" }
+        } },
+        { $sort: { pop: 1 } },
+        { $group: {
+                _id: "$_id.state",
+                biggestCity: { $last: "$_id.city" },
+                biggestPop: { $last: "$pop" },
+                smallestCity: { $first: "$_id.city" },
+                smallestPop: { $first: "$pop" }
+        } },
+        { $project: {
+                _id: 0,
+                state: "$_id",
+                biggestCity:  { name: "$biggestCity",  pop: "$biggestPop" },
+                smallestCity: { name: "$smallestCity", pop: "$smallestPop" }
+        } } )</pre>
+ * Using this library (and a helper method newMap), this could be written in
+ * Java as:
+<pre>AggregateBuilder.aggregate(db.getCollection("zipcodes"))
+        .group(GroupBuilder.start()
+                 .put("_id").to(newMap("state", "$state", "city", "$city"))
+                 .put("pop").sum("$pop")
+                 .get()
+        )
+        .sort(newMap("pop", 1))
+        .group(GroupBuilder.start()
+                .put("_id").to("$_id.state")
+                .put("biggestCity").last("$_id.city")
+                .put("biggestPop").last("$pop")
+                .put("smallestCity").first("$_id.city")
+                .put("smallestPop").first("$pop")
+                .get()
+        )
+        .project(newMap(
+                "_id", 0,
+                "state", "$_id",
+                "biggestCity",
+                newMap("name", "$biggestCity", "pop", "$biggestPop"),
+                "smallestCity",
+                newMap("name", "$smallestCity", "pop", "$smallestPop")
+        ))
+        .run();</pre>
+ * As may be clear from this example, use of the aggregation framework goes a
+ * lot more smoothly with easy ways to create maps.  In Groovy, this isn't an
+ * issue, as a concise map syntax is built into the language.  In Java, one
+ * alternative is to use
+ * <a href="http://code.google.com/p/guava-libraries/">Guava</a>'s
+ * <a href="http://docs.guava-libraries.googlecode.com/git-history/release/javadoc/com/google/common/collect/ImmutableMap.html">ImmutableMap</a>
+ * class (and associated builder).</p>
+ * 
+ * @author David M. Carr
+ * @see <a href="http://docs.mongodb.org/manual/reference/aggregation/">Aggregation Framework Reference</a>
+ * @since 0.1.0
+ */
+package org.bitbucket.davidm24.mongodb.aggregate;