Skip to content

Commit a1c990d

Browse files
scottfscottf
committed
Improved Examples and documentation
1 parent 67077fe commit a1c990d

12 files changed

Lines changed: 396 additions & 250 deletions

‎js-publish-extensions/README.md‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
Extensions specific to JetStream publishing.
66

7-
**Current Release**: 0.3.0
8-
  **Current Snapshot**: 0.4.0-SNAPSHOT
7+
**Current Release**: 0.4.0
8+
  **Current Snapshot**: 0.4.1-SNAPSHOT
99
  **Gradle and Maven** `io.synadia:jnats-js-publish-extensions`
1010
[Dependencies Help](https://github.com/synadia-io/orbit.java?tab=readme-ov-file#dependencies)
1111

@@ -17,32 +17,38 @@ Extensions specific to JetStream publishing.
1717
### PublishRetrier
1818

1919
This class parallels the standard JetStream publish api with methods that will retry the publish.
20-
2120
The examples:
22-
* [Publish Retrier Sync Example](src/examples/java/io/synadia/examples/PublishRetrierSyncExample.java)
23-
* [Publish Retrier Async Example](src/examples/java/io/synadia/examples/PublishRetrierAsyncExample.java)
21+
* The [Publish Retrier Sync Example](src/examples/java/io/synadia/examples/PublishRetrierSyncExample.java)
22+
demonstrates publishing synchronously with the retrier.
23+
24+
* The [Publish Retrier Async Example](src/examples/java/io/synadia/examples/PublishRetrierAsyncExample.java)
25+
demonstrates publishing asynchronously with the retrier.
2426

2527
### AsyncJsPublisher
2628

27-
This class is a full async message publish manager.
28-
This utility provides a workflow of
29+
This class is a full async message publish manager that provides:
2930
1. Publishing a message async
3031
* The number of inflight messages (published but not received acks) can be set.
31-
2. Queueing and tracking of the in-flight PublishAck future
32+
2. Queueing and tracking of the inflight PublishAck future
3233
3. The ability to observe the queue and respond to events
3334
* The message was published
3435
* The message received a valid ack
3536
* The publish completed with an exception
3637
* The publish timed out.
38+
* Publishing was paused or resumed due to threshold settings
3739

3840
It can be combined with the retrier.
3941
You must consider that when publishing async in this manner
4042
it's possible for messages to be published out of order.
4143
In that case you can use publish expectations.
4244
If order of messages is a requirement, you
4345

44-
* [Async Js Publisher Example](src/examples/java/io/synadia/examples/AsyncJsPublisherExample.java)
45-
* [Async Js Publisher More Customized Example](src/examples/java/io/synadia/examples/AsyncJsPublisherCustomizedExample.java)
46+
* The [Async Js Publisher Example](src/examples/java/io/synadia/examples/AsyncJsPublisherExample.java)
47+
demonstrates basic use of the class.
48+
49+
* The [Async Js Publisher Custom Threads Example](src/examples/java/io/synadia/examples/AsyncJsPublisherCustomThreadsExample.java)
50+
has the identical workflow, but demonstrates the ability to provide the executors and threads manually instead of relying
51+
on the built-in ones.
4652

4753
---
4854
Copyright (c) 2024-2025 Synadia Communications Inc. All Rights Reserved.

‎js-publish-extensions/build.gradle‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ plugins {
1313
id 'signing'
1414
}
1515

16-
def jarVersion = "0.4.0"
16+
def jarVersion = "0.4.1"
1717
group = 'io.synadia'
1818

1919
def isMerge = System.getenv("BUILD_EVENT") == "push"

‎js-publish-extensions/docs/DraftDesign.md‎

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,39 @@ This document is the draft design describing a managed async publish utility.
77
* JetStream context on which to publish
88

99
#### Optional Properties
10-
| Property | Description |
11-
|---------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
12-
| String idPrefix | used to make unique identifiers around each message. Defaults to a NUID |
13-
| int maxInFlight | no more than this number of messages can be waiting for publish ack. Defaults to 50. |
14-
| int refillAllowedAt | if the queue size reaches maxInFlight, a hold is placed so no more messages can be published until the in flight queue contains this amount or less messages, at which time the hold is removed. Defaults to 0 which would be full sawtooth. Non zero provides for a window. |
15-
| RetryConfig retryConfig | if the user wants to publish with retries, they must supply a config, otherwise the publish will be attempted only once. |
16-
| long pollTime | the amount of time in ms to poll any given queue. Ensures polling doesn't block indefinitely. Defaults to 100ms |
17-
| long holdPauseTime | the amount of time in ms to pause between checks when hold is on. Defaults to 100ms |
18-
| long waitTimeout | the timeout when waiting for a publish to be acknowledged. Defaults to 5000ms |
19-
| PublisherListener publisherListener | a callback for the user to see what's going on in the workflow, see description of Flight later |
10+
| Property | Description |
11+
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
12+
| String idPrefix | used to make unique identifiers around each message. Defaults to a NUID |
13+
| int maxInFlight | no more than this number of messages can be waiting for publish ack. Defaults to 50. |
14+
| int refillAllowedAt | if the queue size reaches maxInFlight, a hold is placed so no more messages can be published until the in flight queue contains this amount or less messages, at which time the hold is removed. Defaults to 0 which would be full sawtooth. Non zero provides for a window. |
15+
| RetryConfig retryConfig | if the user wants to publish with retries, they must supply a config, otherwise the publish will be attempted only once. |
16+
| long pollTime | the amount of time in ms to poll any given queue. Ensures polling doesn't block indefinitely. Defaults to 100ms |
17+
| long publishPauseTime | the amount of time in ms to pause between checks when hold is on. Defaults to 100ms |
18+
| long waitTimeout | the timeout when waiting for a publish to be acknowledged. Defaults to 5000ms |
19+
| PublisherListener publisherListener | a callback for the user to see what's going on in the workflow, see description of Flight later |
2020

2121

2222
## PublisherListener Interface
2323

2424
The callback interface for the user to get information about the publish workflow
2525

26-
| Method | Description |
27-
|---------------------------------------------|-----------------------------------------------------------------------|
28-
| void published(Flight flight) | the flight is ready when the message is published |
29-
| void acked(Flight flight); | the publish ack was received |
30-
| void completedExceptionally(Flight flight); | the publish exceptioned, such as a 503 or lower level request timeout |
31-
| void timeout(Flight flight) | the ack was not returned in time based on waitTimeout |
26+
| Method | Description |
27+
|-----------------------------------------------------------------------|-----------------------------------------------------------------------|
28+
| void published(Flight flight) | the flight is ready when the message is published |
29+
| void acked(Flight flight) | the publish ack was received |
30+
| void completedExceptionally(Flight flight) | the publish exceptioned, such as a 503 or lower level request timeout |
31+
| void timeout(Flight flight) | the ack was not returned in time based on waitTimeout |
32+
| void paused(int currentInFlight, int maxInFlight, int resumeAmount) | Publishing was paused due to in-flight conditions |
33+
| void resumed(int currentInFlight, int maxInFlight, int resumeAmount) | Publishing was resumed due to in-flight conditions |
34+
35+
/**
36+
* The engine has just resumed publishing and will continue unless
37+
* the number of messages in flight reaches the max
38+
* @param currentInFlight the number of messages in flight
39+
* @param maxInFlight the number of in flight messages when publishing will be paused
40+
* @param resumeAmount the number of in flight messages when publishing will resume after being paused
41+
*/
42+
void resumed(int currentInFlight, int maxInFlight, int resumeAmount);
3243

3344
## Flight structure
3445

@@ -68,7 +79,7 @@ while keepGoing flag
6879
if in flight queue has reached maxInFlight put hold on
6980
notify listener to indicate published
7081
else in holding pattern
71-
sleep holdPauseTime
82+
sleep publishPauseTime
7283
```
7384

7485
## Flights Runner Pseudo Code:

0 commit comments

Comments
 (0)