/*
 * Copyright 2018 The Vert.x Community.
 *
 * 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 io.vertx.cassandra;

import com.datastax.oss.driver.api.core.cql.PreparedStatement;
import com.datastax.oss.driver.api.core.cql.Row;
import com.datastax.oss.driver.api.core.cql.SimpleStatement;
import com.datastax.oss.driver.api.core.cql.Statement;
import com.datastax.oss.driver.api.core.metadata.Metadata;
import io.vertx.cassandra.impl.CassandraClientImpl;
import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.Vertx;

import java.util.List;
import java.util.UUID;
import java.util.stream.Collector;

Eclipse Vert.x Cassandra client.
Author:
Pavel Drankou, Thomas Segismont/**
 * Eclipse Vert.x Cassandra client.
 *
 * @author Pavel Drankou
 * @author Thomas Segismont
 */
@VertxGen
public interface CassandraClient {

  
The default shared client name.
/**
   * The default shared client name.
   */
  String DEFAULT_SHARED_CLIENT_NAME = "DEFAULT";

  
Like create(Vertx, CassandraClientOptions) with default options. /**
   * Like {@link CassandraClient#create(Vertx, CassandraClientOptions)} with default options.
   */
  static CassandraClient create(Vertx vertx) {
    return create(vertx, new CassandraClientOptions());
  }

  
Create a Cassandra client which maintains its own driver session.

It is not recommended to create several non shared clients in an application.
Params:
vertx –   the Vert.x instance
options – the options
Returns:
the client/**
   * Create a Cassandra client which maintains its own driver session.
   * <p>
   * It is not recommended to create several non shared clients in an application.
   *
   * @param vertx   the Vert.x instance
   * @param options the options
   * @return the client
   */
  static CassandraClient create(Vertx vertx, CassandraClientOptions options) {
    return new CassandraClientImpl(vertx, UUID.randomUUID().toString(), options);
  }

  
Like createShared(Vertx, String, CassandraClientOptions) with default options and client name. /**
   * Like {@link CassandraClient#createShared(Vertx, String, CassandraClientOptions)} with default options and client name.
   */
  static CassandraClient createShared(Vertx vertx) {
    return createShared(vertx, DEFAULT_SHARED_CLIENT_NAME);
  }

  
Like createShared(Vertx, String, CassandraClientOptions) with default options. /**
   * Like {@link CassandraClient#createShared(Vertx, String, CassandraClientOptions)} with default options.
   */
  static CassandraClient createShared(Vertx vertx, String clientName) {
    return createShared(vertx, clientName, new CassandraClientOptions());
  }

  
Like createShared(Vertx, String, CassandraClientOptions) with default client name. /**
   * Like {@link CassandraClient#createShared(Vertx, String, CassandraClientOptions)} with default client name.
   */
  static CassandraClient createShared(Vertx vertx, CassandraClientOptions options) {
    return createShared(vertx, DEFAULT_SHARED_CLIENT_NAME, options);
  }

  
Create a Cassandra client that shares its driver session with any other client having the same name.
Params:
vertx – the Vert.x instance
options – the options
clientName – the shared client name
Returns:
the client/**
   * Create a Cassandra client that shares its driver session with any other client having the same name.
   *
   * @param vertx the Vert.x instance
   * @param options the options
   * @param clientName the shared client name
   *
   * @return the client
   */
  static CassandraClient createShared(Vertx vertx, String clientName, CassandraClientOptions options) {
    return new CassandraClientImpl(vertx, clientName, options);
  }

  
Returns:
whether this Cassandra client instance is connected/**
   * @return whether this Cassandra client instance is connected
   */
  boolean isConnected();

  
Execute the query and provide a handler for consuming results.
Params:
resultHandler – handler called when result of execution is fully fetched.
query – the query to execute
Returns:
current Cassandra client instance/**
   * Execute the query and provide a handler for consuming results.
   *
   * @param resultHandler handler called when result of execution is fully fetched.
   * @param query the query to execute
   *
   * @return current Cassandra client instance
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  CassandraClient executeWithFullFetch(String query, Handler<AsyncResult<List<Row>>> resultHandler);

  
Like executeWithFullFetch(String, Handler<AsyncResult<List<Row>>>) but returns a Future of the asynchronous result. /**
   * Like {@link #executeWithFullFetch(String, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  Future<List<Row>> executeWithFullFetch(String query);

  
Execute the query and provide a handler for consuming results.
Params:
resultHandler – handler called when result of execution is fully fetched.
statement – the statement to execute
Returns:
current Cassandra client instance/**
   * Execute the query and provide a handler for consuming results.
   *
   * @param resultHandler handler called when result of execution is fully fetched.
   * @param statement the statement to execute
   *
   * @return current Cassandra client instance
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  CassandraClient executeWithFullFetch(Statement statement, Handler<AsyncResult<List<Row>>> resultHandler);

  
Like executeWithFullFetch(Statement, Handler<AsyncResult<List<Row>>>) but returns a Future of the asynchronous result. /**
   * Like {@link #executeWithFullFetch(Statement, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  Future<List<Row>> executeWithFullFetch(Statement statement);

  
Execute the query and provide a handler for consuming results.
Params:
resultHandler – handler called when result of execution is present, but can be not fully fetched
query – the query to execute
Returns:
current Cassandra client instance/**
   * Execute the query and provide a handler for consuming results.
   *
   * @param resultHandler handler called when result of execution is present, but can be not fully fetched
   * @param query the query to execute
   *
   * @return current Cassandra client instance
   */
  @Fluent
  CassandraClient execute(String query, Handler<AsyncResult<ResultSet>> resultHandler);

  
Like execute(String, Handler<AsyncResult<ResultSet>>) but returns a Future of the asynchronous result. /**
   * Like {@link #execute(String, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  Future<ResultSet> execute(String query);

  
Execute a query and produce a result by applying a collector to result set rows.
Params:
query – the query to execute
collector – the collector to use to produce a result
resultHandler – the handler called when result of execution and collection is present
Type parameters:
<R> – the result type
Returns:
current Cassandra client instance/**
   * Execute a query and produce a result by applying a collector to result set rows.
   *
   * @param query the query to execute
   * @param collector the collector to use to produce a result
   * @param resultHandler the handler called when result of execution and collection is present
   * @param <R> the result type
   *
   * @return current Cassandra client instance
   */
  @GenIgnore
  @Fluent
  <R> CassandraClient execute(String query, Collector<Row, ?, R> collector, Handler<AsyncResult<R>> resultHandler);

  
Like execute(String, Collector<Row,?,Object>, Handler<AsyncResult<Object>>) but returns a Future of the asynchronous result. /**
   * Like {@link #execute(String, Collector, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore
  <R> Future<R> execute(String query, Collector<Row, ?, R> collector);

  
Execute the statement and provide a handler for consuming results.
Params:
resultHandler – handler called when result of execution is present
statement – the statement to execute
Returns:
current Cassandra client instance/**
   * Execute the statement and provide a handler for consuming results.
   *
   * @param resultHandler handler called when result of execution is present
   * @param statement the statement to execute
   *
   * @return current Cassandra client instance
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  CassandraClient execute(Statement statement, Handler<AsyncResult<ResultSet>> resultHandler);

  
Like execute(Statement, Handler<AsyncResult<ResultSet>>) but returns a Future of the asynchronous result. /**
   * Like {@link #execute(Statement, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  Future<ResultSet> execute(Statement statement);

  
Execute a statement and produce a result by applying a collector to result set rows.
Params:
statement – the statement to execute
collector – the collector to use to produce a result
resultHandler – the handler called when result of execution and collection is present
Type parameters:
<R> – the result type
Returns:
current Cassandra client instance/**
   * Execute a statement and produce a result by applying a collector to result set rows.
   *
   * @param statement the statement to execute
   * @param collector the collector to use to produce a result
   * @param resultHandler the handler called when result of execution and collection is present
   * @param <R> the result type
   *
   * @return current Cassandra client instance
   */
  @GenIgnore
  @Fluent
  <R> CassandraClient execute(Statement statement, Collector<Row, ?, R> collector, Handler<AsyncResult<R>> resultHandler);

  
Like execute(Statement, Collector<Row,?,Object>, Handler<AsyncResult<Object>>) but returns a Future of the asynchronous result. /**
   * Like {@link #execute(Statement, Collector, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore
  <R> Future<R> execute(Statement statement, Collector<Row, ?, R> collector);

  
Prepares the provided query string.
Params:
resultHandler – handler called when result of query preparation is present
query – the query to prepare
Returns:
current Cassandra client instance/**
   * Prepares the provided query string.
   *
   * @param resultHandler handler called when result of query preparation is present
   * @param query the query to prepare
   *
   * @return current Cassandra client instance
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  CassandraClient prepare(String query, Handler<AsyncResult<PreparedStatement>> resultHandler);

  
Like prepare(String, Handler<AsyncResult<PreparedStatement>>) but returns a Future of the asynchronous result. /**
   * Like {@link #prepare(String, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  Future<PreparedStatement> prepare(String query);

  
Prepares the provided a SimpleStatement. 
Params:
resultHandler – handler called when result of query preparation is present
statement – the statement to prepare
Returns:
current Cassandra client instance/**
   * Prepares the provided a {@link SimpleStatement}.
   *
   * @param resultHandler handler called when result of query preparation is present
   * @param statement the statement to prepare
   *
   * @return current Cassandra client instance
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  CassandraClient prepare(SimpleStatement statement, Handler<AsyncResult<PreparedStatement>> resultHandler);

  
Like prepare(SimpleStatement, Handler<AsyncResult<PreparedStatement>>) but returns a Future of the asynchronous result. /**
   * Like {@link #prepare(SimpleStatement, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  Future<PreparedStatement> prepare(SimpleStatement statement);

  
Executes the given SQL SELECT statement which returns the results of the query as a read stream.
Params:
sql – the SQL to execute. For example SELECT * FROM table ....
rowStreamHandler – the handler which is called once the operation completes. It will return an instance of CassandraRowStream.
Returns:
current Cassandra client instance/**
   * Executes the given SQL <code>SELECT</code> statement which returns the results of the query as a read stream.
   *
   * @param sql the SQL to execute. For example <code>SELECT * FROM table ...</code>.
   * @param rowStreamHandler the handler which is called once the operation completes. It will return an instance of {@link CassandraRowStream}.
   *
   * @return current Cassandra client instance
   */
  @Fluent
  CassandraClient queryStream(String sql, Handler<AsyncResult<CassandraRowStream>> rowStreamHandler);

  
Like queryStream(String, Handler<AsyncResult<CassandraRowStream>>) but returns a Future of the asynchronous result. /**
   * Like {@link #queryStream(String, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  Future<CassandraRowStream> queryStream(String sql);

  
Executes the given SQL statement which returns the results of the query as a read stream.
Params:
statement – the statement to execute.
rowStreamHandler – the handler which is called once the operation completes. It will return an instance of CassandraRowStream.
Returns:
current Cassandra client instance/**
   * Executes the given SQL statement which returns the results of the query as a read stream.
   *
   * @param statement the statement to execute.
   * @param rowStreamHandler the handler which is called once the operation completes. It will return an instance of {@link CassandraRowStream}.
   *
   * @return current Cassandra client instance
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  @Fluent
  CassandraClient queryStream(Statement statement, Handler<AsyncResult<CassandraRowStream>> rowStreamHandler);

  
Like queryStream(Statement, Handler<AsyncResult<CassandraRowStream>>) but returns a Future of the asynchronous result. /**
   * Like {@link #queryStream(Statement, Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  Future<CassandraRowStream> queryStream(Statement statement);

  
Like close(Handler<AsyncResult<Void>>) but returns a Future of the asynchronous result. /**
   * Like {@link #close(Handler)} but returns a {@code Future} of the asynchronous result.
   */
  Future<Void> close();

  
Closes this client.
Params:
closeHandler – handler called when client is closed
Returns:
current Cassandra client instance/**
   * Closes this client.
   *
   * @param closeHandler handler called when client is closed
   *
   * @return current Cassandra client instance
   */
  @Fluent
  CassandraClient close(Handler<AsyncResult<Void>> closeHandler);

  
Get Metadata for the session. 
Params:
handler – the handler called backed with the metadata/**
   * Get {@link Metadata} for the session.
   *
   * @param handler the handler called backed with the metadata
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  void metadata(Handler<AsyncResult<Metadata>> handler);

  
Like metadata(Handler<AsyncResult<Metadata>>) but returns a Future of the asynchronous result. /**
   * Like {@link #metadata(Handler)} but returns a {@code Future} of the asynchronous result.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  Future<Metadata> metadata();
}