Merge branch 'master' of github.com:michaelklishin/monger

src/monger/collection.clj

@@ -153,12 +153,16 @@
 
   Please note that update is potentially destructive operation. It will update your document with the given set
   emptying the fields not mentioned in (^Map document). In order to only change certain fields, please use
-  \"$set\", for example:
+  \"$set\".
+
+  EXAMPLES
 
       (monger.collection/update \"people\" { :first_name \"Raul\" } { \"$set\" { :first_name \"Paul\" } })
 
   You can use all the Mongodb Modifier Operations ($inc, $set, $unset, $push, $pushAll, $addToSet, $pop, $pull
-  $pullAll, $rename, $bit) here, as well. Few examples:
+  $pullAll, $rename, $bit) here, as well
+
+  EXAMPLES
 
     (monger.collection/update \"people\" { :first_name \"Paul\" } { \"$set\" { :index 1 } })
     (monger.collection/update \"people\" { :first_name \"Paul\" } { \"$inc\" { :index 5 } })
@@ -167,6 +171,8 @@
 
   It also takes modifiers, such as :upsert and :multi.
 
+  EXAMPLES
+
     ;; add :band field to all the records found in \"people\" collection, otherwise only the first matched record
     ;; will be updated
     (monger.collection/update \"people\" { } { \"$set\" { :band \"The Beatles\" }} :multi true)
@@ -185,11 +191,13 @@
 (defn ^WriteResult save
   "Saves an object to the given collection (does insert or update based on the object _id).
 
-   If the object is not present in the database, insert operation will be performed:
+   If the object is not present in the database, insert operation will be performed.
+   If the object is already in the database, it will be updated.
+
+   EXAMPLES
 
        (monger.collection/save \"people\" { :first_name \"Ian\" :last_name \"Gillan\" })
-
-   If the object is already in the database, it will be updated."
+   "
   ([^String collection, ^Map document]
      (let [^DBCollection coll (.getCollection monger.core/*mongodb-database* collection)]
        (.save coll (to-db-object document) monger.core/*mongodb-write-concern*)))
@@ -201,6 +209,15 @@
 ;; monger.collection/remove
 
 (defn ^WriteResult remove
+  "Removes objects from the database.
+
+  EXAMPLES
+
+      (monger.collection/remove collection) ;; Removes all documents from DB
+
+      (monger.collection/remove collection { :language \"Clojure\" }) ;; Removes documents based on given query
+
+  "
   ([^String collection]
      (let [^DBCollection coll (.getCollection monger.core/*mongodb-database* collection)]
        (.remove coll (to-db-object {}))))
@@ -215,6 +232,14 @@
 ;;
 
 (defn create-index
+  "Forces creation of index on a set of fields, if one does not already exists.
+
+  EXAMPLES
+
+      ;; Will create an index on \"language\" field
+      (monger.collection/create-index collection { \"language\" 1 })
+
+  "
   [^String collection, ^Map keys]
   (let [^DBCollection coll (.getCollection monger.core/*mongodb-database* collection)]
     (.createIndex coll (to-db-object keys))))
@@ -225,6 +250,14 @@
 ;;
 
 (defn ensure-index
+  "Creates an index on a set of fields, if one does not already exist.
+   ensureIndex in Java driver is optimized and is inexpensive if the index already exists.
+
+   EXAMPLES
+
+     (monger.collection/ensure-index collection { \"language\" 1 })
+
+  "
   ([^String collection, ^Map keys]
      (let [coll ^DBCollection (.getCollection monger.core/*mongodb-database* collection)]
        (.ensureIndex ^DBCollection coll ^DBObject (to-db-object keys))))
@@ -238,6 +271,13 @@
 ;;
 
 (defn indexes-on
+  "Return a list of the indexes for this collection.
+
+   EXAMPLES
+
+     (monger.collection/indexes-on collection)
+
+  "
   [^String collection]
   (let [^DBCollection coll (.getCollection monger.core/*mongodb-database* collection)]
     (from-db-object (.getIndexInfo coll) true)))

src/monger/core.clj

@@ -95,5 +95,62 @@
 
 
 (defn command
+  "Available commands (please check MongoDB documentation for a complete list of commands for particular DB version.
+   Returns CommandResult.
+     Use (.ok result) to get response status.
+     It implements AbstractMap interface, so you can access it's internals:
+
+        (get (monger.core/command { :collstats \"things\") \"ns\")) ;; => monger-test.things
+
+   { :buildinfo 1 } returns version number and build information about the current MongoDB server, should be executed via admin DB.
+
+   { :collstats collection-name [ :scale scale ] } returns stats about given collection.
+
+   { :dbStats 1 } returns the stats of current database
+
+   { :dropDatabase 1 }  deletes the current database
+
+   { :findAndModify find-and-modify-config } runs find, modify and return for the given query.
+       Takes :query, :sory, :remove, :update, :new, :fields and :upsert arguments.
+       Please refer MongoDB documentation for details. http://www.mongodb.org/display/DOCS/findAndModify+Command
+
+   { :fsync config } performs a full fsync, that flushes all pending writes to database, provides an optional write lock that will make
+      backups easier.
+      Please refer MongoDB documentation for details :http://www.mongodb.org/display/DOCS/fsync+Command
+
+   { :getLastError 1 } returns the status of the last operation on current connection.
+
+   { :group group-config } performs grouping aggregation, docs and support for grouping are TBD in Monger.
+
+   { :listCommands 1 }  displays the list of available commands.
+
+   { :profile new-profile-level } sets the database profiler to profile level N.
+
+   { :reIndex coll } performs re-index on a given collection.
+
+   { :renameCollection old-name :to new-name } renames collection from old-name to new-name
+
+   { :repairDatabase 1 } repair and compact the current database (may be very time-consuming, depending on DB size)
+
+   Replica set commands
+     { :isMaster 1 } checks if this server is a master server.
+     { :replSetGetStatus 1 } get the status of a replica set.
+     { :replSetInitiate replica-config } initiate a replica set with given config.
+     { :replSetReconfig replica-config } set a given config for replica set.
+     { :replSetStepDown seconds } manually tell a member to step down as primary. It will become primary again after specified amount of seconds.
+     { :replSetFreeze seconds } freeze state of member, call with 0 to unfreeze.
+     { :resync 1 } start a full resync of a replica slave
+        For more information, please refer Mongodb Replica Set Command guide: http://www.mongodb.org/display/DOCS/Replica+Set+Commands
+
+   { :serverStatus 1 } gets administrative statistics about the server.
+
+   { :shutdown 1 } shuts the MongoDB server down.
+
+   { :top 1 } get a breakdown of usage by collection.
+
+   { :validate namespace-name } validate the namespace (collection or index). May be very time-consuming, depending on DB size.
+
+   For :distinct, :count, :drop, :dropIndexes, :mapReduce we suggest to use monger/collection #distinct, #count,  #drop, #dropIndexes, :mapReduce respectively.
+  "
   [^Map cmd]
   (.command ^DB *mongodb-database* ^DBObject (to-db-object cmd)))

test/monger/test/core.clj

@@ -33,6 +33,13 @@
 ;;         db         (monger.core/get-db connection "monger-test" "monger" "test_password")]
 ;;     (is (instance? com.mongodb.DB db))))
 
-(deftest issuing-a-profiling-command
+(deftest issuing-a-command
+  "Some commands require administrative priviledges or complex data / checks or heavily depend on DB version. They will be ommited here."
   (let [collection "things"]
-    (monger.core/command { :profile 1 })))
+    (are [a b] (= a (.ok (monger.core/command b)))
+         true { :profile 1 }
+         true { :listCommands 1 }
+         true { :dbStats 1 }
+         true { :collstats "things" :scale (* 1024 1024) }
+         true { :getLastError 1 }
+         )))