io.mats3.matssocket

Interface MatsSocketServer.MatsSocketEndpointIncomingContext<I,MR,R>

Type Parameters:

I - MatsSocket Incoming type

MR - Mats reply type (i.e. the type of the reply from the Mats endpoint which was forwarded to)

R - MatsSocket Reply type

All Superinterfaces:

MatsSocketServer.MatsSocketEndpointContext<I,MR,R>

Enclosing interface:

MatsSocketServer

public static interface MatsSocketServer.MatsSocketEndpointIncomingContext<I,MR,R>
extends MatsSocketServer.MatsSocketEndpointContext<I,MR,R>

The context which the MatsSocketServer.IncomingAuthorizationAndAdapter gets to work with when handling an incoming MatsSocket message.

Please make absolutely certain that you understand that these messages originate directly from the hostile Internet, and you cannot assume that any values are benign - they might be tailored specifically to hack or crash your system. Act and code accordingly! Read more at the "Warning" in the MatsSocketServer class JavaDoc.

Method Summary

Modifier and Type	Method and Description
void	deny() Invoke if you want to deny this message from being processed, e.g.
void	forward(java.lang.String toMatsEndpointId, java.lang.Object matsMessage, io.mats3.MatsInitiator.InitiateLambda customInit) Generic forward method.
void	forwardEssential(java.lang.String toMatsEndpointId, java.lang.Object matsMessage) Employ this for Requests or Sends whose call flow can potentially change state in the system.
void	forwardNonessential(java.lang.String toMatsEndpointId, java.lang.Object matsMessage) Employ this for pure, non-state changing "GET-style" Requests, or Sends for e.g.
java.util.EnumSet<AuthenticationPlugin.DebugOption>	getAllowedDebugOptions()
java.lang.String	getAuthorizationValue()
byte[]	getCorrelationBinary() If this is a Client Reply from a Server-to-Client request, this method returns the 'correlationBinary' that was provided in the request.
java.lang.String	getCorrelationString() If this is a Client Reply from a Server-to-Client request, this method returns the 'correlationString' that was provided in the request.
io.mats3.MatsInitiator.MatsInitiate	getMatsInitiate() Using the returned MatsInitiate instance, which is the same as the forwardXX(..) methods utilize, you can initiate one or several Mats flows, in addition to your actual handling of the incoming message - within the same Mats transactional demarcation as the handling of the incoming message ("actual handling" referring to forward, resolve, reject or even deny or ignore - the latter two being a bit hard to understand why you'd want).
I	getMatsSocketIncomingMessage()
java.lang.String	getMatsSocketSessionId()
MatsSocketServer.MessageType	getMessageType()
java.security.Principal	getPrincipal()
java.util.EnumSet<AuthenticationPlugin.DebugOption>	getResolvedDebugOptions()
MatsSocketServer.LiveMatsSocketSession	getSession()
java.lang.String	getTraceId()
java.lang.String	getUserId()
void	reject(R matsSocketRejectMessage) Only for REQUESTs: Send "Reject" reply (rejects the client side Promise) to the MatsSocket directly, i.e.
void	resolve(R matsSocketResolveMessage) Only for REQUESTs: Send "Resolve" reply (resolves the client side Promise) to the MatsSocket directly, i.e.

Methods inherited from interface io.mats3.matssocket.MatsSocketServer.MatsSocketEndpointContext

getMatsSocketEndpoint, getMatsSocketEndpointId

Method Detail

getSession

MatsSocketServer.LiveMatsSocketSession getSession()

Returns:

the MatsSocketServer.LiveMatsSocketSession for the requesting MatsSocketSession.

getAuthorizationValue

java.lang.String getAuthorizationValue()

Returns:

current Authorization Value in effect for the MatsSocket that delivered the message. This String is what resolves to the current Principal and UserId via the AuthenticationPlugin.

getPrincipal

java.security.Principal getPrincipal()

Returns:

the resolved Principal from the Authorization Value, via the AuthenticationPlugin. It is assumed that you must cast this to a more specific class which the current AuthenticationPlugin provides.

getUserId

java.lang.String getUserId()

Returns:

the resolved UserId for the Authorization Value.

getAllowedDebugOptions

java.util.EnumSet<AuthenticationPlugin.DebugOption> getAllowedDebugOptions()

Returns:

the set of AuthenticationPlugin.DebugOption the the active AuthenticationPlugin allows the current Principal to request.

getResolvedDebugOptions

java.util.EnumSet<AuthenticationPlugin.DebugOption> getResolvedDebugOptions()

Returns:

the set of AuthenticationPlugin.DebugOption the the current message tells that us the Client requests, intersected with what active AuthenticationPlugin allows the current Principal to request.

getMatsSocketSessionId

java.lang.String getMatsSocketSessionId()

Returns:

the MatsSocketSession Id. This can be useful when wanting to do a MatsSocketServer.send(String, String, String, Object).

getTraceId

java.lang.String getTraceId()

Returns:

the TraceId accompanying the incoming message.

getMessageType

MatsSocketServer.MessageType getMessageType()

Returns:

the MatsSocketServer.MessageType of the message being processed - either SEND, REQUEST, RESOLVE or REJECT (the two latter are Reply-types to a previous REQUEST).

getMatsSocketIncomingMessage

I getMatsSocketIncomingMessage()

Returns:

the incoming MatsSocket Message.

getCorrelationString

java.lang.String getCorrelationString()

If this is a Client Reply from a Server-to-Client request, this method returns the 'correlationString' that was provided in the request.

Returns:

the 'correlationString' that was provided in the request , otherwise null.

getCorrelationBinary

byte[] getCorrelationBinary()

If this is a Client Reply from a Server-to-Client request, this method returns the 'correlationBinary' that was provided in the request.

Returns:

the 'correlationBinary' that was provided in the request , otherwise null.

deny

void deny()

Invoke if you want to deny this message from being processed, e.g. your preliminary Authorization checks determined that the current Principal is not allowed to perform the requested operation. Will send a "negative acknowledgement" to the client.

forwardNonessential

void forwardNonessential(java.lang.String toMatsEndpointId,
                         java.lang.Object matsMessage)

Employ this for pure, non-state changing "GET-style" Requests, or Sends for e.g. log event store/processing (do not use this method for audit logging, though - those you want reliable).

Sets the following properties on the forwarded message:

• Non-persistent: Since it is not vitally important that this message is not lost, non-persistent messaging can be used. The minuscule chance for this message to disappear is not worth the considerable overhead of store-and-forward multiple times to persistent storage. Also, speed is much more interesting.
• No audit: Since this message will not change the state of the system (i.e. the "GET-style" requests), using storage on auditing requests and replies is not worthwhile. Or this is a log event that will be stored by other means.
• Interactive: Set if a REQUEST, since a human is probably then waiting for the result. NOT set for other message types (SEND, RESOLVE or REJECT).

If the MessageType of the incoming message from the Client is REQUEST, it will be a Mats request(..) message, while if it was a SEND, RESOLVE or REJECT, it will be a Mats send(..) message.

Parameters:

toMatsEndpointId - which Mats endpoint to send to. Be observant of the skew between the two different name spaces: A MatsSocket EndpointId is local to this MatsSocketFactory, while a Mats EndpointId is global for the entire Mats fabric the MatsFactory resides on (i.e. which message queue it communicates with).

matsMessage - the message to send to the Mats endpoint.

forwardEssential

void forwardEssential(java.lang.String toMatsEndpointId,
                      java.lang.Object matsMessage)

Employ this for Requests or Sends whose call flow can potentially change state in the system.

Sets the following properties on the forwarded message:

• Persistent: Since it actually is vitally important that this message is not lost, persistent messaging must be used. It is worth the considerable overhead of store-and-forward multiple times to persistent storage to be sure that the message flow is finished. Also, reliability is much more important than speed.
• Audited: Since this message might change the state of the system, logging the entire message and response in an audit log is worth the storage use.
• Interactive: Set if a REQUEST, since a human is probably then waiting for the result. NOT set for other message types (SEND, RESOLVE or REJECT).

If the MessageType of the incoming message from the Client is REQUEST, it will be a Mats request(..) message, while if it was a SEND, RESOLVE or REJECT, it will be a Mats send(..) message.

Parameters:

toMatsEndpointId - which Mats endpoint to send to. Be observant of the skew between the two different name spaces: A MatsSocket EndpointId is local to this MatsSocketFactory, while a Mats EndpointId is global for the entire Mats fabric the MatsFactory resides on (i.e. which message queue it communicates with).

matsMessage - the message to send to the Mats endpoint.

forward

void forward(java.lang.String toMatsEndpointId,
             java.lang.Object matsMessage,
             io.mats3.MatsInitiator.InitiateLambda customInit)

Generic forward method. You are provided the InitiateLambda so that you can customize the created message, including setting TraceProperties. Note that "from" "to", and if REQUEST, "replyTo" with MatsSockets correlation state, will be set by the system. Also, the invocation of request(..) or send(..) will be done by the system - you are not supposed to do it! None of the "interactive", "nonPersistent" nor "noAudit" flags will be set (but you may set them!).

If the MessageType of the incoming message from the Client is REQUEST, it will be a Mats request(..) message, while if it was a SEND, RESOLVE or REJECT, it will be a Mats send(..) message.

Parameters:

toMatsEndpointId - which Mats endpoint to send to. Be observant of the skew between the two different name spaces: A MatsSocket EndpointId is local to this MatsSocketFactory, while a Mats EndpointId is global for the entire Mats fabric the MatsFactory resides on (i.e. which message queue it communicates with).

matsMessage - the message to send to the Mats endpoint.

customInit - the MatsInitiator.InitiateLambda of the Mats message, where you can customize the sending of the message.

getMatsInitiate

io.mats3.MatsInitiator.MatsInitiate getMatsInitiate()

Using the returned MatsInitiate instance, which is the same as the forwardXX(..) methods utilize, you can initiate one or several Mats flows, in addition to your actual handling of the incoming message - within the same Mats transactional demarcation as the handling of the incoming message ("actual handling" referring to forward, resolve, reject or even deny or ignore - the latter two being a bit hard to understand why you'd want).

Notice: As mentioned, this is the same instance as the forward-methods utilize, so you must not put it into some "intermediate" state where you've invoked some of its methods, but not invoked any of the finishing-methods matsInitiate.send(..) or .request(..) methods.

Returns:

the MatsInitiate instance which the forward methods utilize, where you can initiate one or several other Mats flows (in addition to actual handling of incoming message) within the same Mats transactional demarcation as the handling of the message.

resolve

void resolve(R matsSocketResolveMessage)

Only for REQUESTs: Send "Resolve" reply (resolves the client side Promise) to the MatsSocket directly, i.e. without forward to Mats - can be used if you can answer the MatsSocket request directly without going onto the Mats MQ fabric.

Parameters:

matsSocketResolveMessage - the resolve message (the actual reply), or null if you just want to resolve it without adding any information.

reject

void reject(R matsSocketRejectMessage)

Only for REQUESTs: Send "Reject" reply (rejects the client side Promise) to the MatsSocket directly, i.e. without forward to Mats - can be used if you can answer the MatsSocket request directly without going onto the Mats MQ fabric.

Parameters:

matsSocketRejectMessage - the reject message, or null if you just want to reject it without adding any information.