Reactivemongo Shortcuts for Play (with JSON)

Reduce code for the common cases of ReactiveMongo usage in Play framework, Scala language.

Table of Contents

• Install
• Usage
• Methods and properties
  • Collection
    • collectionName
    • defineSubCollectionName
    • collection
    • count
    • fold
    • foldM
  • Document
    • all
    • one
    • first
    • first in a set of collections
  • Field
    • fieldOpt[T]
    • field[T]
    • fieldStringOrEmpty
  • Update/Create
    • update
    • createUnique
    • insert
  • Remove
    • remove
• [Field shortcuts] (#field-shortcuts)

Install

Add the library in built.sbt

Play 2.6, Scala 2.11

libraryDependencies += "com.github.andriykuba" % "reactivemongo-shortcuts-play-json" % "2.6.1"

Play 2.5, Scala 2.11

libraryDependencies += "com.github.andriykuba" % "reactivemongo-shortcuts-play-json" % "2.5.19" 

Usage

Suppose, we want to get some field from all documents. The "native" ReactiveMongo code will look like:

def native()(implicit mongo: ReactiveMongoApi):Future[List[JsObject]] = 
  mongo.database
    .map(_.collection[JSONCollection](collectionName)).flatMap(_
      .find(Json.obj(), Json.obj("field" -> 1))
        .cursor[JsObject]()
          .collect[List](-1, 
            Cursor.FailOnError(
              (a: List[JsObject], e: Throwable) => Cursor.Fail(e))))

With the Shortcuts it will:

def shortcuts()(implicit mongo: ReactiveMongoApi): Future[List[JsObject]] = 
  all(Json.obj(), Json.obj("name" -> 1))

The Shortcuts reduce method "chaining" to one call and use Play Framework JSON to work with data.

To start use shortcuts just extend com.github.andriykuba.play.reactivemongo.shortcuts.Collection

object Users extends Collection{
  val collectionName = "users"
}

...

val allUsersInLondon = Users.all(Json.obj("city" -> "London"))

ReactiveMongoApi and ExecutionContext are passed implicitly to all methods but defineSubCollectionName. ReactiveMongo is asynchronous, so all methods but defineSubCollectionName return results wrapped in Future.

Methods and properties

Collection

collectionName

The name of the collection in MongoDB

defineSubCollectionName

Sugar for creating name of higher detailed collection. For example you need to create a collection of user's page visits and you already have the "users" collection. Good naming are:

users
users.pagevisits

So you can do:

object Users extends Collection{
  val collectionName = "users"
}

object UsersPagevisits extends Collection{
  val collectionName = "users.pagevisits"
}

Or:

object Users extends Collection{
  val collectionName = "users"
}

object UsersPagevisits extends Collection{
  val collectionName = Users.defineSubCollectionName("pagevisits")
}

collection

Shortcut for getting a collection from a database.

So this string

mongo.database.map(_.collection[JSONCollection](collectionName))

become as short as

MyCollection.collection()

count

Shortcut for getting a number of documents in the collection.

So this string

mongo.database.map(_.collection[JSONCollection](collectionName)).flatMap(c => c.count())

become as short as

MyCollection.count()

fold

Fold the collection. A start value and a fold function are set with the Folder case class. Projection and sort can also be used.

val folder = Folder(0, (count: Int, doc: JsObject) => {
  count + 1
})

MyCollection.fold(Json.obj("age" -> 20), folder)

foldM

Fold the collection asynchronously. A start value and a fold function are set with the FolderM case class. Projection and sort can also be used.

val folderM = FolderM(0, (count: Int, doc: JsObject) => {
  Future(count + 1)
})

MyCollection.foldM(Json.obj("age" -> 20), folderM)

Document

all

Find all documents. It returns a list of JsObject. Projection and sort can also be used.

MyCollection.all(Json.obj("age" -> 30))

one

Find zero or one document. It throw an exception if more than one document found. Projection can also be used.

MyCollection.one(Json.obj("name" -> "Adam Smith"))

first

Find zero or one document. It returns first document if more than one document found. Projection and sort can also be used.

MyCollection.first(Json.obj("age" -> 40))

first in a set of collections

Look for the first document in a set of collections with different selects.

Scenario to use - check if there is some document in a set of collection that meets the criteria.

Collection.first(List(
    (TrainsCollection, Json.obj("price" -> Json.obj("$lte" -> 100))),
    (BusesCollection, Json.obj("price" -> Json.obj("$lte" -> 100))),
    (PlanesCollection, Json.obj("price" -> Json.obj("$lte" -> 100)))))

Field

fieldOpt[T]

Get an optional field from a single document. Throw an exception if more than one document is found. Field type T is obligatory.

MyCollection.fieldOpt[Int](Json.obj("name"->"Adam Smith"), "age")

field[T]

Get a field from a single document. It throws an exception if no document or field are found. Throw an exception if more than one document is found. Field type T is obligatory.

MyCollection.field[Int](Json.obj("name"->"Adam Smith"), "age")

fieldStringOrEmpty

Get a string field from a single document or empty string if no document or file was found. Throw an exception if more than one document is found.

MyCollection.fieldStringOrEmpty(Json.obj("name"->"Adam Smith"), "address")

Update/Create

update

Update matching document (using findAndModify). This method is also used for document creation (upsert = true).

MyCollection.update(
  Json.obj("name"->"Adam Smith"), 
  Json.obj("$set" -> Json.obj("age" -> 80)))  
  
  
MyCollection.update(
  mySelector, 
  myDocument,
  upsert = true)   

createUnique

Finds some matching document and creates new document if nothing found. It throws a DocumentAlreadyExists exception otherwise

MyCollection.createUnique(
  Json.obj("name"->"John Silver"), 
  Json.obj(Json.obj("age" -> 40)))   

insert

Inserts a document into the collection and wait for the results.

val document = Json.obj("name"->"Adam Smith")

MyCollection.insert(document)  

Remove

remove

Remove matching document (using findAndModify). Return true if document was removed or false if it was not found.

MyCollection.remove(Json.obj("name"->"Adam Smith"))  

Field Shortcuts

In beta, look the source code of the FieldShortcuts object