io.vertx.sqlclient.PreparedStatement Maven / Gradle / Ivy
/*
* Copyright (C) 2017 Julien Viet
*
* 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.sqlclient;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.sqlclient.impl.ArrayTuple;
/**
* A prepared statement, the statement is pre-compiled and it's more efficient to execute the statement for multiple times.
* In addition, this kind of statement provides protection against SQL injection attacks.
*
* From a prepared statement you can
*
*
* - use {@link #query()} to create and execute a {@link PreparedQuery}
* - use {@link #cursor()} to create a {@link Cursor}
* - use {@link #createStream} to create a {@link RowStream}
*
*
* @author Julien Viet
*/
@VertxGen
public interface PreparedStatement {
/**
* Create a prepared query for this statement.
*
* @return the prepared query
*/
PreparedQuery> query();
/**
* Like {@link #cursor(Tuple)} but with empty arguments.
*/
default Cursor cursor() {
return cursor(ArrayTuple.EMPTY);
}
/**
* Create a cursor with the provided {@code arguments}.
*
* @param args the list of arguments
* @return the query
*/
Cursor cursor(Tuple args);
/**
* Like {@link #createStream(int, Tuple)} but with empty arguments.
*/
default RowStream createStream(int fetch) {
return createStream(fetch, ArrayTuple.EMPTY);
}
/**
* Execute the prepared query with a cursor and createStream the result. The createStream opens a cursor
* with a {@code fetch} size to fetch the results.
*
* Note: this requires to be in a transaction, since cursors require it.
*
* @param fetch the cursor fetch size
* @param args the prepared query arguments
* @return the createStream
*/
RowStream createStream(int fetch, Tuple args);
/**
* Close the prepared query and release its resources.
*/
Future close();
/**
* Like {@link #close()} but notifies the {@code completionHandler} when it's closed.
*/
void close(Handler> completionHandler);
}