Package com.cloudant.client.api.views

This package provides access to the view API.

See: Description

Interface Summary

Interface	Description
AllDocsRequest	The AllDocsRequest is used for getting an AllDocsResponse
AllDocsRequestBuilder	Interface for building an unpaginated _all_docs request.
AllDocsResponse	Encapsulates a response from an _all_docs request.
MultipleRequestBuilder<K,V>	Interface for building ViewMultipleRequests.
PaginatedRequestBuilder<K,V>	Interface for building a paginated ViewRequest.
RequestBuilder<RB>	Parent interface of all types of view request builders.
SettableViewParameters	Describes the parameters that can be set when building view requests.
SettableViewParameters.Common<K,RB extends RequestBuilder>	Setters for parameters that are common to all view requests.
SettableViewParameters.Paginated<K,RB extends RequestBuilder>	Setters for parameters only available to paginated requests.
SettableViewParameters.Reduceable<K,RB extends RequestBuilder>	Setters for parameters applicable to views that have reduce
SettableViewParameters.Unpaginated<K,RB extends RequestBuilder>	Setters for parameters only available to unpaginated requests.
SingleRequestBuilder<K,V,RB>	A request builder for a single request on a view.
UnpaginatedRequestBuilder<K,V>	Interface for building an unpaginated ViewRequest.
ViewMultipleRequest<K,V>	A convenience class for performing multiple unpaginated query requests on a single view.
ViewRequest<K,V>	Enables retrieving view responses.
ViewResponse<K,V>	Encapsulates a response from a view request.
ViewResponse.Row<K,V>	Encapsulates a single row from the response results array.

Class Summary

Class	Description
Key	Class for specifying the types of keys emitted by a view.
Key.ComplexKey	Provides methods for adding values to build a complex key array.
Key.ComplexKeyDeserializer	GSON deserializer to convert JSON arrays to .ComplexKey
Key.Type<T>	Key type identifier.
ViewRequestBuilder	Provides methods for obtaining builders for view requests.

Package com.cloudant.client.api.views Description

This package provides access to the view API.

Overview

As described in the view documentation, views are a way of performing MapReduce on document content in a database. This package facilitates making query requests on views defined in design documents in the database.

Consider this example view (called "shape_sides") that has a map function emitting key-value pairs of a string and an integer:

 function(doc) {
     emit(doc.shape, doc.sides);
 }
 

A sample document that could be queried by this view is:

 { "_id" : docId,
   "_rev" : 1-23456
   "shape" : "triangle"
   "sides" : 3
 }
 

The results of a query using this view are a JSON object containing rows of the document ID and key-value pairs:

 {"total_rows":1,"offset":0,"rows":[
 {"id":"docId","key":"triangle","value":3},
 ]}
 

Example Usage

Example usage of this API for the example view and document above:

 
 //get a ViewRequestBuilder from the database for the chosen view
 ViewRequestBuilder viewBuilder = db.getViewRequestBuilder("myDesignDoc", "shapes_sides");

 //build a new request and specify any parameters required
 ViewRequest<String, Integer> request = viewBuilder.newRequest(Key.Type.STRING,Integer.class)
 .startKey("square") //return docs after "square"
 .build();

 //perform the request and get the response
 ViewResponse<String, Integer> response = request.getResponse();

 //loop through the rows of the response
 for (ViewResponse.Row<String, Integer> row : response.getRows()) {
 String key = row.getKey();
 Integer value = row.getValue();
 System.out.println("Shape " + key + " has " + value + " sides.");
 }
 
 

Would produce output like:

 Shape square has 4 sides.
 Shape triangle has 3 sides.
 

Usage Summary

1. Get a ViewRequestBuilder from the Database.
2. Use the ViewRequestBuilder to get a RequestBuilder for the required type of request.
3. Specify the parameters for the request using the builder's methods defined by teh type of SettableViewParameters.
4. Build the ViewRequest.
5. From the ViewRequest optionally obtain a single result or get the complete ViewResponse.
6. Process the ViewResponse keys, values, documents or rows as needed by your application.

Migration example

This shows how to migrate some examples from the version 1.x view API to the version 2.x view API.

Version 1.x

 
  List<Foo> list = db.view("example/foo")
 	  .startKey("start-key")
 	  .endKey("end-key")
 	  .limit(10)
 	  .includeDocs(true)
 	  .query(Foo.class);

  // scalar values
  int count = db.view("example/by_tag")
 	  .key("couchdb")
 	  .queryForInt();

 // pagination
 Page<Foo> page = db.view("example/foo").queryPage(5, null, Foo.class);
 List<Foo> foos = page.getResultList();
 Page<Foo> nextPage = db.view("example/foo").queryPage(5, page.getNextParam(), Foo.class);
 
 

Version 2.x

 
  List<Foo> list = db.getViewRequestBuilder("example","foo")
    .newRequest(Key.Type.STRING, Object.class)
 	  .startKey("start-key")
 	  .endKey("end-key")
 	  .limit(10)
 	  .includeDocs(true)
 	  .build()
 	  .getResponse()
 	  .getDocsAs(Foo.class);

  // scalar values
  int count = db.getViewRequestBuilder("example","by_tag")
    .newRequest(Key.Type.STRING, Integer.class)
 	  .keys("couchdb")
 	  .build()
 	  .getSingleValue();

 // pagination
 ViewResponse<String, Object> page = db.getViewRequestBuilder("example","foo")
   .newPaginatedRequest(Key.Type.STRING, Object.class)
   .rowsPerPage(5)
   .includeDocs(true)
   .build()
   .getResponse();

 List<Foo> foos = page.getDocsAs(Foo.class);
 ViewResponse<String, Object> nextPage = page.nextPage();
 
 

Since:

2.0.0