diff --git "a/\"latest\"" "b/\"latest\"" index ebc5e8b76d..f50752104b 120000 --- "a/\"latest\"" +++ "b/\"latest\"" @@ -1 +1 @@ -4.26.0-RC3 \ No newline at end of file +4.26.0-RC4 \ No newline at end of file diff --git a/4.26.0-RC4/404.html b/4.26.0-RC4/404.html new file mode 100644 index 0000000000..b1ab1af5a6 --- /dev/null +++ b/4.26.0-RC4/404.html @@ -0,0 +1,2454 @@ + + + +
+ + + + + + + + + + + + + + +The AMQP Connector adds support for AMQP 1.0 to Reactive Messaging.
+Advanced Message Queuing Protocol 1.0 (AMQP 1.0) is an open standard for +passing business messages between applications or organizations.
+With this connector, your application can:
+Message
to an AMQP addressThe AMQP connector is based on the Vert.x AMQP Client.
+To use the AMQP Connector, add the following dependency to your project:
+The connector name is: smallrye-amqp
.
So, to indicate that a channel is managed by this connector you need:
+RabbitMQ
+To use RabbitMQ, refer to Using RabbitMQ.
+You can customize the underlying AMQP Client configuration by
+producing an instance of
+AmqpClientOptions
:
This instance is retrieved and used to configure the client used by the
+connector. You need to indicate the name of the client using the
+client-options-name
attribute:
If you experience frequent disconnections from the broker, the AmqpClientOptions can also be used to set a heartbeat if you need to keep the AMQP connection permanently. +Some brokers might terminate the AMQP connection after a certain idle timeout. +You can provide a heartbeat value which will be used by the Vert.x proton client to advertise the idle timeout when opening transport to a remote peer.
+Both incoming and outgoing AMQP channels can be configured with a list +of capabilities to declare during sender and receiver connections with +the AMQP broker. Note that supported capability names are broker +specific.
+ + + + + + + +The AMQP connector reports the startup, liveness, and readiness of each +inbound (Receiving messages) and outbound (sending messages) channel +managed by the connector:
+Startup :: For both inbound and outbound, the startup probe reports OK when the +connection with the broker is established, and the AMQP senders and +receivers are opened (the links are attached to the broker).
+Liveness :: For both inbound and outbound, the liveness check verifies that the +connection is established. The check still returns OK if the +connection got cut, but we are attempting a reconnection.
+Readiness :: For the inbound, it checks that the connection is established and the +receiver is opened. Unlike the liveness check, this probe reports KO +until the connection is re-established. For the outbound, it checks that +the connection is established and the sender is opened. Unlike the +liveness check, this probe reports KO until the connection is +re-established.
+Note
+To disable health reporting, set the health-enabled
attribute for the
+channel to false
.
Note that a message processing failures nacks the message, which is
+then handled by the failure-strategy. It is the responsibility of the
+failure-strategy
to report the failure and influence the outcome of
+the checks. The fail
failure strategy reports the failure, and so the
+check will report the fault.
This connector is for AMQP 1.0. RabbitMQ implements AMQP 0.9.1. RabbitMQ +does not provide AMQP 1.0 by default, but there is a plugin for it. To +use RabbitMQ with this connector, enable and configure the AMQP 1.0 +plugin.
+Despite the plugin, a few features won’t work with RabbitMQ. Thus, we +recommend the following configurations.
+To receive messages from RabbitMQ:
+durable
to false
To send messages to RabbitMQ:
+address
(anonymous sender are not supported)It’s not possible to change the destination dynamically (using message +metadata) when using RabbitMQ. The connector automatically detects that +the broker does not support anonymous sender (See +http://docs.oasis-open.org/amqp/anonterm/v1.0/anonterm-v1.0.html).
+Alternatively, you can use the RabbitMQ connector.
+ + + + + + +The AMQP connector lets you retrieve messages from an AMQP broker or
+router. The AMQP connector
+retrieves AMQP Messages and maps each of them into Reactive Messaging
+Messages
.
Let’s imagine you have an AMQP broker (such as Apache ActiveMQ
+Artemis) running, and
+accessible using the amqp:5672
address (by default it would use
+localhost:5672
). Configure your application to receive AMQP Messages
+on the prices
channel as follows:
Configures the broker/router host name. You can do it per channel
+ (using the host
attribute) or globally using amqp-host
Configures the broker/router port. You can do it per channel (using
+ the port
attribute) or globally using amqp-port
. The default is
+ 5672
.
Configures the broker/router username if required. You can do it per
+ channel (using the username
attribute) or globally using
+ amqp-username
.
Configures the broker/router password if required. You can do it per
+ channel (using the password
attribute) or globally using
+ amqp-password
.
Instructs the prices
channel to be managed by the AMQP connector
Note
+You don’t need to set the AMQP address. By default, it uses the
+channel name (prices
). You can configure the address
attribute to
+override it.
Then, your application receives Message<Double>
. You can consume the
+payload directly:
Or, you can retrieve the Message<Double>
:
The connector converts incoming AMQP Messages into Reactive Messaging
+Message<T>
instances. T
depends on the body of the received AMQP
+Message.
The AMQP Type +System +defines the supported types.
+AMQP Body Type | +<T> |
+
---|---|
AMQP Value containing a AMQP Primitive Type | +the corresponding Java type | +
AMQP Value using the Binary type |
+byte[] |
+
AMQP Sequence | +List |
+
AMQP Data (with binary content) and the content-type is set to application/json |
+JsonObject |
+
AMQP Data with a different content-type |
+byte[] |
+
If you send objects with this AMQP connector (outbound connector), it
+gets encoded as JSON and sent as binary. The content-type
is set to
+application/json
. You can receive this payload using (Vert.x) JSON
+Objects, and then map it to the object class you want:
The Price
instances are automatically encoded to JSON by the
+ connector
You can receive it using a JsonObject
Then, you can reconstruct the instance using the mapTo
method
Messages coming from AMQP contains an instance of IncomingAmqpMetadata
+When a Reactive Messaging Message
associated with an AMQP Message is
+acknowledged, it informs the broker that the message has been
+accepted.
If a message produced from an AMQP message is nacked, a failure +strategy is applied. The AMQP connector supports six strategies:
+fail
- fail the application; no more AMQP messages will be
+ processed (default). The AMQP message is marked as rejected.
accept
- this strategy marks the AMQP message as accepted. The
+ processing continues ignoring the failure. Refer to the accepted
+ delivery state
+ documentation.
release
- this strategy marks the AMQP message as released. The
+ processing continues with the next message. The broker can redeliver
+ the message. Refer to the released delivery state
+ documentation.
reject
- this strategy marks the AMQP message as rejected. The
+ processing continues with the next message. Refer to the rejected
+ delivery state
+ documentation.
modified-failed
- this strategy marks the AMQP message as
+ modified and indicates that it failed (with the delivery-failed
+ attribute). The processing continues with the next message, but the
+ broker may attempt to redeliver the message. Refer to the modified
+ delivery state
+ documentation
modified-failed-undeliverable-here
- this strategy marks the AMQP
+ message as modified and indicates that it failed (with the
+ delivery-failed
attribute). It also indicates that the application
+ cannot process the message, meaning that the broker will not attempt
+ to redeliver the message to this node. The processing continues with
+ the next message. Refer to the modified delivery state
+ documentation
Attribute (alias) | +Description | +Type | +Mandatory | +Default | +
---|---|---|---|---|
address | +The AMQP address. If not set, the channel name is used | +string | +false | ++ |
auto-acknowledgement | +Whether the received AMQP messages must be acknowledged when received | +boolean | +false | +false |
+
broadcast | +Whether the received AMQP messages must be dispatched to multiple subscribers | +boolean | +false | +false |
+
capabilities | +A comma-separated list of capabilities proposed by the sender or receiver client. | +string | +false | ++ |
client-options-name (amqp-client-options-name) | +The name of the AMQP Client Option bean used to customize the AMQP client configuration | +string | +false | ++ |
cloud-events | +Enables (default) or disables the Cloud Event support. If enabled on an incoming channel, the connector analyzes the incoming records and try to create Cloud Event metadata. If enabled on an outgoing, the connector sends the outgoing messages as Cloud Event if the message includes Cloud Event Metadata. | +boolean | +false | +true |
+
connect-timeout (amqp-connect-timeout) | +The connection timeout in milliseconds | +int | +false | +1000 |
+
container-id | +The AMQP container id | +string | +false | ++ |
durable | +Whether AMQP subscription is durable | +boolean | +false | +false |
+
failure-strategy | +Specify the failure strategy to apply when a message produced from an AMQP message is nacked. Accepted values are fail (default), accept , release , reject , modified-failed , modified-failed-undeliverable-here |
+string | +false | +fail |
+
health-timeout | +The max number of seconds to wait to determine if the connection with the broker is still established for the readiness check. After that threshold, the check is considered as failed. | +int | +false | +3 |
+
host (amqp-host) | +The broker hostname | +string | +false | +localhost |
+
link-name | +The name of the link. If not set, the channel name is used. | +string | +false | ++ |
password (amqp-password) | +The password used to authenticate to the broker | +string | +false | ++ |
port (amqp-port) | +The broker port | +int | +false | +5672 |
+
reconnect-attempts (amqp-reconnect-attempts) | +The number of reconnection attempts | +int | +false | +100 |
+
reconnect-interval (amqp-reconnect-interval) | +The interval in second between two reconnection attempts | +int | +false | +10 |
+
selector | +Sets a message selector. This attribute is used to define an apache.org:selector-filter:string filter on the source terminus, using SQL-based syntax to request the server filters which messages are delivered to the receiver (if supported by the server in question). Precise functionality supported and syntax needed can vary depending on the server. |
+string | +false | ++ |
sni-server-name (amqp-sni-server-name) | +If set, explicitly override the hostname to use for the TLS SNI server name | +string | +false | ++ |
tracing-enabled | +Whether tracing is enabled (default) or disabled | +boolean | +false | +true |
+
use-ssl (amqp-use-ssl) | +Whether the AMQP connection uses SSL/TLS | +boolean | +false | +false |
+
username (amqp-username) | +The username used to authenticate to the broker | +string | +false | ++ |
virtual-host (amqp-virtual-host) | +If set, configure the hostname value used for the connection AMQP Open frame and TLS SNI server name (if TLS is in use) | +string | +false | ++ |
You can also pass any property supported by the Vert.x AMQP +client as attribute.
+To use an existing address or queue, you need to configure the
+address
, container-id
and, optionally, the link-name
attributes.
+For example, if you have an Apache Artemis broker configured with:
You need the following configuration:
+You may need to configure the link-name
attribute, if the queue name
+is not the channel name:
The AMQP connector supports Cloud Events.
+When the connector detects a structured or binary Cloud Events, it
+adds a IncomingCloudEventMetadata
+into the metadata of the Message
. IncomingCloudEventMetadata
+contains accessors to the mandatory and optional Cloud Event attributes.
If the connector cannot extract the Cloud Event metadata, it sends the +Message without the metadata.
+For binary
Cloud Events, all mandatory Cloud Event attributes must
+be set in the AMQP application properties, prefixed by cloudEvents:
+(as mandated by the protocol
+binding).
+The connector considers headers starting with the cloudEvents:
prefix
+but not listed in the specification as extensions. You can access them
+using the getExtension
method from IncomingCloudEventMetadata
.
The datacontenttype
attribute is mapped to the content-type
header
+of the record.
For structured
Cloud Events, the event is encoded in the record’s
+value. Only JSON is supported, so your event must be encoded as JSON in
+the record’s value.
Structured Cloud Event must set the content-type
header of the record
+to application/cloudevents+json; charset=UTF-8
. The message body must
+be a valid JSON object containing at least all the mandatory Cloud
+Events attributes.
If the record is a structured Cloud Event, the created Message’s payload
+is the Cloud Event data
.
The AMQP connector can write Reactive Messaging Messages
as AMQP
+Messages.
Let’s imagine you have an AMQP broker (such as Apache ActiveMQ
+Artemis) running, and
+accessible using the amqp:5672
address (by default it would use
+localhost:5672
). Configure your application to send the messages from
+the prices
channel as AMQP Message as follows:
host
attribute) or globally using amqp-host
+Configures the broker/router port. You can do it per channel (using
+ the port
attribute) or globally using amqp-port
. The default is
+ 5672
.
Configures the broker/router username if required. You can do it per
+ channel (using the username
attribute) or globally using
+ amqp-username
.
Configures the broker/router password if required. You can do it per
+ channel (using the password
attribute) or globally using
+ amqp-password
.
Instructs the prices
channel to be managed by the AMQP connector
Note
+You don’t need to set the address. By default, it uses the channel
+name (prices
). You can configure the address
attribute to override
+it.
Then, your application must send Message<Double>
to the prices
+channel. It can use double
payloads as in the following snippet:
Or, you can send Message<Double>
:
When receiving a Message<T>
, the connector convert the message into an
+AMQP Message. The payload is converted to the AMQP Message body.
T |
+AMQP Message Body | +
---|---|
primitive types or String |
+AMQP Value with the payload | +
Instant or UUID |
+AMQP Value using the corresponding AMQP Type | +
JsonObject or JsonArray |
+AMQP Data using a binary content. The content-type is set to application/json |
+
io.vertx.mutiny.core.buffer.Buffer |
+AMQP Data using a binary content. No content-type set |
+
Any other class | +The payload is converted to JSON (using a Json Mapper). The result is wrapped into AMQP Data using a binary content. The content-type is set to application/json |
+
If the message payload cannot be serialized to JSON, the message is +nacked.
+When sending Messages
, you can add an instance of
+OutgoingAmqpMetadata
+to influence how the message is going to be sent to AMQP. For example, you
+can configure the subjects, properties:
Sometimes it is desirable to select the destination of a message +dynamically. In this case, you should not configure the address inside +your application configuration file, but instead, use the outbound +metadata to set the address.
+For example, you can send to a dynamic address based on the incoming +message:
+Note
+To be able to set the address per message, the connector is using an +anonymous sender.
+By default, the Reactive Messaging Message
is acknowledged when the
+broker acknowledged the message. When using routers, this
+acknowledgement may not be enabled. In this case, configure the
+auto-acknowledgement
attribute to acknowledge the message as soon as
+it has been sent to the router.
If an AMQP message is rejected/released/modified by the broker (or +cannot be sent successfully), the message is nacked.
+The back-pressure is handled by the max-inflight-messages
attribute and AMQP credits.
+The outbound connector requests messages minimum between max-inflight-messages
and credits allowed by the broker.
+When the amount of credits reaches 0, it waits (in a non-blocking fashion) until the broker grants more credits to the AMQP sender.
When max-inflight-messages
is set to 0, only AMQP credits apply to limit the requests.
Note that if an AMQP message send fails, it is retried until reconnect-attempts
is reached.
+If the client reconnects to the broker during the retry, failing messages are sent again but the message order is not preserved.
To preserve the message order in this case you can set max-inflight-messages
to
Attribute (alias) | +Description | +Type | +Mandatory | +Default | +
---|---|---|---|---|
address | +The AMQP address. If not set, the channel name is used | +string | +false | ++ |
capabilities | +A comma-separated list of capabilities proposed by the sender or receiver client. | +string | +false | ++ |
client-options-name (amqp-client-options-name) | +The name of the AMQP Client Option bean used to customize the AMQP client configuration | +string | +false | ++ |
cloud-events | +Enables (default) or disables the Cloud Event support. If enabled on an incoming channel, the connector analyzes the incoming records and try to create Cloud Event metadata. If enabled on an outgoing, the connector sends the outgoing messages as Cloud Event if the message includes Cloud Event Metadata. | +boolean | +false | +true |
+
cloud-events-data-content-type (cloud-events-default-data-content-type) | +Configure the default datacontenttype attribute of the outgoing Cloud Event. Requires cloud-events to be set to true . This value is used if the message does not configure the datacontenttype attribute itself |
+string | +false | ++ |
cloud-events-data-schema (cloud-events-default-data-schema) | +Configure the default dataschema attribute of the outgoing Cloud Event. Requires cloud-events to be set to true . This value is used if the message does not configure the dataschema attribute itself |
+string | +false | ++ |
cloud-events-insert-timestamp (cloud-events-default-timestamp) | +Whether or not the connector should insert automatically the time attribute into the outgoing Cloud Event. Requires cloud-events to be set to true . This value is used if the message does not configure the time attribute itself |
+boolean | +false | +true |
+
cloud-events-mode | +The Cloud Event mode (structured or binary (default)). Indicates how are written the cloud events in the outgoing record |
+string | +false | +binary |
+
cloud-events-source (cloud-events-default-source) | +Configure the default source attribute of the outgoing Cloud Event. Requires cloud-events to be set to true . This value is used if the message does not configure the source attribute itself |
+string | +false | ++ |
cloud-events-subject (cloud-events-default-subject) | +Configure the default subject attribute of the outgoing Cloud Event. Requires cloud-events to be set to true . This value is used if the message does not configure the subject attribute itself |
+string | +false | ++ |
cloud-events-type (cloud-events-default-type) | +Configure the default type attribute of the outgoing Cloud Event. Requires cloud-events to be set to true . This value is used if the message does not configure the type attribute itself |
+string | +false | ++ |
connect-timeout (amqp-connect-timeout) | +The connection timeout in milliseconds | +int | +false | +1000 |
+
container-id | +The AMQP container id | +string | +false | ++ |
credit-retrieval-period | +The period (in milliseconds) between two attempts to retrieve the credits granted by the broker. This time is used when the sender run out of credits. | +int | +false | +2000 |
+
durable | +Whether sent AMQP messages are marked durable | +boolean | +false | +false |
+
health-timeout | +The max number of seconds to wait to determine if the connection with the broker is still established for the readiness check. After that threshold, the check is considered as failed. | +int | +false | +3 |
+
host (amqp-host) | +The broker hostname | +string | +false | +localhost |
+
link-name | +The name of the link. If not set, the channel name is used. | +string | +false | ++ |
max-inflight-messages | +The maximum number of messages to be written to the broker concurrently. The number of sent messages waiting to be acknowledged by the broker are limited by this value and credits granted by the broker. The default value 0 means only credits apply. |
+long | +false | +0 |
+
merge | +Whether the connector should allow multiple upstreams | +boolean | +false | +false |
+
password (amqp-password) | +The password used to authenticate to the broker | +string | +false | ++ |
port (amqp-port) | +The broker port | +int | +false | +5672 |
+
reconnect-attempts (amqp-reconnect-attempts) | +The number of reconnection attempts | +int | +false | +100 |
+
reconnect-interval (amqp-reconnect-interval) | +The interval in second between two reconnection attempts | +int | +false | +10 |
+
sni-server-name (amqp-sni-server-name) | +If set, explicitly override the hostname to use for the TLS SNI server name | +string | +false | ++ |
tracing-enabled | +Whether tracing is enabled (default) or disabled | +boolean | +false | +true |
+
ttl | +The time-to-live of the send AMQP messages. 0 to disable the TTL | +long | +false | +0 |
+
use-anonymous-sender | +Whether or not the connector should use an anonymous sender. Default value is true if the broker supports it, false otherwise. If not supported, it is not possible to dynamically change the destination address. |
+boolean | +false | ++ |
use-ssl (amqp-use-ssl) | +Whether the AMQP connection uses SSL/TLS | +boolean | +false | +false |
+
username (amqp-username) | +The username used to authenticate to the broker | +string | +false | ++ |
virtual-host (amqp-virtual-host) | +If set, configure the hostname value used for the connection AMQP Open frame and TLS SNI server name (if TLS is in use) | +string | +false | ++ |
You can also pass any property supported by the Vert.x AMQP +client as attribute.
+To use an existing address or queue, you need to configure the
+address
, container-id
and, optionally, the link-name
attributes.
+For example, if you have an Apache Artemis broker configured with:
You need the following configuration:
+You may need to configure the link-name
attribute, if the queue name
+is not the channel name:
To use a MULTICAST
queue, you need to provide the FQQN
+(Fully-qualified queue name) instead of just the name of the queue:
More details about the AMQP Address model can be found on the Artemis +documentation.
+The AMQP connector supports Cloud Events. The +connector sends the outbound record as Cloud Events if:
+the message metadata contains an
+ io.smallrye.reactive.messaging.ce.OutgoingCloudEventMetadata
+ instance,
the channel configuration defines the cloud-events-type
and
+ cloud-events-source
attributes.
You can create
+io.smallrye.reactive.messaging.ce.OutgoingCloudEventMetadata
instances
+using:
If the metadata does not contain an id, the connector generates one
+(random UUID). The type
and source
can be configured per message or
+at the channel level using the cloud-events-type
and
+cloud-events-source
attributes. Other attributes are also
+configurable.
The metadata can be contributed by multiple methods, however, you must +always retrieve the already existing metadata to avoid overriding the +values:
+By default, the connector sends the Cloud Events using the binary
+format. You can write structured Cloud Events by setting the
+cloud-events-mode
to structured
. Only JSON is supported, so the
+created records had its content-type
header set to
+application/cloudevents+json; charset=UTF-8
Note
+you can disable the Cloud Event support by setting the cloud-events
+attribute to false
{"use strict";/*!
+ * escape-html
+ * Copyright(c) 2012-2013 TJ Holowaychuk
+ * Copyright(c) 2015 Andreas Lubbe
+ * Copyright(c) 2015 Tiancheng "Timothy" Gu
+ * MIT Licensed
+ */var Ha=/["'&<>]/;Un.exports=$a;function $a(e){var t=""+e,r=Ha.exec(t);if(!r)return t;var o,n="",i=0,s=0;for(i=r.index;i