com.r3corda.node.services.messaging / ArtemisMessagingService

# ArtemisMessagingService

`class ArtemisMessagingService : SingletonSerializeAsToken, MessagingServiceInternal`

This class implements the MessagingService API using Apache Artemis, the successor to their ActiveMQ product. Artemis is a message queue broker and here, we embed the entire server inside our own process. Nodes communicate with each other using an Artemis specific protocol, but it supports other protocols like AMQP/1.0 as well for interop.

The current implementation is skeletal and lacks features like security or firewall tunnelling (that is, you must be able to receive TCP connections in order to receive messages). It is good enough for local communication within a fully connected network, trusted network or on localhost.

### Parameters

`directory` - A place where Artemis can stash its message journal and other files.
`myHostPort` - What host and port to bind to for receiving inbound connections.
`config` - The config object is used to pass in the passwords for the certificate KeyStore and TrustStore
`defaultExecutor` - This will be used as the default executor to run message handlers on, if no other is specified.

### Types

Handler | `inner class Handler : MessageHandlerRegistration` A registration to handle messages of different types

### Constructors

<init> | `ArtemisMessagingService(directory: Path, myHostPort: <ERROR CLASS>, config: NodeConfiguration, defaultExecutor: Executor = RunOnCallerThread)` This class implements the MessagingService API using Apache Artemis, the successor to their ActiveMQ product. Artemis is a message queue broker and here, we embed the entire server inside our own process. Nodes communicate with each other using an Artemis specific protocol, but it supports other protocols like AMQP/1.0 as well for interop.

### Properties

config | `val config: NodeConfiguration`
defaultExecutor | `val defaultExecutor: Executor`
directory | `val directory: Path`
myAddress | `val myAddress: SingleMessageRecipient` Returns an address that refers to this node.
myHostPort | `val myHostPort: <ERROR CLASS>`

### Functions

addMessageHandler | `fun addMessageHandler(topic: String, sessionID: Long, executor: Executor?, callback: (Message, MessageHandlerRegistration) -> Unit): MessageHandlerRegistration` The provided function will be invoked for each received message whose topic matches the given string, on the given executor. `fun addMessageHandler(topicSession: TopicSession, executor: Executor?, callback: (Message, MessageHandlerRegistration) -> Unit): MessageHandlerRegistration` The provided function will be invoked for each received message whose topic and session matches, on the given executor.
configureWithDevSSLCertificate | `fun configureWithDevSSLCertificate(): Unit` Strictly for dev only automatically construct a server certificate/private key signed from the CA certs in Node resources. Then provision KeyStores into certificates folder under node path.
createMessage | `fun createMessage(topicSession: TopicSession, data: ByteArray): Message` `fun createMessage(topic: String, sessionID: Long, data: ByteArray): Message` Returns an initialised Message with the current time, etc, already filled in.
registerTrustedAddress | `fun registerTrustedAddress(address: SingleMessageRecipient): Unit`
removeMessageHandler | `fun removeMessageHandler(registration: MessageHandlerRegistration): Unit` Removes a handler given the object returned from addMessageHandler. The callback will no longer be invoked once this method has returned, although executions that are currently in flight will not be interrupted.
send | `fun send(message: Message, target: MessageRecipients): Unit` Sends a message to the given receiver. The details of how receivers are identified is up to the messaging implementation: the type system provides an opaque high level view, with more fine grained control being available via type casting. Once this function returns the message is queued for delivery but not necessarily delivered: if the recipients are offline then the message could be queued hours or days later.
start | `fun start(): Unit`
stop | `fun stop(): Unit`

### Inherited Functions

toToken | `open fun toToken(context: SerializeAsTokenContext): SerializationToken`

### Companion Object Properties

SESSION_ID_PROPERTY | `val SESSION_ID_PROPERTY: String`
TOPIC_PROPERTY | `val TOPIC_PROPERTY: String`
log | `val log: <ERROR CLASS>`

### Companion Object Functions

makeRecipient | `fun makeRecipient(hostAndPort: <ERROR CLASS>): SingleMessageRecipient` Temp helper until network map is established. `fun makeRecipient(hostname: String): <ERROR CLASS>`
toHostAndPort | `fun toHostAndPort(hostname: String): <ERROR CLASS>`

### Extension Functions

runOnNextMessage | `fun MessagingService.runOnNextMessage(topic: String, sessionID: Long, executor: Executor? = null, callback: (Message) -> Unit): Unit` Registers a handler for the given topic and session ID that runs the given callback with the message and then removes itself. This is useful for one-shot handlers that arent supposed to stick around permanently. Note that this callback doesnt take the registration object, unlike the callback to MessagingService.addMessageHandler, as the handler is automatically deregistered before the callback runs. `fun MessagingService.runOnNextMessage(topicSession: TopicSession, executor: Executor? = null, callback: (Message) -> Unit): Unit` Registers a handler for the given topic and session that runs the given callback with the message and then removes itself. This is useful for one-shot handlers that arent supposed to stick around permanently. Note that this callback doesnt take the registration object, unlike the callback to MessagingService.addMessageHandler.
send | `fun MessagingService.send(topic: String, sessionID: Long, payload: Any, to: MessageRecipients): Unit` `fun MessagingService.send(topicSession: TopicSession, payload: Any, to: MessageRecipients): Unit`