Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 

README.md

Scala Cloudant client for Spray/Akka

Build Status

Motivation

Why another library? Most of the Cloudant/CouchDB libraries I've came across are overly complicated, and require a bit of a learning curve to use. Error handling and debugging response unmarshalling error wasn't very pleasant. They do have some really nice and advanced features, but I didn't really require them. Since I'm using Spray, and Cloudant already provide a HTTP API, it was fairly straight forward to create a new client library.

About 200 lines of Scala later, here is it.

Features

  • CRUD for Database/Document/Bulk/Index/Views and Search Index/View method are provided.
  • Everything returns a Future[String] by default, this is the raw JSON response from Cloudant.
  • Unmarshalling is optional, with a .unmarshalTo[T] convenience method provided.
  • Exceptions (CloudantException) will come through the usual Future.failed channel.

Usage Example

Just extend the CloudantOps trait and the cloudant operations will be available.

class FoodService extends Actor with CloudantOps {
      // Alternatively: CloudantCredential(username, accountname, password)
      implicit val cloudantCred = new CloudantCredential(username, password)
      implicit val dbName  = "myDB"
      
      // Create doc via JSON directly
      // Notice _id and _rev field is omitted, this will create a new document.
      val doc = """{"food": "Pizza"}"""
      val response1: Future[String] = createOrUpdateDoc(doc)
      
      // Create doc via object
      case class MyFood(food: String)
      val myFood = MyFood("Pizza")
      val response2: Future[String] = createOrUpdateDoc[MyFood](myFood)
      
      // Create doc via object, then unmarshall the response
      val response3: Future[MyResponseType] = createOrUpdateDoc[MyFood](myFood).unmarshalTo[MyResponseType]
}

The best documentation is the code itself, it'll only take 2 minutes to glance through the code.

Client API Available

DB CRUD Operations
  • createDb
  • retrieveDb
  • retrieveAllDbs
  • deleteDb
Doc CRUD Operations
  • createOrUpdateDoc
  • createOrUpdateOrDeleteBulkDoc
  • retrieveDoc
  • deleteDoc
Index/View Operations
  • createOrUpdateIndex
  • createOrUpdateView
  • searchIndex
  • searchView

Unsupported Operations

  • Retrieve all doc on a DB
  • Retrieve DB changes
  • Querying view by composite key

Installing the client

Check Maven Central for the latest published version.

Maven Central

Maven

<dependency>
    <groupId>com.clianz</groupId>
    <artifactId>spray-cloudant_2.11</artifactId>
    <version>0.1.3</version>
</dependency>

SBT

libraryDependencies += "com.clianz" % "spray-cloudant_2.11" % "0.1.3"

Transitive Dependencies

This library uses Scala 2.11, Spray/Akka, and the Shapeless library (via Spray-json-shapless).

com.clianz:spray-cloudant_2.11:jar:0.1-SNAPSHOT
+- org.scala-lang:scala-compiler:jar:2.11.7:compile
|  +- org.scala-lang:scala-library:jar:2.11.7:compile
|  +- org.scala-lang:scala-reflect:jar:2.11.7:compile
|  +- org.scala-lang.modules:scala-xml_2.11:jar:1.0.4:compile
|  \- org.scala-lang.modules:scala-parser-combinators_2.11:jar:1.0.4:compile
+- com.typesafe.akka:akka-actor_2.11:jar:2.4.4:compile
|  +- com.typesafe:config:jar:1.3.0:compile
|  \- org.scala-lang.modules:scala-java8-compat_2.11:jar:0.7.0:compile
+- io.spray:spray-client_2.11:jar:1.3.2:compile
|  +- io.spray:spray-can_2.11:jar:1.3.2:compile
|  |  \- io.spray:spray-io_2.11:jar:1.3.2:compile
|  +- io.spray:spray-http_2.11:jar:1.3.2:compile
|  |  \- org.parboiled:parboiled-scala_2.11:jar:1.1.6:compile
|  |     \- org.parboiled:parboiled-core:jar:1.1.6:compile
|  +- io.spray:spray-httpx_2.11:jar:1.3.2:compile
|  |  \- org.jvnet.mimepull:mimepull:jar:1.9.4:compile
|  \- io.spray:spray-util_2.11:jar:1.3.2:compile
\- com.github.fommil:spray-json-shapeless_2.11:jar:1.2.0:compile
   +- io.spray:spray-json_2.11:jar:1.3.2:compile
   +- org.slf4j:slf4j-api:jar:1.7.16:compile
   \- com.chuusai:shapeless_2.11:jar:2.3.0:compile
      \- org.typelevel:macro-compat_2.11:jar:1.1.1:compile

Spray-routing version

As mentioned in the official Spray documentation, if you are using Spray-routing, then you need the version built for shapeless.

This library was tested with:

io.spray:spray-routing-shapeless2_2.11:jar:1.3.2

About

Scala Cloudant client for Spray/Akka

Resources

License

Packages

No packages published

Languages

You can’t perform that action at this time.