/**
 * 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.storm.task;

import java.io.Serializable;
import java.util.Map;
import org.apache.storm.Config;
import org.apache.storm.tuple.Tuple;

/**
 * An IBolt represents a component that takes tuples as input and produces tuples as output. An IBolt can do everything from filtering to
 * joining to functions to aggregations. It does not have to process a tuple immediately and may hold onto tuples to process later.
 *
 * <p>A bolt's lifecycle is as follows:
 *
 * <p>IBolt object created on client machine. The IBolt is serialized into the topology (using Java serialization) and
 * submitted to the master machine of the cluster (Nimbus). Nimbus then launches workers which deserialize the object,
 * call prepare on it, and then start processing tuples.
 *
 * <p>If you want to parameterize an IBolt, you should set the parameters through its constructor and save the parameterization state as
 * instance variables (which will then get serialized and shipped to every task executing this bolt across the cluster).
 *
 * <p>When defining bolts in Java, you should use the IRichBolt interface which adds necessary methods for using the
 * Java TopologyBuilder API.
 */
public interface IBolt extends Serializable {
    /**
     * Called when a task for this component is initialized within a worker on the cluster. It provides the bolt with the environment in
     * which the bolt executes.
     *
     * <p>This includes the:
     *
     * @param topoConf  The Storm configuration for this bolt. This is the configuration provided to the topology merged in with cluster
     *                  configuration on this machine.
     * @param context   This object can be used to get information about this task's place within the topology, including the task id and
     *                  component id of this task, input and output information, etc.
     * @param collector The collector is used to emit tuples from this bolt. Tuples can be emitted at any time, including the prepare and
     *                  cleanup methods. The collector is thread-safe and should be saved as an instance variable of this bolt object.
     */
    void prepare(Map<String, Object> topoConf, TopologyContext context, OutputCollector collector);

    /**
     * Process a single tuple of input. The Tuple object contains metadata on it about which component/stream/task it came from. The values
     * of the Tuple can be accessed using Tuple#getValue. The IBolt does not have to process the Tuple immediately. It is perfectly fine to
     * hang onto a tuple and process it later (for instance, to do an aggregation or join).
     *
     * <p>Tuples should be emitted using the OutputCollector provided through the prepare method. It is required that all input tuples are
     * acked or failed at some point using the OutputCollector. Otherwise, Storm will be unable to determine when tuples coming off the
     * spouts have been completed.
     *
     * <p>For the common case of acking an input tuple at the end of the execute method, see IBasicBolt which automates this.
     *
     * @param input The input tuple to be processed.
     */
    void execute(Tuple input);

    /**
     * Called when an IBolt is going to be shutdown. Storm will make a best-effort attempt to call this if the worker shutdown is orderly.
     * The {@link Config#SUPERVISOR_WORKER_SHUTDOWN_SLEEP_SECS} setting controls how long orderly shutdown is allowed to take.
     * There is no guarantee that cleanup will be called if shutdown is not orderly, or if the shutdown exceeds the time limit.
     *
     * <p>The one context where cleanup is guaranteed to be called is when a topology is killed when running Storm in local mode.
     */
    void cleanup();
}