com.datastax.dse.driver.api.core.cql.continuous.ContinuousSession Maven / Gradle / Ivy
/*
* 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.
*
* 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 DSE
* Analytics 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.
*
*
Continuous paging provides the best performance improvement against regular paging when the
* following conditions are met:
*
*
* - 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;
*
- 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);
*
- The consistency level must be {@link DefaultConsistencyLevel#ONE ONE} (or {@link
* DefaultConsistencyLevel#LOCAL_ONE LOCAL_ONE}).
*
*
* 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 Continuous
* paging options in cassandra.yaml configuration file
* @see DSE
* Continuous Paging Tuning and Support Guide
*/
public interface ContinuousSession extends Session {
/**
* Executes the provided query with continuous paging synchronously.
*
*
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.
*
*
See {@link ContinuousSession} for more explanations about continuous paging.
*
*
This feature is only available with DataStax Enterprise. Executing continuous queries
* against an Apache Cassandra© 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.
*
*
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.
*
*
See {@link ContinuousSession} for more explanations about continuous paging.
*
*
This feature is only available with DataStax Enterprise. Executing continuous queries
* against an Apache Cassandra© cluster will result in a runtime error.
*
* @param statement the query to execute.
* @return a future to the first asynchronous result.
*/
@NonNull
default CompletionStage executeContinuouslyAsync(
@NonNull Statement statement) {
return Objects.requireNonNull(
execute(statement, ContinuousCqlRequestAsyncProcessor.CONTINUOUS_RESULT_ASYNC));
}
}