Skip to content
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

[DATAGO-83177] Adding docs and release note for Nack feature #15

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[DATAGO-83177] Adding docs and release note for Nack feature #15

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e94f55c
[DATAGO-83177] Adding docs and release note for Nack feature
sunil-solace Nov 14, 2024
c59ae02
Adding review comment for RecoverSession deprecation
sunil-solace Nov 15, 2024
0035dac
Incorporating review comments
sunil-solace Nov 18, 2024
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
9 changes: 5 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Solace PubSub+ Connector - Mule 4, Documentation and Examples

v1.5.x
v1.6.x

## About the Connector

Expand All @@ -17,7 +17,8 @@ Use the PubSub+ Connector to leverage PubSub+ Event Broker (event streaming) and
* Request-reply (synchronous wait for reply in flow)
* Publish to topic or queue (direct or persistent)
* Ack to acknowledge messages anywhere in the Flow
* Recover Session will redeliver all already consumed but unacknowledged messages
* Nack to negatively acknowledge messages with Failed or Rejected settlement anywhere in the Flow
* Recover Session will redeliver all already consumed but unacknowledged messages (deprecated; use the Nack operation instead)
sunil-solace marked this conversation as resolved.
Show resolved Hide resolved
* Guaranteed Endpoint Polling Listener (polling based GM consumer)

* PubSub+ Event Portal integration
Expand Down Expand Up @@ -55,7 +56,7 @@ MuleSoft disclaims any support obligation for MuleSoft Certified Connectors. By
<dependency>
<groupId>com.solace.connector</groupId>
<artifactId>solace-mulesoft-connector</artifactId>
<version>1.5.0</version>
<version>1.6.0</version>
<classifier>mule-plugin</classifier>
</dependency>
```
Expand All @@ -75,7 +76,7 @@ Connector
Published by: MuleSoft Partner
</br>

Published on: March, 2024
Published on: Nov, 2024
</br>

Level: MuleSoft-Certified
Expand Down
Binary file added doc/images/Nack-Example.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 28 additions & 2 deletions doc/release-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,34 @@

Use the PubSub+ Connector to leverage PubSub+ Event Broker (event streaming) and PubSub+ Event Portal (event management) within MuleSoft Anypoint Platform, to make your MuleSoft integrations more reliable, agile, and event-driven.

## v1.6.0
**Nov 30, 2024**
### Compatibility

| Application/Service | Version |
|----------------------|-----------------|
| Mule Runtime | 4.3 and higher |
| Studio Version | 7.9 and higher |
| PubSub+ Event Broker | 9.1 and higher |
| Java | 1.8 and later |

### New Features
1. Negative Acknowledgement (NACK) Support <br/>
• Introduced for Guaranteed Endpoint Listener and Guaranteed Endpoint Polling Listener Sources<br/>
• Uses the FAILED settlement outcome<br/>
2. New Nack Operation <br/>
• Allows negative acknowledgement of guaranteed messages <br/>
• Supports both FAILED and REJECTED settlement outcomes <br/>
• Recommended alternative to Recover Session Operation settlement outcomes <br/>
3. Added support for DeliveryCount and ReplicationGroupMessageId as Solace Message Properties <br/>

**Note:** The version of the Solace PS+ broker that supports NACK using FAILED & REJECTED settlement outcome is version 10.2.1 and later. However, it maintains compatibility with brokers that do not support these settlement capabilities. This capability is automatically processed internally to the connector and requires no user interaction or configuration.

### Deprecation Notice
The Recover Session Operation feature will soon be deprecated. Users are advised to transition to the new Nack Operation for improved message handling and error management.

## v1.5.0
**May 31, 2023**
**May 31, 2024**
### Compatibility

| Application/Service | Version |
Expand Down Expand Up @@ -211,7 +237,7 @@ Add this dependency to your application pom.xml
<dependency>
<groupId>com.solace.connector</groupId>
<artifactId>solace-mulesoft-connector</artifactId>
<version>1.4.0</version>
<version>1.6.0</version>
<classifier>mule-plugin</classifier>
</dependency>
```
Expand Down
278 changes: 250 additions & 28 deletions doc/technical-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
* [Config](#config)
* [Operations](#operations)
* [Ack](#Ack)
* [Nack](#Nack)
* [Consume](#Consume)
* [Publish](#Publish)
* [Request Reply](#request-reply)
Expand Down Expand Up @@ -921,6 +922,222 @@ A retry strategy in case of connectivity errors

<div class="sect2">

### Nack

<div class="paragraph">

`<solace:nack>`

</div>

<div class="paragraph">

Operation that allows the user to negatively acknowledge processing of a guaranteed message so it can be retried/removed from the PubSub+ event broker. It applies only when Ack Mode is selected to MANUAL_CLIENT.

</div>

<div class="sect3">

#### Parameters

<table class="tableblock frame-all grid-all spread"><colgroup><col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 35%;"> <col style="width: 20%;"> <col style="width: 5%;"></colgroup>

<thead>

<tr>

<th class="tableblock halign-left valign-middle">Name</th>

<th class="tableblock halign-left valign-middle">Type</th>

<th class="tableblock halign-left valign-middle">Description</th>

<th class="tableblock halign-left valign-middle">Default Value</th>

<th class="tableblock halign-center valign-middle">Required</th>

</tr>

</thead>

<tbody>

<tr>

<td class="tableblock halign-left valign-middle">

Configuration

</td>

<td class="tableblock halign-left valign-middle">

String

</td>

<td class="tableblock halign-left valign-middle">

The name of the connector configuration to use.

</td>

<td class="tableblock halign-left valign-middle"></td>

<td class="tableblock halign-center valign-middle">

**x**

</td>

</tr>

<tr>

<td class="tableblock halign-left valign-middle">

Message Reference Id

</td>

<td class="tableblock halign-left valign-middle">

<div>

<div class="paragraph">

String

</div>

</div>

</td>

<td class="tableblock halign-left valign-middle">

The "Reference Id" property from the Solace Message Properties of the message to be negatively acknowledged

</td>

<td class="tableblock halign-left valign-middle">

#[attributes.messageReferenceId]

</td>

<td class="tableblock halign-center valign-middle"></td>

</tr>

<tr>

<td class="tableblock halign-left valign-middle">

Settlement Outcome

</td>

<td class="tableblock halign-left valign-middle">

Enumeration, one of:
* FAILED
* REJECTED

</td>

<td class="tableblock halign-left valign-middle">

FAILED:

This negative acknowledgment notifies the event broker that the message was not processed successfully. The event broker will attempt to redeliver the message while adhering to delivery count limits.

REJECTED:

This negative acknowledgment notifies the event broker that the message was not accepted. The event broker will remove the message from its queue and then move the message to the Dead Message Queue (DMQ) if it is configured.

</td>

<td class="tableblock halign-left valign-middle">FAILED</td>

<td class="tableblock halign-center valign-middle">

</td>

</tr>

<tr>

<td class="tableblock halign-left valign-middle">

Reconnection Strategy

</td>

<td class="tableblock halign-left valign-middle">

<div>

<div class="ulist">

* [Reconnect](#reconnect)

* [Reconnect Forever](#reconnect-forever)

</div>

</div>

</td>

<td class="tableblock halign-left valign-middle">

A retry strategy in case of connectivity errors

</td>

<td class="tableblock halign-left valign-middle"></td>

<td class="tableblock halign-center valign-middle"></td>

</tr>

</tbody>

</table>

</div>

<div class="sect3">

#### For Configurations.

<div class="ulist">

* [Config](#config)

</div>

</div>

<div class="sect3">

#### Throws

<div class="ulist">

* SOLACE:GENERIC_ERROR

* SOLACE:INVALID_CONFIGURATION

</div>

</div>

</div>

<div class="sect2">

### Consume

<div class="paragraph">
Expand Down Expand Up @@ -3191,6 +3408,8 @@ Any

<div class="paragraph">

**Deprecation Notice:** This Operation will soon be deprecated. Users are advised to transition to the new Nack Operation for improved message handling and error management.

Operation that allows the user to perform a session recover when consuming an unacknowledged message. It applies only when Ack Mode is selected to MANUAL_CLIENT.

More about the usage and scope can found [here](user-guide.md#recover-session-operation).
Expand Down Expand Up @@ -6369,34 +6588,37 @@ A time unit that qualifies the maxIdleTime attribute

### Solace Message Properties

| Field | Type | Description |
|---|---|---|
| DMQ Eligible | Boolean | |
| Application Message Id | String | An application-specific message identifier |
| Application Message Type | String | An application-specific message type |
| Content Type | String | The HTTP content type header value if the Solace message originated from interaction with an HTTP client or null if it is not set |
| Correlation Id | String | Correlation ID for Request-Reply messaging, used for correlating a request to a reply |
| Cos | Number | The Class of Service (CoS) value for this message |
| Delivery Mode | String | Represents the message delivery mode. Each type is associated with a set of delivery characteristics and guarantees. The valid modes are: NON_PERSISTENT, PERSISTENT and DIRECT |
| Destination | String | The destination this message was published to |
| Discard Indication | Boolean | True if one or more messages have been discarded prior to the current message, else False |
| Eliding Eligible | Boolean | Whether the message is eligible for eliding |
| Endpoint Type | String | The type of the destination: TOPIC or QUEUE |
| Expiration | Number | The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is supposed to expire |
| Message Id | String | The Solace message ID |
| Message Reference Id | String | A generated Message Reference ID, to be used for Acknowledgement |
| Priority | Number | The priority value in the range of 0–255, or -1 if it is not set |
| Receiver Timestamp | Number | The receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC) |
| Redelivered | Boolean | Indicates if the message has been delivered by the PubSub+ broker to the API before |
| Reply | Boolean | Whether the message's reply field is set, indicating that this message is a reply |
| Reply To | String | The reply-to destination |
| Reply To Endpoint Type | String | The type of the reply-to endpoint: TOPIC or QUEUE |
| Sender ID | String | The Sender's ID |
| Sender Timestamp | Number | The send timestamp (in milliseconds, from midnight, January 1, 1970 UTC) |
| Sequence Number | Number | The Solace message sequence number |
| Time To Live | Number | The number of milliseconds before the message is discarded or moved to Dead Message Queue |
| User Data | Binary | When an application sends a message, it can optionally attach application-specific data along with the message, such as user data |
| User Properties | Object | The user properties map |
| Field | Type | Description |
|------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| DMQ Eligible | Boolean | |
| Application Message Id | String | An application-specific message identifier |
| Application Message Type | String | An application-specific message type |
| Content Type | String | The HTTP content type header value if the Solace message originated from interaction with an HTTP client or null if it is not set |
| Correlation Id | String | Correlation ID for Request-Reply messaging, used for correlating a request to a reply |
| Cos | Number | The Class of Service (CoS) value for this message |
| Delivery Mode | String | Represents the message delivery mode. Each type is associated with a set of delivery characteristics and guarantees. The valid modes are: NON_PERSISTENT, PERSISTENT and DIRECT |
| Destination | String | The destination this message was published to |
| Discard Indication | Boolean | True if one or more messages have been discarded prior to the current message, else False |
| Eliding Eligible | Boolean | Whether the message is eligible for eliding |
| Endpoint Type | String | The type of the destination: TOPIC or QUEUE |
| Expiration | Number | The UTC time (in milliseconds, from midnight, January 1, 1970 UTC) when the message is supposed to expire |
| Message Id | String | The Solace message ID |
| Message Reference Id | String | A generated Message Reference ID, to be used for Acknowledgement |
| Priority | Number | The priority value in the range of 0–255, or -1 if it is not set |
| Receiver Timestamp | Number | The receive timestamp (in milliseconds, from midnight, January 1, 1970 UTC) |
| Redelivered | Boolean | Indicates if the message has been delivered by the PubSub+ broker to the API before |
| Reply | Boolean | Whether the message's reply field is set, indicating that this message is a reply |
| Reply To | String | The reply-to destination |
| Reply To Endpoint Type | String | The type of the reply-to endpoint: TOPIC or QUEUE |
| Sender ID | String | The Sender's ID |
| Sender Timestamp | Number | The send timestamp (in milliseconds, from midnight, January 1, 1970 UTC) |
| Sequence Number | Number | The Solace message sequence number |
| Time To Live | Number | The number of milliseconds before the message is discarded or moved to Dead Message Queue |
| User Data | Binary | When an application sends a message, it can optionally attach application-specific data along with the message, such as user data |
| User Properties | Object | The user properties map |
| Delivery Count | Number | A read-only property that indicates how many times the broker has attempted to deliver a message to a consumer. <br/>**Note:** It must be explicitly enabled for queues and topic endpoints on the broker side before client applications can use it |
| Replication Group Message Id | String | It is a unique identifier assigned by Solace PubSub+ event brokers to messages on queues or topic endpoints within a high availability (HA) group and replication group. |


</br>

Expand Down
Loading