# Vert.x AMQP Bridge

This component provides AMQP 1.0 producer and consumer support via a bridging layer implementing the Vert.x event bus MessageProducer and MessageConsumer APIs over the top of vertx-proton.

Warning | this module has the tech preview status, this means the API can change between versions.

## Using Vert.x AMQP Bridge

To use Vert.x AMQP Bridge, add the following dependency to the dependencies section of your build descriptor:

- Maven (in your `pom.xml`):

    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-amqp-bridge</artifactId>
      <version>3.3.0</version>
    </dependency>

- Gradle (in your `build.gradle` file):

    compile io.vertx:vertx-amqp-bridge:3.3.0

### Sending a Message

Here is a simple example of creating a `MessageProducer` and sending a message with it. First, an `AmqpBridge` is created and started to establish the underlying AMQP connection, then when this is complete the producer is created and a message sent using it. You can also optionally supply `AmqpBridgeOptions` when creating the bridge in order to configure various options, such as SSL connections.

    var AmqpBridge = require("vertx-amqp-bridge-js/amqp_bridge");
    var bridge = AmqpBridge.create(vertx);
    // Start the bridge, then use the event loop thread to process things thereafter.
    bridge.start("localhost", 5672, function (res, res_err) {
      // Set up a producer using the bridge, send a message with it.
      var producer = bridge.createProducer("myAmqpAddress");

      var amqpMsgPayload = {
      };
      amqpMsgPayload.body = "myStringContent";

      producer.send(amqpMsgPayload);
    });

### Receiving a Message

Here is a simple example of creating a `MessageConsumer` and registering a handler with it. First, an `AmqpBridge` is created and started to establish the underlying AMQP connection, then when this is complete the consumer is created and a handler registered that prints the body of incoming AMQP messages.

    var AmqpBridge = require("vertx-amqp-bridge-js/amqp_bridge");
    var bridge = AmqpBridge.create(vertx);
    // Start the bridge, then use the event loop thread to process things thereafter.
    bridge.start("localhost", 5672, function (res, res_err) {
      // Set up a consumer using the bridge, register a handler for it.
      var consumer = bridge.createConsumer("myAmqpAddress");
      consumer.handler(function (vertxMsg) {
        var amqpMsgPayload = vertxMsg.body();
        var amqpBody = amqpMsgPayload.body;

        console.log("Received a message with body: " + amqpBody);
      });
    });

### Message payload

The message payload is passed as a JsonObject with elements representing various sections of the AMQP message.

The top-level elements supported are:

- body: The content for the body section of the AMQP message.

- body_type: An optional String used to indicate whether the "body" element represents an AmqpValue (default), Data, or AmqpSequence section. The values used are "value", "data", and "sequence" respectively.

- header: An optional JsonObject representing the elements of the message Header section. Expanded below.

- properties: An optional JsonObject representing the elements of the message Properties section. Expanded below.

- application_properties: An optional JsonObject containing any application defined properties(/headers).

- message_annotations: An optional JsonObject representing any message annotations.

The elements of the optional "header" sub-element are:

- durable: optional boolean indicating whether the message is durable (default false).

- priority: optional short indicating the message priority (default 4).

- ttl: optional long indicating ttl in milliseconds (no default). See also 'properties' absolute expiry time.

- first_acquirer: boolean indicating if this is the first acquirer of the message (default false)

- delivery_count: long indicating the number of previous failed delivery attempts for message.

The elements of the optional "properties" sub-element are:

- to: optional string with address message is being sent to (no default).

- reply_to: optional string with address for replies (no default). Set automatically when sent with reply handler.

- message_id: optional string with message id (no default). Set automatically when sending with reply handler.

- correlation_id: optional string with correlation id (no default). Set automatically when implicit reply is sent.

- subject: optional string with message subject (no default).

- group_id: optional string with message group id (no default).

- group_sequence: optional long with message group sequence (no default).

- reply_to_group_id: optional string with message reply to group id (no default).

- content_type: optional string with message content type (no default). Only for use with Data body sections.

- content_encoding: optional string with message content encoding (no default).

- creation_time: optional long with message creation time in milliseconds since the unix epoch (no default).

- absolute_expiry_time: optional long with absolute expiry time as milliseconds since the unix epoch (no default).

- user_id: optional string with the id of the user sending the message (no default).