<commit_before>/* This file is part of VoltDB.
 * Copyright (C) 2008-2014 VoltDB Inc.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with VoltDB.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.voltdb.client;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.UnknownHostException;
import java.util.List;

/**
 *  <p>
 *  A <code>Client</code> that connects to one or more nodes in a volt cluster
 *  and provides methods for invoking stored procedures and receiving
 *  responses.
 *  </p>
 */
public interface Client {

    /**
     * Default non-admin port number for volt cluster instances.
     */
    public static final int VOLTDB_SERVER_PORT = 21212;

    /**
     * <p>Create a connection to a VoltDB node and add it to the set of connections.</p>
     *
     * <p>This is a synchronous operation.</p>
     *
     * @param host Hostname or IP address of the host to connect to including
     * optional port in the hostname:port format.
     * @throws UnknownHostException if the hostname can't be resolved.
     * @throws IOException if there is a Java network or connection problem.
     */
    public void createConnection(String host)
    throws UnknownHostException, IOException;

    /**
     * <p>Create a connection to a VoltDB node.</p>
     *
     * <p>This is a synchronous operation.</p>
     *
     * @param host Hostname or IP address of the host to connect to.
     * @param port Port number on remote host to connect to.
     * @throws UnknownHostException if the hostname can't be resolved.
     * @throws IOException if there is a Java network or connection problem.
     */
    public void createConnection(String host, int port)
    throws UnknownHostException, IOException;

    /**
     * <p>Synchronously invoke a procedure. Blocks until a result is available. A {@link ProcCallException}
     * is thrown if the response is anything other then success.</p>
     *
     * @param procName <code>class</code> name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @return {@link ClientResponse} instance of procedure call results.
     * @throws ProcCallException on any VoltDB specific failure.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws IOException if there is a Java network or connection problem.
     */
    public ClientResponse callProcedure(String procName, Object... parameters)
    throws IOException, NoConnectionsException, ProcCallException;

    /**
     * <p>Asynchronously invoke a replicated procedure. If there is backpressure
     * this call will block until the invocation is queued. If configureBlocking(false) is invoked
     * then it will return immediately. Check the return value to determine if queueing actually took place.</p>
     *
     * @param callback {@link ProcedureCallback} that will be invoked with procedure results.
     * @param procName class name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @return <code>true</code> if the procedure was queued and <code>false</code> otherwise.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws IOException if there is a Java network or connection problem.
     */
    public boolean callProcedure(ProcedureCallback callback, String procName, Object... parameters)
    throws IOException, NoConnectionsException;

    /**
     * <p>Asynchronously invoke a replicated procedure. If there is backpressure
     * this call will block until the invocation is queued. If configureBlocking(false) is invoked
     * then it will return immediately. Check the return value to determine if queuing actually took place.</p>
     *
     * <p>An opportunity is provided to hint what the size of the invocation
     * will be once serialized. This is used to perform more efficient memory allocation and serialization. The size
     * of an invocation can be calculated using {@link #calculateInvocationSerializedSize(String, Object...)}.
     * Only Clients that are resource constrained or expect to process hundreds of thousands of txns/sec will benefit
     * from accurately determining the serialized size of message.</p>
     *
     * @deprecated because hinting at the serialized size no longer has any effect.
     * @param callback ProcedureCallback that will be invoked with procedure results.
     * @param procName class name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @param expectedSerializedSize A hint indicating the size the procedure invocation is expected to be
     *                               once serialized. Allocations are done in powers of two.
     * @return <code>true</code> if the procedure was queued and <code>false</code> otherwise.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws IOException if there is a Java network or connection problem.
     */
    @Deprecated
    public boolean callProcedure(
            ProcedureCallback callback,
            int expectedSerializedSize,
            String procName,
            Object... parameters)
    throws IOException, NoConnectionsException;

    /**
     * <p>Calculate the size of a stored procedure invocation once it is serialized. This is computationally intensive
     * as the invocation is serialized as part of the calculation.</p>
     *
     * @deprecated because hinting at the serialized size no longer has any effect.
     * @param procName class name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @return The size of the invocation once serialized.
     */
    @Deprecated
    public int calculateInvocationSerializedSize(String procName, Object... parameters);

    /**
     * <p>Synchronously invokes UpdateApplicationCatalog procedure. Blocks until a
     * result is available. A {@link ProcCallException} is thrown if the
     * response is anything other then success.</p>
     *
     * <p>This method is a convenience method that is equivalent to reading the catalog
     * file into a byte array in Java code, then calling {@link #callProcedure(String, Object...)}
     * with "@UpdateApplicationCatalog" as the procedure name, followed by they bytes of the catalog
     * and the string value of the deployment file.</p>
     *
     * @param catalogPath Path to the catalog jar file.
     * @param deploymentPath Path to the deployment file.
     * @return {@link ClientResponse} instance of procedure call results.
     * @throws IOException If the files cannot be serialized or if there is a Java network error.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws ProcCallException on any VoltDB specific failure.
     */
    public ClientResponse updateApplicationCatalog(File catalogPath, File deploymentPath)
    throws IOException, NoConnectionsException, ProcCallException;

    /**
     * <p>Asynchronously invokes UpdateApplicationCatalog procedure. Does not
     * guarantee that the invocation is actually queued. If there is
     * backpressure on all connections to the cluster then the invocation will
     * not be queued. Check the return value to determine if queuing actually
     * took place.</p>
     *
     * <p>This method is a convenience method that is equivalent to reading the catalog
     * file into a byte array in Java code, then calling
     * {@link #callProcedure(ProcedureCallback, String, Object...)} with
     * "@UpdateApplicationCatalog" as the procedure name, followed by they bytes of the catalog
     * and the string value of the deployment file.</p>
     *
     * @param callback ProcedureCallback that will be invoked with procedure results.
     * @param catalogPath Path to the catalog jar file.
     * @param deploymentPath Path to the deployment file.
     * @return <code>true</code> if the procedure was queued and <code>false</code> otherwise.
     * @throws IOException If the files cannot be serialized or if there is a Java network error.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     */
    public boolean updateApplicationCatalog(ProcedureCallback callback,
                                            File catalogPath,
                                            File deploymentPath)
    throws IOException, NoConnectionsException;


    /**
     * <p>Block the current thread until all queued stored procedure invocations have received responses
     * or there are no more connections to the cluster.</p>
     *
     * @throws NoConnectionsException never, this is deprecated behavior, declared only for backward compatibility.
     * @throws InterruptedException if this blocking call is interrupted.
     */
    public void drain() throws NoConnectionsException, InterruptedException;

    /**
     * <p>Shutdown this Client, closing all network connections and release all memory resources.
     * Failing to call this method before the Client is garbage collected can generate errors because
     * <code>finalization</code> is used to detect resource leaks. A client cannot be used once it has
     * been closed.</p>
     *
     * @throws InterruptedException if call is interrupted before it finishes.
     */
    public void close() throws InterruptedException;

    /**
     * <p>Blocks the current thread until there is no more backpressure or there are no more connections
     * to the database</p>
     *
     * @throws InterruptedException if this blocking call is interrupted.
     * @deprecated Doesn't work right, hasn't for years
     */
    public void backpressureBarrier() throws InterruptedException;

    /**
     * <p>Get a {@link ClientStatsContext} instance to fetch and process performance
     * statistics. Each instance is linked to this client, but provides a custom
     * view of statistics for a desired time period.</p>
     *
     * @see ClientStatsContext
     * @return Statistics context object linked to this client.
     */
    public ClientStatsContext createStatsContext();

    /**
     * <p>Get an identifier for the cluster that this client is currently connected to.
     * This will be null if the client has not been connected. Currently these values have
     * logical meaning, but they should just be interpreted as a unique per-cluster value.</p>
     *
     * @return An array of a Long and Integer containing the millisecond timestamp when the cluster was
     * started and the leader IP address (mapped as an unsigned int).
     */
    public Object[] getInstanceId();

    /**
     * <p>Retrieve the build string that was provided by the server at connection time.</p>
     *
     * @return Volt server build string.
     */
    public String getBuildString();

    /**
     * <p>The default behavior for queueing of asynchronous procedure invocations is to block until
     * it is possible to queue the invocation. If blocking is set to false callProcedure will always return
     * immediately if it is not possible to queue the procedure invocation due to backpressure.</p>
     *
     * @param blocking Whether you want procedure calls to block on backpressure.
     * @deprecated The non-blocking feature set is untested and not very useful
     */
    public void configureBlocking(boolean blocking);

    /**
     * <p>Will {@link #callProcedure(ProcedureCallback, String, Object...)} will return
     * immediately if a an async procedure invocation could not be queued due to backpressure.</p>
     *
     * @return true if {@link #callProcedure(ProcedureCallback, String, Object...)} will
     * block until backpressure ceases and false otherwise.
     * @deprecated The non-blocking feature set is untested and not very useful
     */
    public boolean blocking();

    /**
     * <p>Get the instantaneous values of the rate limiting values for this client.</p>
     *<commit_msg>For ENG-5869, update deprecation message to suggest contacting us if the non-blocking features are still useful<commit_after>/* This file is part of VoltDB.
 * Copyright (C) 2008-2014 VoltDB Inc.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with VoltDB.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.voltdb.client;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.UnknownHostException;
import java.util.List;

/**
 *  <p>
 *  A <code>Client</code> that connects to one or more nodes in a volt cluster
 *  and provides methods for invoking stored procedures and receiving
 *  responses.
 *  </p>
 */
public interface Client {

    /**
     * Default non-admin port number for volt cluster instances.
     */
    public static final int VOLTDB_SERVER_PORT = 21212;

    /**
     * <p>Create a connection to a VoltDB node and add it to the set of connections.</p>
     *
     * <p>This is a synchronous operation.</p>
     *
     * @param host Hostname or IP address of the host to connect to including
     * optional port in the hostname:port format.
     * @throws UnknownHostException if the hostname can't be resolved.
     * @throws IOException if there is a Java network or connection problem.
     */
    public void createConnection(String host)
    throws UnknownHostException, IOException;

    /**
     * <p>Create a connection to a VoltDB node.</p>
     *
     * <p>This is a synchronous operation.</p>
     *
     * @param host Hostname or IP address of the host to connect to.
     * @param port Port number on remote host to connect to.
     * @throws UnknownHostException if the hostname can't be resolved.
     * @throws IOException if there is a Java network or connection problem.
     */
    public void createConnection(String host, int port)
    throws UnknownHostException, IOException;

    /**
     * <p>Synchronously invoke a procedure. Blocks until a result is available. A {@link ProcCallException}
     * is thrown if the response is anything other then success.</p>
     *
     * @param procName <code>class</code> name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @return {@link ClientResponse} instance of procedure call results.
     * @throws ProcCallException on any VoltDB specific failure.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws IOException if there is a Java network or connection problem.
     */
    public ClientResponse callProcedure(String procName, Object... parameters)
    throws IOException, NoConnectionsException, ProcCallException;

    /**
     * <p>Asynchronously invoke a replicated procedure. If there is backpressure
     * this call will block until the invocation is queued. If configureBlocking(false) is invoked
     * then it will return immediately. Check the return value to determine if queueing actually took place.</p>
     *
     * @param callback {@link ProcedureCallback} that will be invoked with procedure results.
     * @param procName class name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @return <code>true</code> if the procedure was queued and <code>false</code> otherwise.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws IOException if there is a Java network or connection problem.
     */
    public boolean callProcedure(ProcedureCallback callback, String procName, Object... parameters)
    throws IOException, NoConnectionsException;

    /**
     * <p>Asynchronously invoke a replicated procedure. If there is backpressure
     * this call will block until the invocation is queued. If configureBlocking(false) is invoked
     * then it will return immediately. Check the return value to determine if queuing actually took place.</p>
     *
     * <p>An opportunity is provided to hint what the size of the invocation
     * will be once serialized. This is used to perform more efficient memory allocation and serialization. The size
     * of an invocation can be calculated using {@link #calculateInvocationSerializedSize(String, Object...)}.
     * Only Clients that are resource constrained or expect to process hundreds of thousands of txns/sec will benefit
     * from accurately determining the serialized size of message.</p>
     *
     * @deprecated because hinting at the serialized size no longer has any effect.
     * @param callback ProcedureCallback that will be invoked with procedure results.
     * @param procName class name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @param expectedSerializedSize A hint indicating the size the procedure invocation is expected to be
     *                               once serialized. Allocations are done in powers of two.
     * @return <code>true</code> if the procedure was queued and <code>false</code> otherwise.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws IOException if there is a Java network or connection problem.
     */
    @Deprecated
    public boolean callProcedure(
            ProcedureCallback callback,
            int expectedSerializedSize,
            String procName,
            Object... parameters)
    throws IOException, NoConnectionsException;

    /**
     * <p>Calculate the size of a stored procedure invocation once it is serialized. This is computationally intensive
     * as the invocation is serialized as part of the calculation.</p>
     *
     * @deprecated because hinting at the serialized size no longer has any effect.
     * @param procName class name (not qualified by package) of the procedure to execute.
     * @param parameters vararg list of procedure's parameter values.
     * @return The size of the invocation once serialized.
     */
    @Deprecated
    public int calculateInvocationSerializedSize(String procName, Object... parameters);

    /**
     * <p>Synchronously invokes UpdateApplicationCatalog procedure. Blocks until a
     * result is available. A {@link ProcCallException} is thrown if the
     * response is anything other then success.</p>
     *
     * <p>This method is a convenience method that is equivalent to reading the catalog
     * file into a byte array in Java code, then calling {@link #callProcedure(String, Object...)}
     * with "@UpdateApplicationCatalog" as the procedure name, followed by they bytes of the catalog
     * and the string value of the deployment file.</p>
     *
     * @param catalogPath Path to the catalog jar file.
     * @param deploymentPath Path to the deployment file.
     * @return {@link ClientResponse} instance of procedure call results.
     * @throws IOException If the files cannot be serialized or if there is a Java network error.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     * @throws ProcCallException on any VoltDB specific failure.
     */
    public ClientResponse updateApplicationCatalog(File catalogPath, File deploymentPath)
    throws IOException, NoConnectionsException, ProcCallException;

    /**
     * <p>Asynchronously invokes UpdateApplicationCatalog procedure. Does not
     * guarantee that the invocation is actually queued. If there is
     * backpressure on all connections to the cluster then the invocation will
     * not be queued. Check the return value to determine if queuing actually
     * took place.</p>
     *
     * <p>This method is a convenience method that is equivalent to reading the catalog
     * file into a byte array in Java code, then calling
     * {@link #callProcedure(ProcedureCallback, String, Object...)} with
     * "@UpdateApplicationCatalog" as the procedure name, followed by they bytes of the catalog
     * and the string value of the deployment file.</p>
     *
     * @param callback ProcedureCallback that will be invoked with procedure results.
     * @param catalogPath Path to the catalog jar file.
     * @param deploymentPath Path to the deployment file.
     * @return <code>true</code> if the procedure was queued and <code>false</code> otherwise.
     * @throws IOException If the files cannot be serialized or if there is a Java network error.
     * @throws NoConnectionsException if this {@link Client} instance is not connected to any servers.
     */
    public boolean updateApplicationCatalog(ProcedureCallback callback,
                                            File catalogPath,
                                            File deploymentPath)
    throws IOException, NoConnectionsException;


    /**
     * <p>Block the current thread until all queued stored procedure invocations have received responses
     * or there are no more connections to the cluster.</p>
     *
     * @throws NoConnectionsException never, this is deprecated behavior, declared only for backward compatibility.
     * @throws InterruptedException if this blocking call is interrupted.
     */
    public void drain() throws NoConnectionsException, InterruptedException;

    /**
     * <p>Shutdown this Client, closing all network connections and release all memory resources.
     * Failing to call this method before the Client is garbage collected can generate errors because
     * <code>finalization</code> is used to detect resource leaks. A client cannot be used once it has
     * been closed.</p>
     *
     * @throws InterruptedException if call is interrupted before it finishes.
     */
    public void close() throws InterruptedException;

    /**
     * <p>Blocks the current thread until there is no more backpressure or there are no more connections
     * to the database</p>
     *
     * @throws InterruptedException if this blocking call is interrupted.
     * @deprecated The non-blocking feature set is untested and has questionable utility. If it is something you need contact us.
     */
    @Deprecated
    public void backpressureBarrier() throws InterruptedException;

    /**
     * <p>Get a {@link ClientStatsContext} instance to fetch and process performance
     * statistics. Each instance is linked to this client, but provides a custom
     * view of statistics for a desired time period.</p>
     *
     * @see ClientStatsContext
     * @return Statistics context object linked to this client.
     */
    public ClientStatsContext createStatsContext();

    /**
     * <p>Get an identifier for the cluster that this client is currently connected to.
     * This will be null if the client has not been connected. Currently these values have
     * logical meaning, but they should just be interpreted as a unique per-cluster value.</p>
     *
     * @return An array of a Long and Integer containing the millisecond timestamp when the cluster was
     * started and the leader IP address (mapped as an unsigned int).
     */
    public Object[] getInstanceId();

    /**
     * <p>Retrieve the build string that was provided by the server at connection time.</p>
     *
     * @return Volt server build string.
     */
    public String getBuildString();

    /**
     * <p>The default behavior for queueing of asynchronous procedure invocations is to block until
     * it is possible to queue the invocation. If blocking is set to false callProcedure will always return
     * immediately if it is not possible to queue the procedure invocation due to backpressure.</p>
     *
     * @param blocking Whether you want procedure calls to block on backpressure.
     * @deprecated The non-blocking feature set is untested and has questionable utility. If it is something you need contact us.
     */
    @Deprecated
    public void configureBlocking(boolean blocking);

    /**
     * <p>Will {@link #callProcedure(ProcedureCallback, String, Object...)} will return
     * immediately if a an async procedure invocation could not be queued due to backpressure.</p>
     *
     * @return true if {@link #callProcedure(ProcedureCallback, String, Object...)} will
     * block until backpressure ceases and false otherwise.
     * @deprecated The non-blocking feature set is untested and has questionable utility. If it is something you need contact us.
     */
    @Deprecated
    public boolean blocking();

    /**
     * <p>Get the instantaneous values of the rate limiting values for this client.</p>
     *
{'fraction_non_alphanumeric': 0.06498194945848375, 'fraction_numerical': 0.0012289730394039482, 'mean_word_length': 3.133174603174603, 'pattern_counts': {'":': 0, '<': 133, '<?xml version=': 0, '>': 133, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4728466', 'n_tokens_mistral': 6289, 'n_tokens_neox': 6106, 'n_words': 3072}