You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by mm...@apache.org on 2018/02/02 20:03:15 UTC
[incubator-pulsar] branch master updated: Reader interface docs
update (#1120)
This is an automated email from the ASF dual-hosted git repository.
mmerli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new ddd4de3 Reader interface docs update (#1120)
ddd4de3 is described below
commit ddd4de39446cd9d214e1112cc88e23b3ee706231
Author: Luc Perkins <lu...@gmail.com>
AuthorDate: Fri Feb 2 12:03:12 2018 -0800
Reader interface docs update (#1120)
* add basic description in concepts/architecture doc
* begin adding section to java API doc
* finish draft of java API section
* finish draft of concepts/architecture section
* add python example
* add reader interface diagram and fix incomplete sentence
* use local PNG rather than lucidchart URL
---
site/docs/latest/clients/Java.md | 4 +---
.../latest/getting-started/ConceptsAndArchitecture.md | 8 +++++---
site/img/pulsar-reader-consumer-interfaces.png | Bin 0 -> 131839 bytes
3 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/site/docs/latest/clients/Java.md b/site/docs/latest/clients/Java.md
index f0fd9b0..5eaaa9d 100644
--- a/site/docs/latest/clients/Java.md
+++ b/site/docs/latest/clients/Java.md
@@ -217,9 +217,7 @@ Async receive operations return a {% javadoc Message client org.apache.pulsar.cl
## Reader interface
-The Pulsar [Reader API](../../getting-started/ConceptsAndArchitecture#reader-interface) enables applications to access messages on Pulsar {% popover topics %}
-
-With the Reader API, Pulsar clients can "manually position" themselves within a topic, reading all messages from a specified message onward. The Pulsar API for Java enables you to create {% javadoc Reader client org.apache.pulsar.client.api.Reader %} objects by specifying a {% popover topic %}, a {% javadoc MessageId client org.apache.pulsar.client.api.MessageId %}, and {% javadoc ReaderConfiguration client org.apache.pulsar.client.api.ReaderConfiguration %}.
+With the [reader interface](../../getting-started/ConceptsAndArchitecture#reader-interface), Pulsar clients can "manually position" themselves within a topic, reading all messages from a specified message onward. The Pulsar API for Java enables you to create {% javadoc Reader client org.apache.pulsar.client.api.Reader %} objects by specifying a {% popover topic %}, a {% javadoc MessageId client org.apache.pulsar.client.api.MessageId %}, and {% javadoc ReaderConfiguration client org.apac [...]
Here's an example:
diff --git a/site/docs/latest/getting-started/ConceptsAndArchitecture.md b/site/docs/latest/getting-started/ConceptsAndArchitecture.md
index f69fd78..54b0dfb 100644
--- a/site/docs/latest/getting-started/ConceptsAndArchitecture.md
+++ b/site/docs/latest/getting-started/ConceptsAndArchitecture.md
@@ -340,9 +340,9 @@ You can use your own service discovery system if you'd like. If you use your own
## Reader interface
-In Pulsar, the "standard" [consumer interface](#consumers) involves using {% popover consumers %} to listen on {% popover topics %}, process incoming messages, and finally {% popover acknowledge %} those messages when they've been processed. Whenever a consumer disconnects from and then reconnects to a topic, it automatically begins reading from the earliest un-acked message onward because the topic's cursor is automatically managed by Pulsar.
+In Pulsar, the "standard" [consumer interface](#consumers) involves using {% popover consumers %} to listen on {% popover topics %}, process incoming messages, and finally {% popover acknowledge %} those messages when they've been processed. Whenever a consumer connects to a topic, it automatically begins reading from the earliest un-acked message onward because the topic's cursor is automatically managed by Pulsar.
-The **reader interface** for Pulsar enables applications to manually manage cursors. When you use a reader to connect to a topic---rather than a consumer---you need to specify *which* message the reader begins reading from. When specifying that initial message, the reader interface gives you three options:
+The **reader interface** for Pulsar enables applications to manually manage cursors. When you use a reader to connect to a topic---rather than a consumer---you need to specify *which* message the reader begins reading from when it connects to a topic. When connecting to a topic, the reader interface enables you to begin with:
* The **earliest** available message in the topic
* The **latest** available message in the topic
@@ -350,6 +350,8 @@ The **reader interface** for Pulsar enables applications to manually manage curs
The reader interface is helpful for use cases like using Pulsar to provide [effectively-once](https://streaml.io/blog/exactly-once/) processing semantics for a stream processing system. For this use case, it's essential that the stream processing system be able to "rewind" topics to a specific message and begin reading there. The reader interface provides Pulsar clients with the low-level abstraction necessary to "manually position" themselves within a topic.
+<img src="/img/pulsar-reader-consumer-interfaces.png" alt="The Pulsar consumer and reader interfaces" width="80%">
+
{% include admonition.html type="warning" title="Non-partitioned topics only"
content="The reader interface for Pulsar cannot currently be used with [partitioned topics](#partitioned-topics)." %}
@@ -386,4 +388,4 @@ To create a reader that will read from some message between earliest and latest:
byte[] msgIdBytes = // Some byte array
MessageId id = MessageId.fromByteArray(msgIdBytes);
Reader reader = pulsarClient.createReader(topic, id, new ReaderConfiguration());
-```
\ No newline at end of file
+```
diff --git a/site/img/pulsar-reader-consumer-interfaces.png b/site/img/pulsar-reader-consumer-interfaces.png
new file mode 100644
index 0000000..26f05d3
Binary files /dev/null and b/site/img/pulsar-reader-consumer-interfaces.png differ
--
To stop receiving notification emails like this one, please contact
mmerli@apache.org.