main.java.com.cloudant.client.api.views.ViewMultipleRequest Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of cloudant-client Show documentation

Official Cloudant client for Java

There is a newer version: 2.20.1

/*
 * Copyright (c) 2015 IBM Corp. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the
 * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 * either express or implied. See the License for the specific language governing permissions
 * and limitations under the License.
 */

package com.cloudant.client.api.views;

import java.io.IOException;
import java.util.List;

/**
 * 
 * A convenience class for performing multiple unpaginated query requests on a single view.
 * 
 * The request is built by a {@link MultipleRequestBuilder}.
 * 
 * 
 * Example usage:
 * 
 *  * {@code
 *
 * List> responses =
 *
 * //get a builder for the "alpha" view of the "directory" design doc
 * db.getViewRequestBuilder("directory","alpha")
 *
 *     //create a new multi request expecting String keys and values
 *     .newMultipleRequest(Key.Type.STRING, String.class)
 *
 *     //add three request queries
 *     .startKey("A").endKey("B").add() //add a request from A to B
 *     .startKey("H").endKey("I").add() //add a request from H to I
 *     .startKey("N").endKey("O").add() //add a request from N to O
 *
 *     //build the request; note the use of buildMulti() not build()
 *     .buildMulti()
 *
 *     //do the POST to get the responses
 *     .getViewResponses();
 *
 * //loop the responses (in order the requests were added)
 * for (ViewResponse response : responses) {
 *     //first response is result from A to B
 *     //second response is result from H to I
 *     //third response is result from N to O
 * }
 *
 * }
 * 
 * 
 * Cloudant API reference
 * 
 *
 * @param  the type of key emitted by the view, fixed by the
 *            {@link com.cloudant.client.api.views.Key.Type} supplied to the
 *            {@link ViewRequestBuilder}
 * @param  the type of value emitted by the view, specified when supplied to the
 *            {@link ViewRequestBuilder}
 * @since 2.0.0
 */
public interface ViewMultipleRequest {

    /**
     * Perform a single POST request to get the responses for the queries built into this request.
     *
     * @return a list of the responses, one for each query
     * @throws IOException if there is an error communicating with the server
     * @since 2.0.0
     */
    List> getViewResponses() throws IOException;
}