Google Git
Sign in
android / platform / tools / dokka-devsite-plugin / c2f2ba9c887aa0cc0def9a7914ce77d8262d6dd5 / . / testData / paging / docs / reference / kotlin / androidx / paging / RemoteMediator.html
blob: 51fccfde7b8b5ca5d03bc52fe27b2ed45118a0be [file] [log] [blame]
<html devsite="true">
<head>
<title>RemoteMediator</title>
{% setvar book_path %}/reference/kotlin/androidx/_book.yaml{% endsetvar %}
{% include "_shared/_reference-head-tags.html" %}
</head>
<body>
<h1>RemoteMediator</h1>
{% setvar page_path %}androidx/paging/RemoteMediator.html{% endsetvar %}
{% setvar can_switch %}1{% endsetvar %}
{% include "reference/_kotlin_switcher2.md" %}
<p>
<pre>abstract class RemoteMediator</pre>
</p>
<div class="devsite-table-wrapper"><devsite-expandable><span class="expand-control jd-sumtable-subclasses">Known direct subclasses
<div class="showalways" id="subclasses-direct"><a href="/reference/kotlin/androidx/paging/ListenableFutureRemoteMediator.html">ListenableFutureRemoteMediator</a>, <a href="/reference/kotlin/androidx/paging/rxjava2/RxRemoteMediator.html">RxRemoteMediator</a>, <a href="/reference/kotlin/androidx/paging/rxjava3/RxRemoteMediator.html">RxRemoteMediator</a></div>
</span>
<div id="subclasses-direct-summary">
<div class="devsite-table-wrapper">
<table class="responsive">
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/ListenableFutureRemoteMediator.html">ListenableFutureRemoteMediator</a></code></td>
<td width="100%">
<p>ListenableFuture-based compatibility wrapper around <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html">RemoteMediator</a></code>'s suspending APIs.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/rxjava2/RxRemoteMediator.html">RxRemoteMediator</a></code></td>
<td width="100%">
<p>RxJava2 compatibility wrapper around <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html">RemoteMediator</a></code>'s suspending APIs.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/rxjava3/RxRemoteMediator.html">RxRemoteMediator</a></code></td>
<td width="100%">
<p>RxJava3 compatibility wrapper around <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html">RemoteMediator</a></code>'s suspending APIs.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</devsite-expandable> </div>
<hr>
<p>Defines a set of callbacks, which may be optionally registered when constructing a <code><a href="/reference/kotlin/androidx/paging/Pager.html">Pager</a></code>, that allow for control of the following events:</p>
<ul>
<li>
<p>Stream initialization</p>
</li>
<li>
<p><code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> signal driven from UI</p>
</li>
<li>
<p><code><a href="/reference/kotlin/androidx/paging/PagingSource.html">PagingSource</a></code> returns a <code><a href="/reference/kotlin/androidx/paging/PagingSource.LoadResult.html">PagingSource.LoadResult</a></code> which signals a boundary condition, i.e., the first page for <code><a href="/reference/kotlin/androidx/paging/LoadType.PREPEND.html">LoadType.PREPEND</a></code> or the last page for <code><a href="/reference/kotlin/androidx/paging/LoadType.APPEND.html">LoadType.APPEND</a></code>.</p>
</li>
</ul>
<p>These events together can be used to implement layered pagination - network + local storage.</p>
<h2>Summary</h2>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2"><h3>Nested types</h3></th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.InitializeAction.html">RemoteMediator.InitializeAction</a></code></td>
<td width="100%">
<p>Return type of <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#initialize()">initialize</a></code>, which signals the action to take after <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#initialize()">initialize</a></code> completes.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.html">RemoteMediator.MediatorResult</a></code></td>
<td width="100%">
<p>Return type of <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#load(androidx.paging.LoadType,androidx.paging.PagingState)">load</a></code>, which determines <code><a href="/reference/kotlin/androidx/paging/LoadState.html">LoadState</a></code>.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.Error.html">RemoteMediator.MediatorResult.Error</a></code></td>
<td width="100%">
<p>Recoverable error that can be retried, sets the <code><a href="/reference/kotlin/androidx/paging/LoadState.html">LoadState</a></code> to <code><a href="/reference/kotlin/androidx/paging/LoadState.Error.html">LoadState.Error</a></code>.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.Success.html">RemoteMediator.MediatorResult.Success</a></code></td>
<td width="100%">
<p>Success signaling that <code><a href="/reference/kotlin/androidx/paging/LoadState.html">LoadState</a></code> should be set to <code><a href="/reference/kotlin/androidx/paging/LoadState.NotLoading.html">LoadState.NotLoading</a></code> if <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.Success.html#endOfPaginationReached()">endOfPaginationReached</a></code> is <code>true</code>, otherwise <code><a href="/reference/kotlin/androidx/paging/LoadState.html">LoadState</a></code> is kept at <code><a href="/reference/kotlin/androidx/paging/LoadState.Loading.html">LoadState.Loading</a></code> to await invalidation.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2"><h3>Public constructors</h3></th>
</tr>
</thead>
<tbody>
<tr>
<td>
<div><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#RemoteMediator()">RemoteMediator</a>()</code></div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2"><h3>Public functions</h3></th>
</tr>
</thead>
<tbody>
<tr>
<td><code>suspend&nbsp;open <a href="/reference/kotlin/androidx/paging/RemoteMediator.InitializeAction.html">RemoteMediator.InitializeAction</a></code></td>
<td width="100%">
<div><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#initialize()">initialize</a>()</code></div>
<p>Callback fired during initialization of a <code><a href="/reference/kotlin/androidx/paging/PagingData.html">PagingData</a></code> stream, before initial load.</p>
</td>
</tr>
<tr>
<td><code>suspend&nbsp;abstract <a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.html">RemoteMediator.MediatorResult</a></code></td>
<td width="100%">
<div><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#load(androidx.paging.LoadType,androidx.paging.PagingState)">load</a>(loadType:&nbsp;<a href="/reference/kotlin/androidx/paging/LoadType.html">LoadType</a>,&nbsp;state:&nbsp;<a href="/reference/kotlin/androidx/paging/PagingState.html">PagingState</a>&lt;Key,&nbsp;Value&gt;)</code></div>
<p>Implement this method to load additional remote data, which will then be stored for the <code><a href="/reference/kotlin/androidx/paging/PagingSource.html">PagingSource</a></code> to access.</p>
</td>
</tr>
</tbody>
</table>
</div>
<h2>Public constructors</h2>
<div><a name="RemoteMediator--"></a>
<h3 class="api-name" id="RemoteMediator()">RemoteMediator</h3>
<pre class="api-signature no-pretty-print"><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#RemoteMediator()">RemoteMediator</a>()</pre>
</div>
<h2>Public functions</h2>
<div><a name="initialize--"></a>
<h3 class="api-name" id="initialize()">initialize</h3>
<pre class="api-signature no-pretty-print">suspend&nbsp;open&nbsp;fun&nbsp;<a href="/reference/kotlin/androidx/paging/RemoteMediator.html#initialize()">initialize</a>():&nbsp;<a href="/reference/kotlin/androidx/paging/RemoteMediator.InitializeAction.html">RemoteMediator.InitializeAction</a></pre>
<p>Callback fired during initialization of a <code><a href="/reference/kotlin/androidx/paging/PagingData.html">PagingData</a></code> stream, before initial load.</p>
<p>This function runs to completion before any loading is performed.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.InitializeAction.html">RemoteMediator.InitializeAction</a></code></td>
<td width="100%">
<p><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.InitializeAction.html">InitializeAction</a></code> indicating the action to take after initialization:</p>
<ul>
<li>
<p><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.InitializeAction.LAUNCH_INITIAL_REFRESH.html">LAUNCH_INITIAL_REFRESH</a></code> to immediately dispatch a <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#load(androidx.paging.LoadType,androidx.paging.PagingState)">load</a></code> asynchronously with load type <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code>, to update paginated content when the stream is initialized.</p>
</li>
<li>
<p><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.InitializeAction.SKIP_INITIAL_REFRESH.html">SKIP_INITIAL_REFRESH</a></code> to wait for a refresh request from the UI before dispatching a <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#load(androidx.paging.LoadType,androidx.paging.PagingState)">load</a></code> with load type <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code>.</p>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div><a name="load(androidx.paging.LoadType, androidx.paging.PagingState)"></a><a name="load-androidx.paging.LoadType-androidx.paging.PagingState-"></a>
<h3 class="api-name" id="load(androidx.paging.LoadType,androidx.paging.PagingState)">load</h3>
<pre class="api-signature no-pretty-print">suspend&nbsp;abstract&nbsp;fun&nbsp;<a href="/reference/kotlin/androidx/paging/RemoteMediator.html#load(androidx.paging.LoadType,androidx.paging.PagingState)">load</a>(loadType:&nbsp;<a href="/reference/kotlin/androidx/paging/LoadType.html">LoadType</a>,&nbsp;state:&nbsp;<a href="/reference/kotlin/androidx/paging/PagingState.html">PagingState</a>&lt;Key,&nbsp;Value&gt;):&nbsp;<a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.html">RemoteMediator.MediatorResult</a></pre>
<p>Implement this method to load additional remote data, which will then be stored for the <code><a href="/reference/kotlin/androidx/paging/PagingSource.html">PagingSource</a></code> to access. These loads take one of two forms:</p>
<ul>
<li>
<p>type == <code><a href="/reference/kotlin/androidx/paging/LoadType.PREPEND.html">LoadType.PREPEND</a></code> / <code><a href="/reference/kotlin/androidx/paging/LoadType.APPEND.html">LoadType.APPEND</a></code> The <code><a href="/reference/kotlin/androidx/paging/PagingSource.html">PagingSource</a></code> has loaded a 'boundary' page, with a <code>null</code> adjacent key. This means this method should load additional remote data to append / prepend as appropriate, and store it locally.</p>
</li>
<li>
<p>type == <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> The app (or <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#initialize()">initialize</a></code>) has requested a remote refresh of data. This means the method should generally load remote data, and <b>replace</b> all local data.</p>
</li>
</ul>
<p>The runtime of this method defines loading state behavior in boundary conditions, which affects e.g., <code><a href="/reference/kotlin/androidx/paging/LoadState.html">LoadState</a></code> callbacks registered to <code><a href="/reference/kotlin/androidx/paging/PagingDataAdapter.html">androidx.paging.PagingDataAdapter</a></code>.</p>
<p>NOTE: A <code><a href="/reference/kotlin/androidx/paging/PagingSource.html#load(androidx.paging.PagingSource.LoadParams)">PagingSource.load</a></code> request which is fulfilled by a page that hits a boundary condition in either direction will trigger this callback with <code><a href="/reference/kotlin/androidx/paging/LoadType.PREPEND.html">LoadType.PREPEND</a></code> or <code><a href="/reference/kotlin/androidx/paging/LoadType.APPEND.html">LoadType.APPEND</a></code> or both. <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> occurs as a result of <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#initialize()">initialize</a></code> or if refresh is requested programmatically (e.g. in response to a pull to refresh action).</p>
<p>This method is never called concurrently <em>unless</em><code><a href="/reference/kotlin/androidx/paging/Pager.html#flow()">Pager.flow</a></code> has multiple collectors. Note that Paging might cancel calls to this function if it is currently executing a <code><a href="/reference/kotlin/androidx/paging/LoadType.PREPEND.html">LoadType.PREPEND</a></code> or <code><a href="/reference/kotlin/androidx/paging/LoadType.APPEND.html">LoadType.APPEND</a></code> and a <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> is requested. In that case, <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> has higher priority and will be executed after the previous call is cancelled. If the <code>load</code> call with <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> returns an error, Paging will call <code>load</code> with the previously cancelled <code><a href="/reference/kotlin/androidx/paging/LoadType.APPEND.html">LoadType.APPEND</a></code> or <code><a href="/reference/kotlin/androidx/paging/LoadType.PREPEND.html">LoadType.PREPEND</a></code> request. If the <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> succeeds, it won't make the <code><a href="/reference/kotlin/androidx/paging/LoadType.APPEND.html">LoadType.APPEND</a></code> or <code><a href="/reference/kotlin/androidx/paging/LoadType.PREPEND.html">LoadType.PREPEND</a></code> requests unless they are necessary again after the <code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> is applied to the UI.</p>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.html">RemoteMediator.MediatorResult</a></code></td>
<td width="100%">
<p><code><a href="/reference/kotlin/androidx/paging/RemoteMediator.MediatorResult.html">MediatorResult</a></code> signifying what <code><a href="/reference/kotlin/androidx/paging/LoadState.html">LoadState</a></code> to be passed to the UI, and whether there's more data available.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="devsite-table-wrapper">
<table class="responsive">
<thead>
<tr>
<th colspan="2">Parameters</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>loadType</code></td>
<td width="100%">
<p><code><a href="/reference/kotlin/androidx/paging/LoadType.html">LoadType</a></code> of the boundary condition which triggered this callback.</p>
<ul>
<li>
<p><code><a href="/reference/kotlin/androidx/paging/LoadType.PREPEND.html">LoadType.PREPEND</a></code> indicates a boundary condition at the front of the list.</p>
</li>
<li>
<p><code><a href="/reference/kotlin/androidx/paging/LoadType.APPEND.html">LoadType.APPEND</a></code> indicates a boundary condition at the end of the list.</p>
</li>
<li>
<p><code><a href="/reference/kotlin/androidx/paging/LoadType.REFRESH.html">LoadType.REFRESH</a></code> indicates this callback was triggered as the result of a requested refresh - either driven by the UI, or by <code><a href="/reference/kotlin/androidx/paging/RemoteMediator.html#initialize()">initialize</a></code>.</p>
</li>
</ul>
</td>
</tr>
<tr>
<td><code>state</code></td>
<td width="100%">
<p>A copy of the state including the list of pages currently held in memory of the currently presented <code><a href="/reference/kotlin/androidx/paging/PagingData.html">PagingData</a></code> at the time of starting the load. E.g. for load(loadType = END), you can use the page or item at the end as input for what to load from the network.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</body>
</html>