ISpout源码解析

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

import backtype.storm.task.TopologyContext;
import java.util.Map;
import java.io.Serializable;

/**
 * ISpout is the core interface for implementing spouts. A Spout is responsible
 * for feeding messages into the topology for processing. For every tuple emitted by
 * a spout, Storm will track the (potentially very large) DAG of tuples generated
 * based on a tuple emitted by the spout. When Storm detects that every tuple in
 * that DAG has been successfully processed, it will send an ack message to the Spout.
 *
 * <p>If a tuple fails to be fully processed within the configured timeout for the
 * topology (see {@link backtype.storm.Config}), Storm will send a fail message to the spout
 * for the message.</p>
 *
 * <p> When a Spout emits a tuple, it can tag the tuple with a message id. The message id
 * can be any type. When Storm acks or fails a message, it will pass back to the
 * spout the same message id to identify which tuple it's referring to. If the spout leaves out
 * the message id, or sets it to null, then Storm will not track the message and the spout
 * will not receive any ack or fail callbacks for the message.</p>
 *
 * <p>Storm executes ack, fail, and nextTuple all on the same thread. This means that an implementor
 * of an ISpout does not need to worry about concurrency issues between those methods. However, it 
 * also means that an implementor must ensure that nextTuple is non-blocking: otherwise 
 * the method could block acks and fails that are pending to be processed.</p>
 */
public interface ISpout extends Serializable {
    /**
     * 在群集上的工作程序中初始化此组件的任务时调用。
		它为喷口提供了喷口执行的环境
     *
     * <p>This includes the:</p>
     *
     * @param conf The Storm configuration for this spout. 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 spout. Tuples can be emitted at any time, including the open and close methods. The collector is thread-safe and should be saved as an instance variable of this spout object.
     */
    void open(Map conf, TopologyContext context, SpoutOutputCollector collector);

    /**
     *在ISpout即将关闭时调用。 没有保证关闭
		将被调用，因为主管在集群上杀死-9的工作进程。
		<p>保证调用close的一个上下文是拓扑是 在本地模式下运行Storm时被杀死。</ p>
     */
    void close();
    
    /**
     *当喷嘴已从停用模式激活时调用。
 		 很快就会在这个喷口上调用nextTuple。 
		当使用storm`客户端操作拓扑时，在已停用后，可以激活喷口。
     */
    void activate();
    
    /**
     * 当喷嘴已停用时调用。 在停用spout时，不会调用nextTuple。 喷口可能会或可能不会在将来重新激活。
     */
    void deactivate();

    /**
     * 调用此方法时，Storm会请求Spout向其发出元组
 		输出收集器。 此方法应该是非阻塞的，因此如果Spout没有元组
 		要发出，这个方法应该返回。 nextTuple，ack和fail都是紧张的
 		在spout任务中的单个线程中循环。 当没有元组发出时，
		让nextTuple睡眠很短的时间（如一毫秒）是有礼貌的，这样就不会浪费太多的CPU
     */
    void nextTuple();

    /**
     *Storm确定了这个spout使用msgId标识符发出的元组
		已经完全处理。 通常，此方法的实现将采用该方法
		队列中的消息并阻止它被重播。
     */
    void ack(Object msgId);

    /**
     *这个spout使用msgId标识符发出的元组未能成功
		完全处理。 通常，此方法的实现将提出这一点
		队列中的消息将在稍后重播。.
     */
    void fail(Object msgId);
}