io.mats3

Interface MatsInitiator

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

public interface MatsInitiator
extends java.io.Closeable

Provides the means to get hold of a MatsInitiator.MatsInitiate instance for initiating Mats message flows: You fetch an instance implementing this interface using typically MatsFactory.getDefaultInitiator(), and then invoke initiate(InitiateLambda), where the lambda will provide you with the necessary MatsInitiator.MatsInitiate instance on which you have methods to construct and dispatch e.g. "send" and "request" Messages.

Notice: This class is Thread Safe - you are not supposed to make one instance per message initiation, but rather make one (or a few) for the entire application, and use it/them for all your initiation needs. The mentioned MatsFactory.getDefaultInitiator() is what you typically want to use, get the instance, and keep it to perform all your Mats initiations. For example, in a Spring-based service, you'd typically put it in the Spring context, and inject it where ever there is a need to perform Mats initiations.

Implementation Note: It shall be possible to use instances of MatsInitiator as keys in a HashMap, i.e. their equals and hashCode should remain stable throughout the life of the MatsFactory - and similar instances but with different MatsFactory are not equals. Depending on the implementation, instance equality may be sufficient.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	MatsInitiator.InitiateLambda @FunctionalInterface for the "initiate lambda" - what you supply to the initiate method.
static class	MatsInitiator.KeepTrace A hint to the underlying implementation of how much historic debugging information for the call flow should be retained in the underlying protocol.
static class	MatsInitiator.MatsBackendException Will be thrown by the initiate(InitiateLambda)-method if it is not possible at this time to establish a connection to the underlying messaging system (e.g.
static class	MatsInitiator.MatsBackendRuntimeException Unchecked variant of the MatsInitiator.MatsBackendException, thrown from the initiateUnchecked(InitiateLambda) variant of initiate().
static interface	MatsInitiator.MatsInitiate An implementation of this interface is given to you when you want to initiate a new Mats Flow.
static class	MatsInitiator.MatsInitiateWrapper A base Wrapper for MatsInitiator.MatsInitiate, which simply implements MatsInitiate, takes a MatsInitiate instance and forwards all calls to that.
static class	MatsInitiator.MatsMessageSendException Will be thrown by the initiate(InitiateLambda)-method if Mats fails to send the messages after the MatsInitiator.InitiateLambda has been run, any external resource (typically DB) has been committed, and then some situation occurs that makes it impossible to send out messages.
static class	MatsInitiator.MatsMessageSendRuntimeException Unchecked variant of the MatsInitiator.MatsMessageSendException, thrown from the initiateUnchecked(InitiateLambda) variant of initiate().
static interface	MatsInitiator.MessageReference Reference information about the outgoing message.

Method Summary

Modifier and Type	Method and Description
void	close() Closes any underlying backend resource.
java.lang.String	getName()
MatsFactory	getParentFactory()
void	initiate(MatsInitiator.InitiateLambda lambda) Initiates a new message ("request" or "send") out to an endpoint: You provide a lambda which is supplied the MatsInitiator.MatsInitiate instance on which you invoke methods to construct and dispatch messages.
void	initiateUnchecked(MatsInitiator.InitiateLambda lambda) Variant of initiate(InitiateLambda) where the two error conditions are raised as unchecked exceptions (But please understand the implications of MatsInitiator.MatsMessageSendRuntimeException!)

Method Detail

getName

java.lang.String getName()

Returns:

the name of this MatsInitiator. The default initiator's name is 'default'.

getParentFactory

MatsFactory getParentFactory()

Returns:

the parent MatsFactory.

initiate

void initiate(MatsInitiator.InitiateLambda lambda)
       throws MatsInitiator.MatsBackendException,
              MatsInitiator.MatsMessageSendException

Initiates a new message ("request" or "send") out to an endpoint: You provide a lambda which is supplied the MatsInitiator.MatsInitiate instance on which you invoke methods to construct and dispatch messages. The InitiateLambda#initiate(MatsInitiate) will be invoked in a transactional context, which will also include database operations that are invoked inside the lambda if the transaction manager for the MatsFactory is also used for database operations. This also implies that either all messages produced in the lambda will be sent, or none will.

Parameters:

lambda - provides the MatsInitiator.MatsInitiate instance on which to create the message to be sent.

Throws:

MatsInitiator.MatsBackendException - if the Mats implementation cannot connect to the underlying message broker, or are having problems interacting with it.

MatsInitiator.MatsMessageSendException - if the Mats implementation cannot send the messages after it has executed the initiation lambda and committed external resources - please read the JavaDoc of that class.

initiateUnchecked

void initiateUnchecked(MatsInitiator.InitiateLambda lambda)
                throws MatsInitiator.MatsBackendRuntimeException,
                       MatsInitiator.MatsMessageSendRuntimeException

Variant of initiate(InitiateLambda) where the two error conditions are raised as unchecked exceptions (But please understand the implications of MatsInitiator.MatsMessageSendRuntimeException!)

Parameters:

lambda - provides the MatsInitiator.MatsInitiate instance on which to create the message to be sent.

Throws:

MatsInitiator.MatsBackendRuntimeException - if the Mats implementation cannot connect to the underlying message broker, or are having problems interacting with it.

MatsInitiator.MatsMessageSendRuntimeException - if the Mats implementation cannot send the messages after it has executed the initiation lambda and committed external resources - please read the JavaDoc of MatsInitiator.MatsMessageSendException.

close

void close()

Closes any underlying backend resource.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable