blob: b476bcb8141a7f690eec261c4272e5394447b19a [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="de">
<head>
<!-- Generated by javadoc (17) -->
<title>ISpout (Storm 2.6.2 API)</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="description" content="declaration: package: org.apache.storm.spout, interface: ISpout">
<meta name="generator" content="javadoc/ClassWriterImpl">
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../../script-dir/jquery-ui.min.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../../jquery-ui.overrides.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
<script type="text/javascript" src="../../../../script-dir/jquery-3.6.1.min.js"></script>
<script type="text/javascript" src="../../../../script-dir/jquery-ui.min.js"></script>
</head>
<body class="class-declaration-page">
<script type="text/javascript">var evenRowColor = "even-row-color";
var oddRowColor = "odd-row-color";
var tableTab = "table-tab";
var activeTableTab = "active-table-tab";
var pathtoroot = "../../../../";
loadScripts(document, 'script');</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<div class="flex-box">
<header role="banner" class="flex-header">
<nav role="navigation">
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="top-nav" id="navbar-top">
<div class="skip-nav"><a href="#skip-navbar-top" title="Skip navigation links">Skip navigation links</a></div>
<ul id="navbar-top-firstrow" class="nav-list" title="Navigation">
<li><a href="../../../../index.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="nav-bar-cell1-rev">Class</li>
<li><a href="class-use/ISpout.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html#class">Help</a></li>
</ul>
</div>
<div class="sub-nav">
<div>
<ul class="sub-nav-list">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method-summary">Method</a></li>
</ul>
<ul class="sub-nav-list">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method-detail">Method</a></li>
</ul>
</div>
<div class="nav-list-search"><label for="search-input">SEARCH:</label>
<input type="text" id="search-input" value="search" disabled="disabled">
<input type="reset" id="reset-button" value="reset" disabled="disabled">
</div>
</div>
<!-- ========= END OF TOP NAVBAR ========= -->
<span class="skip-nav" id="skip-navbar-top"></span></nav>
</header>
<div class="flex-content">
<main role="main">
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="sub-title"><span class="package-label-in-type">Package</span>&nbsp;<a href="package-summary.html">org.apache.storm.spout</a></div>
<h1 title="Interface ISpout" class="title">Interface ISpout</h1>
</div>
<section class="class-description" id="class-description">
<dl class="notes">
<dt>All Superinterfaces:</dt>
<dd><code><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/Serializable.html" title="class or interface in java.io" class="external-link">Serializable</a></code></dd>
</dl>
<dl class="notes">
<dt>All Known Subinterfaces:</dt>
<dd><code><a href="../topology/IRichSpout.html" title="interface in org.apache.storm.topology">IRichSpout</a></code></dd>
</dl>
<dl class="notes">
<dt>All Known Implementing Classes:</dt>
<dd><code><a href="../starter/AnchoredWordCount.RandomSentenceSpout.html" title="class in org.apache.storm.starter">AnchoredWordCount.RandomSentenceSpout</a></code>, <code><a href="../topology/base/BaseRichSpout.html" title="class in org.apache.storm.topology.base">BaseRichSpout</a></code>, <code><a href="../starter/BlobStoreAPIWordCountTopology.RandomSentenceSpout.html" title="class in org.apache.storm.starter">BlobStoreAPIWordCountTopology.RandomSentenceSpout</a></code>, <code><a href="../hive/bolt/BucketTestHiveTopology.UserDataSpout.html" title="class in org.apache.storm.hive.bolt">BucketTestHiveTopology.UserDataSpout</a></code>, <code><a href="CheckpointSpout.html" title="class in org.apache.storm.spout">CheckpointSpout</a></code>, <code><a href="../clojure/ClojureSpout.html" title="class in org.apache.storm.clojure">ClojureSpout</a></code>, <code><a href="../perf/spout/ConstSpout.html" title="class in org.apache.storm.perf.spout">ConstSpout</a></code>, <code><a href="../drpc/DRPCSpout.html" title="class in org.apache.storm.drpc">DRPCSpout</a></code>, <code><a href="../elasticsearch/bolt/EsIndexTopology.UserDataSpout.html" title="class in org.apache.storm.elasticsearch.bolt">EsIndexTopology.UserDataSpout</a></code>, <code><a href="../ExclamationTopology.FixedOrderWordSpout.html" title="class in org.apache.storm">ExclamationTopology.FixedOrderWordSpout</a></code>, <code><a href="../starter/FastWordCountTopology.FastRandomSentenceSpout.html" title="class in org.apache.storm.starter">FastWordCountTopology.FastRandomSentenceSpout</a></code>, <code><a href="../testing/FeederSpout.html" title="class in org.apache.storm.testing">FeederSpout</a></code>, <code><a href="../perf/spout/FileReadSpout.html" title="class in org.apache.storm.perf.spout">FileReadSpout</a></code>, <code><a href="../testing/FixedTupleSpout.html" title="class in org.apache.storm.testing">FixedTupleSpout</a></code>, <code><a href="../flux/wrappers/spouts/FluxShellSpout.html" title="class in org.apache.storm.flux.wrappers.spouts">FluxShellSpout</a></code>, <code><a href="../hdfs/bolt/HdfsFileTopology.SentenceSpout.html" title="class in org.apache.storm.hdfs.bolt">HdfsFileTopology.SentenceSpout</a></code>, <code><a href="../hdfs/spout/HdfsSpout.html" title="class in org.apache.storm.hdfs.spout">HdfsSpout</a></code>, <code><a href="../hive/bolt/HiveTopology.UserDataSpout.html" title="class in org.apache.storm.hive.bolt">HiveTopology.UserDataSpout</a></code>, <code><a href="../hive/bolt/HiveTopologyPartitioned.UserDataSpout.html" title="class in org.apache.storm.hive.bolt">HiveTopologyPartitioned.UserDataSpout</a></code>, <code><a href="../st/topology/window/IncrementingSpout.html" title="class in org.apache.storm.st.topology.window">IncrementingSpout</a></code>, <code><a href="../starter/InOrderDeliveryTest.InOrderSpout.html" title="class in org.apache.storm.starter">InOrderDeliveryTest.InOrderSpout</a></code>, <code><a href="../jms/spout/JmsSpout.html" title="class in org.apache.storm.jms.spout">JmsSpout</a></code>, <code><a href="../kafka/spout/KafkaSpout.html" title="class in org.apache.storm.kafka.spout">KafkaSpout</a></code>, <code><a href="../lambda/LambdaSpout.html" title="class in org.apache.storm.lambda">LambdaSpout</a></code>, <code><a href="../loadgen/LoadSpout.html" title="class in org.apache.storm.loadgen">LoadSpout</a></code>, <code><a href="../trident/topology/MasterBatchCoordinator.html" title="class in org.apache.storm.trident.topology">MasterBatchCoordinator</a></code>, <code><a href="../testing/PythonShellMetricsSpout.html" title="class in org.apache.storm.testing">PythonShellMetricsSpout</a></code>, <code><a href="../starter/spout/RandomIntegerSpout.html" title="class in org.apache.storm.starter.spout">RandomIntegerSpout</a></code>, <code><a href="../starter/spout/RandomSentenceSpout.html" title="class in org.apache.storm.starter.spout">RandomSentenceSpout</a></code>, <code><a href="../starter/spout/RandomSentenceSpout.TimeStamped.html" title="class in org.apache.storm.starter.spout">RandomSentenceSpout.TimeStamped</a></code>, <code><a href="../clojure/RichShellSpout.html" title="class in org.apache.storm.clojure">RichShellSpout</a></code>, <code><a href="../trident/spout/RichSpoutBatchTriggerer.html" title="class in org.apache.storm.trident.spout">RichSpoutBatchTriggerer</a></code>, <code><a href="../hdfs/bolt/SequenceFileTopology.SentenceSpout.html" title="class in org.apache.storm.hdfs.bolt">SequenceFileTopology.SentenceSpout</a></code>, <code><a href="ShellSpout.html" title="class in org.apache.storm.spout">ShellSpout</a></code>, <code><a href="../sql/runtime/datasource/socket/spout/SocketSpout.html" title="class in org.apache.storm.sql.runtime.datasource.socket.spout">SocketSpout</a></code>, <code><a href="../testing/SpoutTracker.html" title="class in org.apache.storm.testing">SpoutTracker</a></code>, <code><a href="../perf/spout/StringGenSpout.html" title="class in org.apache.storm.perf.spout">StringGenSpout</a></code>, <code><a href="../testing/TestEventLogSpout.html" title="class in org.apache.storm.testing">TestEventLogSpout</a></code>, <code><a href="../testing/TestPlannerSpout.html" title="class in org.apache.storm.testing">TestPlannerSpout</a></code>, <code><a href="../testing/TestWordSpout.html" title="class in org.apache.storm.testing">TestWordSpout</a></code>, <code><a href="../loadgen/ThroughputVsLatency.FastRandomSentenceSpout.html" title="class in org.apache.storm.loadgen">ThroughputVsLatency.FastRandomSentenceSpout</a></code>, <code><a href="../st/topology/window/TimeDataIncrementingSpout.html" title="class in org.apache.storm.st.topology.window">TimeDataIncrementingSpout</a></code>, <code><a href="../jdbc/spout/UserSpout.html" title="class in org.apache.storm.jdbc.spout">UserSpout</a></code>, <code><a href="../starter/WordCountTopologyNode.RandomSentence.html" title="class in org.apache.storm.starter">WordCountTopologyNode.RandomSentence</a></code>, <code><a href="../perf/spout/WordGenSpout.html" title="class in org.apache.storm.perf.spout">WordGenSpout</a></code>, <code><a href="../redis/topology/WordSpout.html" title="class in org.apache.storm.redis.topology">WordSpout</a></code></dd>
</dl>
<hr>
<div class="type-signature"><span class="modifiers">public interface </span><span class="element-name type-name-label">ISpout</span><span class="extends-implements">
extends <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/Serializable.html" title="class or interface in java.io" class="external-link">Serializable</a></span></div>
<div class="block">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
<a href="../Config.html" title="class in org.apache.storm"><code>Config</code></a>), Storm will send a fail message to the spout for the message.
<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>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.</div>
</section>
<section class="summary">
<ul class="summary-list">
<!-- ========== METHOD SUMMARY =========== -->
<li>
<section class="method-summary" id="method-summary">
<h2>Method Summary</h2>
<div id="method-summary-table">
<div class="table-tabs" role="tablist" aria-orientation="horizontal"><button id="method-summary-table-tab0" role="tab" aria-selected="true" aria-controls="method-summary-table.tabpanel" tabindex="0" onkeydown="switchTab(event)" onclick="show('method-summary-table', 'method-summary-table', 3)" class="active-table-tab">All Methods</button><button id="method-summary-table-tab2" role="tab" aria-selected="false" aria-controls="method-summary-table.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('method-summary-table', 'method-summary-table-tab2', 3)" class="table-tab">Instance Methods</button><button id="method-summary-table-tab3" role="tab" aria-selected="false" aria-controls="method-summary-table.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('method-summary-table', 'method-summary-table-tab3', 3)" class="table-tab">Abstract Methods</button></div>
<div id="method-summary-table.tabpanel" role="tabpanel">
<div class="summary-table three-column-summary" aria-labelledby="method-summary-table-tab0">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Method</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#ack(java.lang.Object)" class="member-name-link">ack</a><wbr>(<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>&nbsp;msgId)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Storm has determined that the tuple emitted by this spout with the msgId identifier has been fully processed.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#activate()" class="member-name-link">activate</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Called when a spout has been activated out of a deactivated mode. nextTuple will be called on this spout soon.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#close()" class="member-name-link">close</a>()</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Called when an ISpout is going to be shutdown.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#deactivate()" class="member-name-link">deactivate</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Called when a spout has been deactivated. nextTuple will not be called while a spout is deactivated.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#fail(java.lang.Object)" class="member-name-link">fail</a><wbr>(<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>&nbsp;msgId)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">The tuple emitted by this spout with the msgId identifier has failed to be fully processed.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#nextTuple()" class="member-name-link">nextTuple</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">When this method is called, Storm is requesting that the Spout emit tuples to the output collector.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#open(java.util.Map,org.apache.storm.task.TopologyContext,org.apache.storm.spout.SpoutOutputCollector)" class="member-name-link">open</a><wbr>(<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a>,<wbr><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>&gt;&nbsp;conf,
<a href="../task/TopologyContext.html" title="class in org.apache.storm.task">TopologyContext</a>&nbsp;context,
<a href="SpoutOutputCollector.html" title="class in org.apache.storm.spout">SpoutOutputCollector</a>&nbsp;collector)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Called when a task for this component is initialized within a worker on the cluster.</div>
</div>
</div>
</div>
</div>
</section>
</li>
</ul>
</section>
<section class="details">
<ul class="details-list">
<!-- ============ METHOD DETAIL ========== -->
<li>
<section class="method-details" id="method-detail">
<h2>Method Details</h2>
<ul class="member-list">
<li>
<section class="detail" id="open(java.util.Map,org.apache.storm.task.TopologyContext,org.apache.storm.spout.SpoutOutputCollector)">
<h3>open</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">open</span><wbr><span class="parameters">(<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a>,<wbr><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>&gt;&nbsp;conf,
<a href="../task/TopologyContext.html" title="class in org.apache.storm.task">TopologyContext</a>&nbsp;context,
<a href="SpoutOutputCollector.html" title="class in org.apache.storm.spout">SpoutOutputCollector</a>&nbsp;collector)</span></div>
<div class="block">Called when a task for this component is initialized within a worker on the cluster. It provides the spout with the environment in
which the spout executes.
<p>This includes the:</div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>conf</code> - The Storm configuration for this spout. This is the configuration provided to the topology merged in with cluster
configuration on this machine.</dd>
<dd><code>context</code> - 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.</dd>
<dd><code>collector</code> - 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.</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="close()">
<h3>close</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">close</span>()</div>
<div class="block">Called when an ISpout is going to be shutdown. There is no guarentee that close will be called, because the supervisor kill -9's
worker processes on the cluster.
<p>The one context where close is guaranteed to be called is a topology is killed when running Storm in local mode.</div>
</section>
</li>
<li>
<section class="detail" id="activate()">
<h3>activate</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">activate</span>()</div>
<div class="block">Called when a spout has been activated out of a deactivated mode. nextTuple will be called on this spout soon. A spout can become
activated after having been deactivated when the topology is manipulated using the `storm` client.</div>
</section>
</li>
<li>
<section class="detail" id="deactivate()">
<h3>deactivate</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">deactivate</span>()</div>
<div class="block">Called when a spout has been deactivated. nextTuple will not be called while a spout is deactivated. The spout may or may not be
reactivated in the future.</div>
</section>
</li>
<li>
<section class="detail" id="nextTuple()">
<h3>nextTuple</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">nextTuple</span>()</div>
<div class="block">When this method is called, Storm is requesting that the Spout emit tuples to the output collector. This method should be
non-blocking, so if the Spout has no tuples to emit, this method should return. nextTuple, ack, and fail are all called in a tight
loop in a single thread in the spout task. When there are no tuples to emit, it is courteous to have nextTuple sleep for a short
amount of time (like a single millisecond) so as not to waste too much CPU.</div>
</section>
</li>
<li>
<section class="detail" id="ack(java.lang.Object)">
<h3>ack</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">ack</span><wbr><span class="parameters">(<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>&nbsp;msgId)</span></div>
<div class="block">Storm has determined that the tuple emitted by this spout with the msgId identifier has been fully processed. Typically, an
implementation of this method will take that message off the queue and prevent it from being replayed.</div>
</section>
</li>
<li>
<section class="detail" id="fail(java.lang.Object)">
<h3>fail</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">fail</span><wbr><span class="parameters">(<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html" title="class or interface in java.lang" class="external-link">Object</a>&nbsp;msgId)</span></div>
<div class="block">The tuple emitted by this spout with the msgId identifier has failed to be fully processed. Typically, an implementation of this
method will put that message back on the queue to be replayed at a later time.</div>
</section>
</li>
</ul>
</section>
</li>
</ul>
</section>
<!-- ========= END OF CLASS DATA ========= -->
</main>
<footer role="contentinfo">
<hr>
<p class="legal-copy"><small>Copyright &#169; 2023 <a href="https://www.apache.org/">The Apache Software Foundation</a>. All rights reserved.</small></p>
</footer>
</div>
</div>
</body>
</html>