Skip to content

docs(generated): remove beta from changes follower #708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 9, 2025
Merged

docs(generated): remove beta from changes follower #708

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 45 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,13 @@ to avoid surprises.
* [Error handling](#error-handling)
* [Raw IO](#raw-io)
* [Further resources](#further-resources)
* [Changes feed follower (beta)](#changes-feed-follower-beta)
* [Changes feed follower](#changes-feed-follower)
+ [Introduction](#introduction)
+ [Modes of operation](#modes-of-operation)
+ [Configuring the changes follower](#configuring-the-changes-follower)
+ [Error suppression](#error-suppression)
+ [Follower operation](#follower-operation)
+ [Checkpointing](#checkpointing)
+ [Checkpoints](#checkpoints)
+ [Code examples](#code-examples-1)
- [Initializing a changes follower](#initializing-a-changes-follower)
- [Starting the changes follower](#starting-the-changes-follower)
Expand Down Expand Up @@ -96,7 +96,7 @@ project:
- Handles the authentication.
- Familiar user experience with IBM Cloud SDKs.
- Flexibility to use either built-in models or byte-based requests and responses for documents.
- Built-in [Changes feed follower](#changes-feed-follower-beta) (beta)
- Built-in [Changes feed follower](#changes-feed-follower)
- HTTP2 support for higher performance connections to IBM Cloudant.
- Perform requests either synchronously or asynchronously.
- Instances of the client are unconditionally thread-safe.
Expand Down Expand Up @@ -763,13 +763,13 @@ Expand them to see examples of:
- [Cloudant blog](https://blog.cloudant.com/):
Many useful articles about how to optimize Cloudant for common problems.

### Changes feed follower (beta)
### Changes feed follower

#### Introduction

The SDK provides a changes feed follower utility (currently beta).
The SDK provides a changes feed follower utility.
This helper utility connects to the `_changes` endpoint and returns the individual change items.
It removes some of the complexity of using the `_changes` endpoint by setting some options automatically
It removes some complexity of using the `_changes` endpoint by setting some options automatically
and providing error suppression and retries.

*Tip: the changes feed often does not meet user expectations or assumptions.*
Expand All @@ -781,52 +781,52 @@ to get a better understanding of the limitations and suitable use-cases before u

There are two modes of operation:
* Start mode
* Fetches the changes from the supplied `since` sequence (by default the feed will start from `now`).
* Fetches the changes from the supplied `since` sequence (in this mode follower defaults to reading the feed from `now`).
* Fetches all available changes and then continues listening for new changes indefinitely unless encountering an end condition.
* An example use case for this mode is event driven workloads.
* Start one-off mode
* Fetches the changes from the supplied `since` sequence (by default the feed will start from the beginning).
* Fetches the changes from the supplied `since` sequence (in this mode follower defaults to reading the feed from the beginning).
* Fetches all available changes and then stops when either there are no further changes pending or encountering an end condition.
* An example use case for this mode is ETL style workloads.

#### Configuring the changes follower

The SDK's model of changes feed options is also used to configure the follower.
However, a subset of the options are invalid as they are configured internally by the implementation.
However, a subset of the options used internally by the follower implementation are invalid.
Supplying these options when instantiating the follower causes an error.
The invalid options are:
* `descending`
* `feed`
* `heartbeat`
* `lastEventId` - use `since` instead
* `timeout`
* Only the value of `_selector` is permitted for the `filter` option. This restriction is because selector
based filters perform better than JavaScript backed filters. Configuring a non-selector based filter will
cause the follower to error.
* Follower permits only the value `_selector` for the `filter` option. This restriction is because selector
based filters perform better than JavaScript backed filters. Configuring a non-selector based filter
causes the follower to error.

Note that the `limit` parameter will terminate the follower at the given number of changes in either
Note that the `limit` parameter terminates the follower at the given number of changes in either
operating mode.

The changes follower requires the client to have HTTP timeouts of at least 1 minute and will error during
The changes follower requires the client to have HTTP timeouts of at least 1 minute and errors during
instantiation if it is insufficient. The default client configuration has sufficiently long timeouts.

For use-cases where these configuration limitations are deemed too restrictive then it is recommended to
write code to use the SDK's [POST `_changes` API](https://github.com/IBM/cloudant-java-sdk/tree/v0.10.4/examples#postchanges) instead of the follower.
For use-cases where these configuration limitations are too restrictive then write code to use the SDK's
[POST `_changes` API](https://github.com/IBM/cloudant-java-sdk/tree/v0.10.4/examples#postchanges) instead of the follower.

#### Error suppression

By default, the changes follower will suppress transient errors indefinitely and attempt to run to completion or listen forever as
By default, the changes follower suppresses transient errors indefinitely and attempts to run to completion or listen forever as
dictated by the operating mode.
For applications where that is not desirable an optional error tolerance duration may be specified to control the time since
the last successful response that transient errors will be suppressed. This can be used, for example, by applications as a grace period
For applications where that is not desirable configure the optional error tolerance duration. This controls the time since
the last successful response that the follower suppresses transient errors. An example usage is an application grace period
before reporting an error and requiring intervention.

There are some additional points to consider for error suppression:
* Errors considered terminal, for example, the database not existing or invalid credentials are never suppressed and will error immediately.
* The error suppression duration is not guaranteed to fire immediately after lapsing and should be considered a minimum suppression time.
* The changes follower will back-off between retries and as such may remain paused for a short while after the transient errors have resolved.
* If the underlying SDK client used to initialize the follower also has retries configured then errors could be suppressed for significantly
longer than the follower's configured error tolerance duration depending on the configuration options.
* Errors considered terminal, for example, the database not existing or invalid credentials are never suppressed and error immediately.
* The error suppression duration is not guaranteed to fire immediately after lapsing and is a minimum suppression time.
* The changes follower backs-off between retries and as such may remain paused for a short while after the transient errors have resolved.
* If the underlying SDK client used to initialize the follower also has retries configured then suppression of errors may last
significantly longer than the follower's configured error tolerance duration depending on the specific options.

#### Follower operation

Expand All @@ -835,41 +835,41 @@ For both modes:
* A terminal error (HTTP codes `400`, `401`, `403` `404`).
* Transient errors occur for longer than the error tolerance duration. Transient errors are all other HTTP status codes and connection errors.
* The number of changes received reaches the configured `limit`.
* The feed is terminated early by calling stop.
* The application calls stop to terminate the feed early.

As is true for the `_changes` endpoint change items have *at least once* delivery and an individual item
may be received multiple times. When using the follower change items may be repeated even within a limited
number of changes (i.e. using the `limit` option) this is a minor difference from using `limit` on the HTTP native API.
As is true for the `_changes` endpoint change items have *at least once* delivery and callers may receive
an individual item multiple times. When using the follower change items may repeat even within a limited
number of changes (that is using the `limit` option) this is a minor difference from using `limit` on the HTTP native API.

The follower is not optimized for some use cases and it is not recommended to use it in cases where:
* Setting `include_docs` and larger document sizes (for example > 10 kiB).
* The volume of changes is very high (if the rate of changes in the database exceeds the follower's rate of pulling them it will never catch-up).
* The volume of changes is very high (if the rate of changes in the database exceeds the follower's rate of pulling them it can never catch-up).

In these cases use-case specific control over the number of change requests made and the content size of the responses
may be achieved by using the SDK's [POST `_changes` API](https://github.com/IBM/cloudant-java-sdk/tree/v0.10.4/examples#postchanges).
In these use-cases use the SDK's [POST `_changes` API](https://github.com/IBM/cloudant-java-sdk/tree/v0.10.4/examples#postchanges)
for specific control over the number of change requests made and the content size of the responses.

#### Checkpointing
#### Checkpoints

The changes follower does not checkpoint since it has no information about whether a change item has been
processed by the consuming application after being received. It is the application developer's responsibility
The changes follower does not checkpoint since it has no information about whether the consuming application
has processed a change item after delivery. It is the application developer's responsibility
to store the sequence IDs to have appropriate checkpoints and to re-initialize the follower with the required
`since` value after, for example, the application restarts.

The frequency and conditions for checkpointing are application specific and some applications may be tolerant
of dropped changes. This section is intended only to provide general guidance on how to avoid missing changes.
The frequency and conditions for checkpoints are application specific and some applications may be tolerant
of dropped changes. This section provides only general guidance on how to avoid missing changes.

To guarantee processing of all changes the sequence ID from a change item must not be persisted until *after*
the processing of the change item by the application has completed. As indicated previously change items are
delivered *at least once* so application code must be able to handle repeated changes already and it is
To guarantee processing of all changes do not persist the sequence ID from a change item until *after*
the processing of the change item by the application has completed. As indicated previously change item
delivery is *at least once* so application code must be able to handle repeated changes already. It is
preferable to restart from an older `since` value and receive changes again than risk missing them.

The sequence IDs are available on each change item by default, but may be omitted from some change items when
using the `seq_interval` configuration option. Infrequent sequence IDs may improve performance by reducing
the amount of data that needs to be transferred, but the trade-off is that more changes will be repeated if
it is necessary to resume the changes follower.
The sequence IDs are available on each change item by default. However, the server omits sequence IDs from
some change items when using the `seq_interval` configuration option.
Infrequent sequence IDs may improve performance by reducing the amount of data transfer and server load,
but the tradeoff is repeating more changes if it is necessary to resume the changes follower.

Extreme care should be taken with persisting sequences if choosing to process change items in parallel as there
is a considerable risk of missing changes on a restart if the sequence is recorded out of order.
Take extreme care persisting sequences if choosing to process change items in parallel as there
is a considerable risk of missing changes on a restart if the recorded sequence is out of order.

#### Code examples

Expand Down