ballerina/artemis module

Module overview

This module provides the capability to connect with a ActiveMQ Artemis broker using the Core API.

Samples

Artemis Producer

The following program produces message to the Artemis broker.

import ballerina/artemis;
import ballerina/log;

artemis:Producer prod = new({host:"localhost", port:61616}, "demo");
public function main() {
    var err = prod->send("Hello World!");
    if (err is error) {
        log:printError("Error occurred while sending message", err = err);
    }
    // Close the producer
    if (!prod.isClosed()) {
        err = prod->close();
        if (err is error) {
            log:printError("Error occurred closing producer", err = err);
        }
    }
}

Artemis consumer

The following program will consume a message from the Artemis broker.

@artemis:ServiceConfig {
    queueConfig: {
        queueName: "demo"
    }
}
service artemisConsumer on new artemis:Listener({host:"localhost", port:61616}) {
    resource function onMessage(artemis:Message message) {
        var payload = message.getPayload();
        if (payload is string) {
            io:println("Recieved: " + payload);
        }
    }
}

Module Detail

Records

Record Description
AddressConfiguration The ActiveMQ Artemis address related configuration. If the `autoCreated` is `false` an error will be thrown if the address does not exist. If `autocreated` is `true` and the address already exists then the `routingType` configuration would be ignored.
ArtemisError The Artemis error record.
ArtemisServiceConfig The configuration for an Artemis consumer service.
ConnectionConfiguration Configurations related to a Artemis `Connection`.
MessageConfiguration Represents a message sent and/or received by ActiveMQ Artemis.
QueueConfiguration ActiveMQ Artemis Queue configuration. If the `autoCreated` is `false` an error will be thrown if the queue does not exist. If `autocreated` is `true` and the queue already exists then the other configurations would be ignored.
SessionConfiguration Configurations related to a Artemis Session.
URLConfiguration The url configuration for `Producer` and `Consumer`.

Objects

Object Description
Listener

Represents ActiveMQ Artemis Listener. This is an abstraction for that includes the connection and session. Consumers are represented by the service attaching to this listener.

Endpoints

Endpoint Description
Connection

Represents ActiveMQ Artemis Connection.

Message

Represents ActiveMQ Artemis Message.

Producer

Represents ActiveMQ Artemis Producer.

Session

Represents ActiveMQ Artemis Session.

Type Definitions

Type Values Description
MessageType UNSUPPORTED | TEXT | STREAM | MAP | BYTES

ActiveMQ Artemis message types.

RoutingType MULTICAST | ANYCAST

Determines how messages are sent to the queues associated with an address.

Annotations

Name Attaches To Data Type Description
ServiceConfig service ArtemisServiceConfig

public type AddressConfiguration

The ActiveMQ Artemis address related configuration. If the `autoCreated` is `false` an error will be thrown if the address does not exist. If `autocreated` is `true` and the address already exists then the `routingType` configuration would be ignored.

Field Name Data Type Default Value Description
routingType MULTICAST|ANYCAST? ANYCAST

the routing type for the address, MULTICAST or ANYCAST

autoCreated boolean true

whether the address has to be auto created.

public type ArtemisError

The Artemis error record.

Field Name Data Type Default Value Description
message string

the error message.

public type ArtemisServiceConfig

The configuration for an Artemis consumer service.

Field Name Data Type Default Value Description
autoAck boolean true

whether to automatically acknowledge a service when a resource completes

queueConfig artemis:QueueConfiguration

the configuration for the queue to consume from

filter string? ()

only messages which match this filter will be consumed

browseOnly boolean false

whether the ClientConsumer will only browse the queue or consume messages

public type ConnectionConfiguration

Configurations related to a Artemis `Connection`.

Field Name Data Type Default Value Description
timeToLive int 60000

Connection's time-to-live. negative to disable or greater or equals to 0

callTimeout int 30000

The blocking calls timeout in milliseconds

consumerWindowSize int 1024 * 1024

Window size in bytes for flow control of the consumers created through this Connection

consumerMaxRate int -1

Maximum rate of message consumption for consumers created through this Connection

producerWindowSize int 64 * 1024

Window size for flow control of the producers created through this Connection

producerMaxRate int -1

The maximum rate of message production for producers created through this Connection

retryInterval int 2000

The time in milliseconds to retry connection

retryIntervalMultiplier float 1.0

Multiplier to apply to successive retry intervals

maxRetryInterval int 2000

The maximum retry interval (in the case a retry interval multiplier has been specified)

reconnectAttempts int 0

The maximum number of attempts to retry connection in case of failure

initialConnectAttempts int 1

The maximum number of attempts to establish an initial connection

public type MessageConfiguration

Represents a message sent and/or received by ActiveMQ Artemis.

Field Name Data Type Default Value Description
expiration int? ()

The expiration time of this message

timeStamp int? ()

The message timestamp

priority byte 0

the message priority (between 0 and 9 inclusive)

durable boolean true

whether the created message is durable or not

routingType MULTICAST|ANYCAST? ()

RoutingType of the message

public type QueueConfiguration

ActiveMQ Artemis Queue configuration. If the `autoCreated` is `false` an error will be thrown if the queue does not exist. If `autocreated` is `true` and the queue already exists then the other configurations would be ignored.

Field Name Data Type Default Value Description
queueName string

the name of the queue

addressName string? ()

the address queue is bound to. If the value is nil and autoCreated is true and the queue does not already exist then the address would take the name of the queue.

autoCreated boolean true

whether to automatically create the queue

routingType MULTICAST|ANYCAST? ANYCAST

the routing type for the queue, MULTICAST or ANYCAST

temporary boolean true

whether the queue is temporary. If this value is set to true the durable property value shall be ignored.

filter string? ()

messages which match this filter will be put in the queue

durable boolean false

whether the queue is durable or not. If temporary property value is true this value

maxConsumers int -1

how many concurrent consumers will be allowed on this queue

purgeOnNoConsumers boolean false

whether to delete the contents of the queue when the last consumer disconnects

exclusive boolean false

whether the queue should be exclusive

lastValue boolean false

whether the queue should be lastValue

public type SessionConfiguration

Configurations related to a Artemis Session.

Field Name Data Type Default Value Description
username string? ()

The username

password string? ()

The password

public type URLConfiguration

The url configuration for `Producer` and `Consumer`.

Field Name Data Type Default Value Description
host string

The host

port int

The port

username string

The username

password string

The password

public type Listener object

Represents ActiveMQ Artemis Listener. This is an abstraction for that includes the connection and session. Consumers are represented by the service attaching to this listener.

  • <Listener> __init(artemis:Session|artemis:URLConfiguration sesssionOrURLConfig)

    Parameter Name Data Type Default Value Description
    sesssionOrURLConfig artemis:Session|artemis:URLConfiguration
  • <Listener> __start() returns (error?<>)

    Return Type Description
    error?<>
  • <Listener> __stop() returns (error?<>)

    Return Type Description
    error?<>
  • <Listener> __attach(service serviceType, string? name) returns (error?<>)

    Parameter Name Data Type Default Value Description
    serviceType service
    name string? ()
    Return Type Description
    error?<>

Endpoint Connection

Represents ActiveMQ Artemis Connection.

  • <Connection> close()

    Closes the connection and release all its resources.

Endpoint Message

Represents ActiveMQ Artemis Message.

  • <Message> acknowledge() returns (error?<>)

    Acknowledges reception of this message.

    Return Type Description
    error?<>

    If an error occurred while acknowledging the message

Endpoint Producer

Represents ActiveMQ Artemis Producer.

  • <Producer> send(int|float|string|json|xml|byte|byte[]|map<string|int|float|byte|boolean|byte[]>|io:ReadableByteChannel|artemis:Message data) returns (error?<>)

    Sends a message to the producer's address.

    Parameter Name Data Type Default Value Description
    data int|float|string|json|xml|byte|byte">byte[]|map<string|int|float|byte|boolean|byte">byte[]>|io:ReadableByteChannel|artemis:Message

    the Message or data to send

    Return Type Description
    error?<>

    error on failure

  • <Producer> close() returns (error?<>)

    Closes the ClientProducer. If already closed nothing is done.

    Return Type Description
    error?<>

    error on failure to close.

Endpoint Session

Represents ActiveMQ Artemis Session.

  • <Session> close() returns (error?<>)

    Closes the connection and release all its resources

    Return Type Description
    error?<>

    error if an error occurs closing the connection or nil