blob: c3a3e05c47ebc91f214e9fe35c036944bfbd0658 [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="en">
<head>
<!-- Generated by javadoc (17) on Thu Sep 15 14:12:07 CDT 2022 -->
<title>Stream (Eclipse Jetty API Doc - v10.0.12)</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="dc.created" content="2022-09-15">
<meta name="description" content="declaration: package: org.eclipse.jetty.http3.api, interface: Stream">
<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.5.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/Stream.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><a href="#nested-class-summary">Nested</a>&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.eclipse.jetty.http3.api</a></div>
<h1 title="Interface Stream" class="title">Interface Stream</h1>
</div>
<section class="class-description" id="class-description">
<dl class="notes">
<dt>All Known Subinterfaces:</dt>
<dd><code><a href="Stream.Client.html" title="interface in org.eclipse.jetty.http3.api">Stream.Client</a></code>, <code><a href="Stream.Server.html" title="interface in org.eclipse.jetty.http3.api">Stream.Server</a></code></dd>
</dl>
<hr>
<div class="type-signature"><span class="modifiers">public interface </span><span class="element-name type-name-label">Stream</span></div>
<div class="block"><p>A <a href="Stream.html" title="interface in org.eclipse.jetty.http3.api"><code>Stream</code></a> represents a bidirectional exchange of data within a <a href="Session.html" title="interface in org.eclipse.jetty.http3.api"><code>Session</code></a>.</p>
<p>A <a href="Stream.html" title="interface in org.eclipse.jetty.http3.api"><code>Stream</code></a> maps to an HTTP/3 request/response cycle, and after the request/response
cycle is completed, the stream is closed and removed from the <a href="Session.html" title="interface in org.eclipse.jetty.http3.api"><code>Session</code></a>.</p>
<p>Like <a href="Session.html" title="interface in org.eclipse.jetty.http3.api"><code>Session</code></a>, <a href="Stream.html" title="interface in org.eclipse.jetty.http3.api"><code>Stream</code></a> is the active part and by calling its API applications
can generate events on the stream; conversely, <a href="Stream.Client.Listener.html" title="interface in org.eclipse.jetty.http3.api"><code>Stream.Client.Listener</code></a> and
<a href="Stream.Server.Listener.html" title="interface in org.eclipse.jetty.http3.api"><code>Stream.Server.Listener</code></a> are the passive part, and their callbacks are invoked when
events happen on the stream.</p>
<p>The client initiates a stream by sending a HEADERS frame containing the HTTP/3 request URI
and request headers, and zero or more DATA frames containing request content.</p>
<p>Similarly, the server responds by sending a HEADERS frame containing the HTTP/3 response
status code and response headers, and zero or more DATA frames containing response content.</p>
<p>Both client and server can end their side of the stream by sending a final frame with
the <code>last</code> flag set to <code>true</code>, see <a href="../frames/HeadersFrame.html#%3Cinit%3E(org.eclipse.jetty.http.MetaData,boolean)"><code>HeadersFrame(MetaData, boolean)</code></a>
and <a href="../frames/DataFrame.html#%3Cinit%3E(java.nio.ByteBuffer,boolean)"><code>DataFrame(ByteBuffer, boolean)</code></a>.</p></div>
</section>
<section class="summary">
<ul class="summary-list">
<!-- ======== NESTED CLASS SUMMARY ======== -->
<li>
<section class="nested-class-summary" id="nested-class-summary">
<h2>Nested Class Summary</h2>
<div class="caption"><span>Nested Classes</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Interface</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>static interface&nbsp;</code></div>
<div class="col-second even-row-color"><code><a href="Stream.Client.html" class="type-name-link" title="interface in org.eclipse.jetty.http3.api">Stream.Client</a></code></div>
<div class="col-last even-row-color">
<div class="block">The client side version of <a href="Stream.html" title="interface in org.eclipse.jetty.http3.api"><code>Stream</code></a>.</div>
</div>
<div class="col-first odd-row-color"><code>static class&nbsp;</code></div>
<div class="col-second odd-row-color"><code><a href="Stream.Data.html" class="type-name-link" title="class in org.eclipse.jetty.http3.api">Stream.Data</a></code></div>
<div class="col-last odd-row-color">
<div class="block">A <a href="Stream.Data.html" title="class in org.eclipse.jetty.http3.api"><code>Stream.Data</code></a> instance associates a <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/ByteBuffer.html" title="class or interface in java.nio" class="external-link"><code>ByteBuffer</code></a>
containing request bytes or response bytes with a completion event
that applications <em>must</em> trigger when the bytes have been
processed.</div>
</div>
<div class="col-first even-row-color"><code>static interface&nbsp;</code></div>
<div class="col-second even-row-color"><code><a href="Stream.Server.html" class="type-name-link" title="interface in org.eclipse.jetty.http3.api">Stream.Server</a></code></div>
<div class="col-last even-row-color">
<div class="block">The server side version of <a href="Stream.html" title="interface in org.eclipse.jetty.http3.api"><code>Stream</code></a>.</div>
</div>
</div>
</section>
</li>
<!-- ========== 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><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html" title="class or interface in java.util.concurrent" class="external-link">CompletableFuture</a>&lt;<a href="Stream.html" title="interface in org.eclipse.jetty.http3.api">Stream</a>&gt;</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#data(org.eclipse.jetty.http3.frames.DataFrame)" class="member-name-link">data</a><wbr>(<a href="../frames/DataFrame.html" title="class in org.eclipse.jetty.http3.frames">DataFrame</a>&nbsp;frame)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Sends the given DATA frame containing some or all the bytes
of the request content or of the response content.</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="#demand()" class="member-name-link">demand</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Causes <a href="Stream.Client.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Client)"><code>Stream.Client.Listener.onDataAvailable(Stream.Client)</code></a>
on the client, or <a href="Stream.Server.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Server)"><code>Stream.Server.Listener.onDataAvailable(Stream.Server)</code></a>
on the server, to be invoked, possibly at a later time, when the stream
has data to be read.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>long</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#getId()" class="member-name-link">getId</a>()</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">&nbsp;</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="Session.html" title="interface in org.eclipse.jetty.http3.api">Session</a></code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#getSession()" class="member-name-link">getSession</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">&nbsp;</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="Stream.Data.html" title="class in org.eclipse.jetty.http3.api">Stream.Data</a></code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#readData()" class="member-name-link">readData</a>()</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Reads request content bytes or response content bytes.</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="#reset(long,java.lang.Throwable)" class="member-name-link">reset</a><wbr>(long&nbsp;error,
<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Throwable.html" title="class or interface in java.lang" class="external-link">Throwable</a>&nbsp;failure)</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Abruptly terminates this stream with the given error.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html" title="class or interface in java.util.concurrent" class="external-link">CompletableFuture</a>&lt;<a href="Stream.html" title="interface in org.eclipse.jetty.http3.api">Stream</a>&gt;</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#trailer(org.eclipse.jetty.http3.frames.HeadersFrame)" class="member-name-link">trailer</a><wbr>(<a href="../frames/HeadersFrame.html" title="class in org.eclipse.jetty.http3.frames">HeadersFrame</a>&nbsp;frame)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Sends the given HEADERS frame containing the trailer headers.</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="getId()">
<h3>getId</h3>
<div class="member-signature"><span class="return-type">long</span>&nbsp;<span class="element-name">getId</span>()</div>
<dl class="notes">
<dt>Returns:</dt>
<dd>the stream id</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="getSession()">
<h3>getSession</h3>
<div class="member-signature"><span class="return-type"><a href="Session.html" title="interface in org.eclipse.jetty.http3.api">Session</a></span>&nbsp;<span class="element-name">getSession</span>()</div>
<dl class="notes">
<dt>Returns:</dt>
<dd>the session this stream is associated to</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="data(org.eclipse.jetty.http3.frames.DataFrame)">
<h3>data</h3>
<div class="member-signature"><span class="return-type"><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html" title="class or interface in java.util.concurrent" class="external-link">CompletableFuture</a>&lt;<a href="Stream.html" title="interface in org.eclipse.jetty.http3.api">Stream</a>&gt;</span>&nbsp;<span class="element-name">data</span><wbr><span class="parameters">(<a href="../frames/DataFrame.html" title="class in org.eclipse.jetty.http3.frames">DataFrame</a>&nbsp;frame)</span></div>
<div class="block"><p>Sends the given DATA frame containing some or all the bytes
of the request content or of the response content.</p></div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>frame</code> - the DATA frame containing some or all the bytes of the request or of the response.</dd>
<dt>Returns:</dt>
<dd>the <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html" title="class or interface in java.util.concurrent" class="external-link"><code>CompletableFuture</code></a> that gets notified when the frame has been sent</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="readData()">
<h3>readData</h3>
<div class="member-signature"><span class="return-type"><a href="Stream.Data.html" title="class in org.eclipse.jetty.http3.api">Stream.Data</a></span>&nbsp;<span class="element-name">readData</span>()</div>
<div class="block"><p>Reads request content bytes or response content bytes.</p>
<p>The returned <a href="Stream.Data.html" title="class in org.eclipse.jetty.http3.api"><code>Stream.Data</code></a> object may be <code>null</code>, indicating
that the end of the read side of the stream has not yet been reached, which
may happen in these cases:</p>
<ul>
<li>not all the bytes have been received so far, for example the remote
peer did not send them yet, or they are in-flight</li>
<li>all the bytes have been received, but there is a trailer HEADERS
frame to be received to indicate the end of the read side of the
stream</li>
</ul>
<p>When the returned <a href="Stream.Data.html" title="class in org.eclipse.jetty.http3.api"><code>Stream.Data</code></a> object is not <code>null</code>,
applications <em>must</em> call, either immediately or later (possibly
asynchronously) <a href="Stream.Data.html#complete()"><code>Stream.Data.complete()</code></a> to notify the
implementation that the bytes have been processed.</p>
<p><a href="Stream.Data.html" title="class in org.eclipse.jetty.http3.api"><code>Stream.Data</code></a> objects may be stored away for later, asynchronous,
processing (for example, to process them only when all of them have been
received).</p></div>
<dl class="notes">
<dt>Returns:</dt>
<dd>a <a href="Stream.Data.html" title="class in org.eclipse.jetty.http3.api"><code>Stream.Data</code></a> object containing the request bytes or
the response bytes, or null if no bytes are available</dd>
<dt>See Also:</dt>
<dd>
<ul class="see-list-long">
<li><a href="Stream.Client.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Client)"><code>Stream.Client.Listener.onDataAvailable(Stream.Client)</code></a></li>
<li><a href="Stream.Server.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Server)"><code>Stream.Server.Listener.onDataAvailable(Stream.Server)</code></a></li>
</ul>
</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="demand()">
<h3>demand</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">demand</span>()</div>
<div class="block"><p>Causes <a href="Stream.Client.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Client)"><code>Stream.Client.Listener.onDataAvailable(Stream.Client)</code></a>
on the client, or <a href="Stream.Server.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Server)"><code>Stream.Server.Listener.onDataAvailable(Stream.Server)</code></a>
on the server, to be invoked, possibly at a later time, when the stream
has data to be read.</p>
<p>This method is idempotent: calling it when there already is an
outstanding demand to invoke <code>onDataAvailable(Stream)</code>
is a no-operation.</p>
<p>The thread invoking this method may invoke directly
<code>onDataAvailable(Stream)</code>, unless another thread
that must invoke <code>onDataAvailable(Stream)</code>
notices the outstanding demand first.</p>
<p>When all bytes have been read (via <a href="#readData()"><code>readData()</code></a>), further
invocations of this method are a no-operation.</p>
<p>It is always guaranteed that invoking this method from within
<code>onDataAvailable(Stream)</code> will not cause a
<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/StackOverflowError.html" title="class or interface in java.lang" class="external-link"><code>StackOverflowError</code></a>.</p></div>
<dl class="notes">
<dt>See Also:</dt>
<dd>
<ul class="see-list-long">
<li><a href="#readData()"><code>readData()</code></a></li>
<li><a href="Stream.Client.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Client)"><code>Stream.Client.Listener.onDataAvailable(Stream.Client)</code></a></li>
<li><a href="Stream.Server.Listener.html#onDataAvailable(org.eclipse.jetty.http3.api.Stream.Server)"><code>Stream.Server.Listener.onDataAvailable(Stream.Server)</code></a></li>
</ul>
</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="trailer(org.eclipse.jetty.http3.frames.HeadersFrame)">
<h3>trailer</h3>
<div class="member-signature"><span class="return-type"><a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html" title="class or interface in java.util.concurrent" class="external-link">CompletableFuture</a>&lt;<a href="Stream.html" title="interface in org.eclipse.jetty.http3.api">Stream</a>&gt;</span>&nbsp;<span class="element-name">trailer</span><wbr><span class="parameters">(<a href="../frames/HeadersFrame.html" title="class in org.eclipse.jetty.http3.frames">HeadersFrame</a>&nbsp;frame)</span></div>
<div class="block"><p>Sends the given HEADERS frame containing the trailer headers.</p></div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>frame</code> - the HEADERS frame containing the trailer headers</dd>
<dt>Returns:</dt>
<dd>the <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html" title="class or interface in java.util.concurrent" class="external-link"><code>CompletableFuture</code></a> that gets notified when the frame has been sent</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="reset(long,java.lang.Throwable)">
<h3>reset</h3>
<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">reset</span><wbr><span class="parameters">(long&nbsp;error,
<a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Throwable.html" title="class or interface in java.lang" class="external-link">Throwable</a>&nbsp;failure)</span></div>
<div class="block"><p>Abruptly terminates this stream with the given error.</p></div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>error</code> - the error code</dd>
<dd><code>failure</code> - the failure that caused the reset of the stream</dd>
</dl>
</section>
</li>
</ul>
</section>
</li>
</ul>
</section>
<!-- ========= END OF CLASS DATA ========= -->
</main>
<footer role="contentinfo">
<hr>
<p class="legal-copy"><small>Copyright &#169; 1995&#x2013;2022 <a href="https://webtide.com">Webtide</a>. All rights reserved.</small></p>
</footer>
</div>
</div>
</body>
</html>