content: /*
   * Licensed to the Apache Software Foundation (ASF) under one
   * or more contributor license agreements.  See the NOTICE file
   * distributed with this work for additional information
   * regarding copyright ownership.  The ASF licenses this file
   * to you 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.datastax.dse.driver.api.core.cql.continuous;
  
  import com.datastax.dse.driver.internal.core.cql.continuous.ContinuousCqlRequestAsyncProcessor;
  import com.datastax.dse.driver.internal.core.cql.continuous.ContinuousCqlRequestSyncProcessor;
  import com.datastax.oss.driver.api.core.DefaultConsistencyLevel;
  import com.datastax.oss.driver.api.core.cql.Statement;
  import com.datastax.oss.driver.api.core.loadbalancing.LoadBalancingPolicy;
  import com.datastax.oss.driver.api.core.metadata.token.Token;
  import com.datastax.oss.driver.api.core.session.Session;
  import edu.umd.cs.findbugs.annotations.NonNull;
  import java.nio.ByteBuffer;
  import java.util.Objects;
  import java.util.concurrent.CompletionStage;
  
  /**
   * A session that has the ability to execute continuous paging queries.
   *
   * <p>Continuous paging is a new method of streaming bulk amounts of records from DataStax
   * Enterprise (DSE) to the Java Driver, available since DSE 5.1. It is mainly intended to be
   * leveraged by <a
   * href="https://docs.datastax.com/en/dse/5.1/dse-dev/datastax_enterprise/analytics/analyticsTOC.html">DSE
   * Analytics</a> and Apache Spark™, or by any similar analytics tool that needs to read large
   * portions of a table in one single operation, as quick and reliably as possible.
   *
   * <p>Continuous paging provides the best performance improvement against regular paging when the
   * following conditions are met:
   *
   * <ol>
   *   <li>The statement must target a single partition or a token range owned by one single replica;
   *       in practice, this means that the statement must have either a {@linkplain
   *       Statement#setRoutingKey(ByteBuffer) routing key} or a {@linkplain
   *       Statement#setRoutingToken(Token) routing token} set;
   *   <li>The coordinator must be a replica; in practice, this is usually achieved by using
   *       token-aware routing (if you are using the driver's default {@link LoadBalancingPolicy},
   *       then this condition is met);
   *   <li>The consistency level must be {@link DefaultConsistencyLevel#ONE ONE} (or {@link
   *       DefaultConsistencyLevel#LOCAL_ONE LOCAL_ONE}).
   * </ol>
   *
   * <p>If the above conditions are met, the coordinator will be able to optimize the read path and
   * serve results from local data, thus significantly improving response times; if however these
   * conditions cannot be met, continuous paging would still work, but response times wouldn't be
   * significantly better than those of regular paging anymore.
   *
   * @see <a
   *     href="https://docs.datastax.com/en/dse/6.7/dse-dev/datastax_enterprise/config/configCassandra_yaml.html#configCassandra_yaml__continous-paging">Continuous
   *     paging options in cassandra.yaml configuration file</a>
   * @see <a
   *     href="https://www.datastax.com/dev/blog/dse-continuous-paging-tuning-and-support-guide">DSE
   *     Continuous Paging Tuning and Support Guide</a>
   */
  public interface ContinuousSession extends Session {
  
    /**
     * Executes the provided query with continuous paging synchronously.
     *
     * <p>This method takes care of chaining the successive results into a convenient iterable,
     * provided that you always access the result from the same thread. For more flexibility, consider
     * using the {@linkplain #executeContinuouslyAsync(Statement) asynchronous variant} of this method
     * instead.
     *
     * <p>See {@link ContinuousSession} for more explanations about continuous paging.
     *
     * <p>This feature is only available with DataStax Enterprise. Executing continuous queries
     * against an Apache Cassandra&copy; cluster will result in a runtime error.
     *
     * @param statement the query to execute.
     * @return a synchronous iterable on the results.
     */
    @NonNull
    default ContinuousResultSet executeContinuously(@NonNull Statement<?> statement) {
      return Objects.requireNonNull(
          execute(statement, ContinuousCqlRequestSyncProcessor.CONTINUOUS_RESULT_SYNC));
    }
  
    /**
     * Executes the provided query with continuous paging asynchronously.
     *
     * <p>The server will push all requested pages asynchronously, according to the options defined in
     * the current execution profile. The client should consume all pages as quickly as possible, to
     * avoid blocking the server for too long. The server will adjust the rate according to the client
     * speed, but it will give up if the client does not consume any pages in a period of time equal
     * to the read request timeout.
     *
     * <p>See {@link ContinuousSession} for more explanations about continuous paging.
     *
     * <p>This feature is only available with DataStax Enterprise. Executing continuous queries
     * against an Apache Cassandra&copy; cluster will result in a runtime error.
     *
     * @param statement the query to execute.
     * @return a future to the first asynchronous result.
     */
    @NonNull
    default CompletionStage<ContinuousAsyncResultSet> executeContinuouslyAsync(
        @NonNull Statement<?> statement) {
      return Objects.requireNonNull(
          execute(statement, ContinuousCqlRequestAsyncProcessor.CONTINUOUS_RESULT_ASYNC));
    }
  }
  