Package io.mats3
Interface MatsInitiator
- All Superinterfaces:
AutoCloseable
,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 ClassesModifier and TypeInterfaceDescriptionstatic interface
@FunctionalInterface
for the "initiate lambda" - what you supply to theinitiate
method.static enum
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
Will be thrown by theinitiate(InitiateLambda)
-method if it is not possible at this time to establish a connection to the underlying messaging system (e.g.static class
Unchecked variant of theMatsInitiator.MatsBackendException
, thrown from theinitiateUnchecked(InitiateLambda)
variant of initiate().static interface
An implementation of this interface is given to you when you want to initiate a new Mats Flow.static class
A base Wrapper forMatsInitiator.MatsInitiate
, which simply implements MatsInitiate, takes a MatsInitiate instance and forwards all calls to that.static class
Will be thrown by theinitiate(InitiateLambda)
-method if Mats fails to send the messages after theMatsInitiator.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
Unchecked variant of theMatsInitiator.MatsMessageSendException
, thrown from theinitiateUnchecked(InitiateLambda)
variant of initiate().static interface
Reference information about the outgoing message. -
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Closes any underlying backend resource.getName()
void
initiate
(MatsInitiator.InitiateLambda lambda) Initiates a new message ("request" or "send") out to an endpoint: You provide a lambda which is supplied theMatsInitiator.MatsInitiate
instance on which you invoke methods to construct and dispatch messages.void
Variant ofinitiate(InitiateLambda)
where the two error conditions are raised as unchecked exceptions (But please understand the implications ofMatsInitiator.MatsMessageSendRuntimeException
!)
-
Method Details
-
getName
String getName()- Returns:
- the name of this
MatsInitiator
. Thedefault 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 theMatsInitiator.MatsInitiate
instance on which you invoke methods to construct and dispatch messages. TheMatsInitiator.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 theMatsInitiator.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 ofinitiate(InitiateLambda)
where the two error conditions are raised as unchecked exceptions (But please understand the implications ofMatsInitiator.MatsMessageSendRuntimeException
!)- Parameters:
lambda
- provides theMatsInitiator.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 ofMatsInitiator.MatsMessageSendException
.
-
close
void close()Closes any underlying backend resource.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-