• Home
• com.datastax.dse
• dse-java-driver-core
• 1.2.5
• source code
• ResultSetFuture.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.datastax.driver.core.ResultSetFuture Maven / Gradle / Ivy

/*
 *      Copyright (C) 2012-2017 DataStax Inc.
 *
 *      This software can be used solely with DataStax Enterprise. Please consult the license at
 *      http://www.datastax.com/terms/datastax-dse-driver-license-terms
 */
package com.datastax.driver.core;

import com.datastax.driver.core.exceptions.NoHostAvailableException;
import com.datastax.driver.core.exceptions.QueryExecutionException;
import com.datastax.driver.core.exceptions.QueryValidationException;
import com.google.common.util.concurrent.ListenableFuture;

import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

/**
 * A future on a {@link ResultSet}.
 * 

 * Note that this class implements Guava's {@code
 * ListenableFuture} and can so be used with Guava's future utilities.
 */
public interface ResultSetFuture extends ListenableFuture {

    /**
     * Waits for the query to return and return its result.
     * 

     * This method is usually more convenient than {@link #get} because it:
     * 

     * 
Waits for the result uninterruptibly, and so doesn't throw
     * {@link InterruptedException}.
     * 
Returns meaningful exceptions, instead of having to deal
     * with ExecutionException.
     * 
     * As such, it is the preferred way to get the future result.
     *
     * @return the query result set.
     * @throws NoHostAvailableException if no host in the cluster can be
     *                                  contacted successfully to execute this query.
     * @throws QueryExecutionException  if the query triggered an execution
     *                                  exception, that is an exception thrown by Cassandra when it cannot execute
     *                                  the query with the requested consistency level successfully.
     * @throws QueryValidationException if the query is invalid (syntax error,
     *                                  unauthorized or any other validation problem).
     */
    public ResultSet getUninterruptibly();

    /**
     * Waits for the provided time for the query to return and return its
     * result if available.
     * 

     * This method is usually more convenient than {@link #get} because it:
     * 

     * 
Waits for the result uninterruptibly, and so doesn't throw
     * {@link InterruptedException}.
     * 
Returns meaningful exceptions, instead of having to deal
     * with ExecutionException.
     * 
     * As such, it is the preferred way to get the future result.
     *
     * @param timeout the time to wait for the query to return.
     * @param unit    the unit for {@code timeout}.
     * @return the query result set.
     * @throws NoHostAvailableException if no host in the cluster can be
     *                                  contacted successfully to execute this query.
     * @throws QueryExecutionException  if the query triggered an execution
     *                                  exception, that is an exception thrown by Cassandra when it cannot execute
     *                                  the query with the requested consistency level successfully.
     * @throws QueryValidationException if the query if invalid (syntax error,
     *                                  unauthorized or any other validation problem).
     * @throws TimeoutException         if the wait timed out (Note that this is
     *                                  different from a Cassandra timeout, which is a {@code
     *                                  QueryExecutionException}).
     */
    public ResultSet getUninterruptibly(long timeout, TimeUnit unit) throws TimeoutException;

    /**
     * Attempts to cancel the execution of the request corresponding to this
     * future. This attempt will fail if the request has already returned.
     * 

     * Please note that this only cancel the request driver side, but nothing
     * is done to interrupt the execution of the request Cassandra side (and that even
     * if {@code mayInterruptIfRunning} is true) since  Cassandra does not
     * support such interruption.
     * 

     * This method can be used to ensure no more work is performed driver side
     * (which, while it doesn't include stopping a request already submitted
     * to a Cassandra node, may include not retrying another Cassandra host on
     * failure/timeout) if the ResultSet is not going to be retried. Typically,
     * the code to wait for a request result for a maximum of 1 second could
     * look like:
     * 
     *   ResultSetFuture future = session.executeAsync(...some query...);
     *   try {
     *       ResultSet result = future.get(1, TimeUnit.SECONDS);
     *       ... process result ...
     *   } catch (TimeoutException e) {
     *       future.cancel(true); // Ensure any resource used by this query driver
     *                            // side is released immediately
     *       ... handle timeout ...
     *   }
     * 
     *
     * @param mayInterruptIfRunning the value of this parameter is currently
     *                              ignored.
     * @return {@code false} if the future could not be cancelled (it has already
     * completed normally); {@code true} otherwise.
     */
    @Override
    public boolean cancel(boolean mayInterruptIfRunning);
}