/*
 * Copyright DataStax, Inc.
 *
 * 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 com.datastax.oss.driver.internal.core.channel;

import com.datastax.oss.protocol.internal.Frame;

The outcome of a request sent to a Cassandra node.
This comes into play after the request has been successfully written to the channel.
Due to internal implementation constraints, different instances of this type must not be equal to each other (they are stored in a BiMap in InFlightHandler); reference equality should be appropriate in all cases. /**
 * The outcome of a request sent to a Cassandra node.
 *
 * <p>This comes into play after the request has been successfully written to the channel.
 *
 * <p>Due to internal implementation constraints, different instances of this type must not be equal
 * to each other (they are stored in a {@code BiMap} in {@link InFlightHandler}); reference equality
 * should be appropriate in all cases.
 */
public interface ResponseCallback {

  
Invoked when the server replies (note that the response frame might contain an error message).
/**
   * Invoked when the server replies (note that the response frame might contain an error message).
   */
  void onResponse(Frame responseFrame);

  
Invoked if we couldn't get the response.
This can be triggered in two cases:

  
the connection was closed (for example, because of a heartbeat failure) before the
      response was received;
  
the response was received but there was an error while decoding it.

/**
   * Invoked if we couldn't get the response.
   *
   * <p>This can be triggered in two cases:
   *
   * <ul>
   *   <li>the connection was closed (for example, because of a heartbeat failure) before the
   *       response was received;
   *   <li>the response was received but there was an error while decoding it.
   * </ul>
   */
  void onFailure(Throwable error);

  
Reports the stream id used for the request on the current connection.
This is called every time the request is written successfully to a connection (and therefore
might multiple times in case of retries). It is guaranteed to be invoked before any response to
the request on that connection is processed.
The default implementation does nothing. This only needs to be overridden for specialized
requests that hold the stream id across multiple responses.
See Also:
isLastResponse(Frame)/**
   * Reports the stream id used for the request on the current connection.
   *
   * <p>This is called every time the request is written successfully to a connection (and therefore
   * might multiple times in case of retries). It is guaranteed to be invoked before any response to
   * the request on that connection is processed.
   *
   * <p>The default implementation does nothing. This only needs to be overridden for specialized
   * requests that hold the stream id across multiple responses.
   *
   * @see #isLastResponse(Frame)
   */
  default void onStreamIdAssigned(int streamId) {
    // nothing to do
  }

  
Whether the given frame is the last response to this request.
This is invoked for each response received by this callback; if it returns true, the driver assumes that the server is no longer using this stream id, and that it can be safely reused to send another request. 
The default implementation always returns true: regular CQL requests only have one response, and we can reuse the stream id as soon as we've received it. This only needs to be overridden for specialized requests that hold the stream id across multiple responses. /**
   * Whether the given frame is the last response to this request.
   *
   * <p>This is invoked for each response received by this callback; if it returns {@code true}, the
   * driver assumes that the server is no longer using this stream id, and that it can be safely
   * reused to send another request.
   *
   * <p>The default implementation always returns {@code true}: regular CQL requests only have one
   * response, and we can reuse the stream id as soon as we've received it. This only needs to be
   * overridden for specialized requests that hold the stream id across multiple responses.
   */
  default boolean isLastResponse(Frame responseFrame) {
    return true;
  }
}