/*
 * 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 org.apache.cassandra.net;

import java.util.concurrent.TimeUnit;

import org.apache.cassandra.concurrent.Stage;
import org.apache.cassandra.net.Message.Header;

/**
 * Encapsulates the callbacks that {@link InboundMessageHandler} invokes during the lifecycle of an inbound message
 * passing through it: from arrival to dispatch to execution.
 *
 * The flow will vary slightly between small and large messages. Small messages will be deserialized first and only
 * then dispatched to one of the {@link Stage} stages for execution, whereas a large message will be dispatched first,
 * and deserialized in-place on the relevant stage before being immediately processed.
 *
 * This difference will only show in case of deserialization failure. For large messages, it's possible for
 * {@link #onFailedDeserialize(int, Header, Throwable)} to be invoked after {@link #onExecuting(int, Header, long, TimeUnit)},
 * whereas for small messages it isn't.
 */
interface InboundMessageCallbacks
{
    /**
     * Invoked once the header of a message has arrived, small or large.
     */
    void onHeaderArrived(int messageSize, Header header, long timeElapsed, TimeUnit unit);

    /**
     * Invoked once an entire message worth of bytes has arrived, small or large.
     */
    void onArrived(int messageSize, Header header, long timeElapsed, TimeUnit unit);

    /**
     * Invoked if a message arrived too late to be processed, after its expiration. {@code wasCorrupt} might
     * be set to {@code true} if 1+ corrupt frames were encountered while assembling an expired large message.
     */
    void onArrivedExpired(int messageSize, Header header, boolean wasCorrupt, long timeElapsed, TimeUnit unit);

    /**
     * Invoked if a large message arrived in time, but had one or more of its frames corrupted in flight.
     */
    void onArrivedCorrupt(int messageSize, Header header, long timeElapsed, TimeUnit unit);

    /**
     * Invoked if {@link InboundMessageHandler} was closed before receiving all frames of a large message.
     * {@code wasCorrupt} will be set to {@code true} if some corrupt frames had been already encountered,
     * {@code wasExpired} will be set to {@code true} if the message had expired in flight.
     */
    void onClosedBeforeArrival(int messageSize, Header header, int bytesReceived, boolean wasCorrupt, boolean wasExpired);

    /**
     * Invoked if a deserializer threw an exception while attempting to deserialize a message.
     */
    void onFailedDeserialize(int messageSize, Header header, Throwable t);

    /**
     * Invoked just before a message-processing task is scheduled on the appropriate {@link Stage}
     * for the {@link Verb} of the message.
     */
    void onDispatched(int messageSize, Header header);

    /**
     * Invoked at the very beginning of execution of the message-processing task on the appropriate {@link Stage}.
     */
    void onExecuting(int messageSize, Header header, long timeElapsed, TimeUnit unit);

    /**
     * Invoked upon 'successful' processing of the message. Alternatively, {@link #onExpired(int, Header, long, TimeUnit)}
     * will be invoked if the message had expired while waiting to be processed in the queue of the {@link Stage}.
     */
    void onProcessed(int messageSize, Header header);

    /**
     * Invoked if the message had expired while waiting to be processed in the queue of the {@link Stage}. Otherwise,
     * {@link #onProcessed(int, Header)} will be invoked.
     */
    void onExpired(int messageSize, Header header, long timeElapsed, TimeUnit unit);

    /**
     * Invoked at the very end of execution of the message-processing task, no matter the outcome of processing.
     */
    void onExecuted(int messageSize, Header header, long timeElapsed, TimeUnit unit);
}