Members
(constant) AuthorizationRequiredEventType :string
Type of AuthorizationRequiredEvent.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
NOT_PRESENT |
string | Initial state, if auth not already set by app. |
EXPIRED |
string | The authentication is expired - note that this might well still be in the future, but the "slack" left before expiration is not long enough. |
REAUTHENTICATE |
string | The server has requested that the app provides fresh auth to proceed - this needs to be fully fresh, even though there might still be "slack" enough left on the current authorization to proceed. (The server side might want the full expiry to proceed, or wants to ensure that the app can still produce new auth - i.e. it might suspect that the current authentication session has been invalidated, and need proof that the app can still produce new authorizations/tokens). |
- Source:
(constant) ConnectionEventType :string
The event types of ConnectionEvent - four of the event types are state-transitions into different states
of ConnectionState.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
CONNECTING |
string | State, and fires as ConnectionEvent when we transition into this state, which is when the WebSocket is literally trying to connect.
This is between new WebSocket(url) (or the "PreConnectOperation" if configured),
and either webSocket.onopen or webSocket.onclose is fired, or countdown reaches 0. If webSocket.onopen,
we transition into ConnectionEventType.CONNECTED, if webSocket.onclose, we transition into
ConnectionEventType.WAITING. If we reach countdown 0 while in CONNECTING, we will "re-transition" to the same state, and
thus get one more event of CONNECTING.
User Info Tip: Show a info-box, stating "Connecting! <4.0 seconds..>", countdown in "grayed out" style, box is
some neutral information color, e.g. yellow (fading over to this color if already red or orange due to
ConnectionEventType.CONNECTION_ERROR or ConnectionEventType.LOST_CONNECTION).
Each time it transitions into CONNECTING, it will start a new countdown. Let's say it starts from say 4
seconds: If this connection attempt fails after 1 second, it will transition into WAITING and continue the
countdown with 3 seconds remaining. |
WAITING |
string | State, and fires as ConnectionEvent when we transition into this state, which is when ConnectionEventType.CONNECTING fails. The only transition out of this state is ConnectionEventType.CONNECTING, when the ConnectionEventType.COUNTDOWN reaches 0. Notice that the ConnectionEvent contains the Event that came with webSocket.close (while CONNECTING). User Info Tip: Show a info-box, stating "Waiting! <2.9 seconds..>", countdown in normal visibility, box is some neutral information color, e.g. yellow (keeping the box color fading if in progress). It will come into this state from ConnectionEventType.CONNECTING, and have the time remaining from the initial countdown. So if the attempt countdown started from 4 seconds, and it took 1 second before the connection attempt failed, then there will be 3 seconds left in WAITING state. |
CONNECTED |
string | State, and fires as ConnectionEvent when we transition into this state, which is when WebSocket.onopen is fired. Notice that the MatsSocket is still not fully established, as we have not yet exchanged HELLO and WELCOME - the MatsSocket is fully established at ConnectionEventType.SESSION_ESTABLISHED. Notice that the ConnectionEvent contains the WebSocket 'onopen' Event that was issued when the WebSocket opened. User Info Tip: Show a info-box, stating "Connected!", happy-color, e.g. green, with no countdown. |
SESSION_ESTABLISHED |
string | State, and fires as ConnectionEvent when we transition into this state, which is when when the WELCOME MatsSocket message comes from the Server, also implying that it has been authenticated: The MatsSocket is now fully established, and actual messages can be exchanged. User Info Tip: Show a info-box, stating "Session OK!", happy-color, e.g. green, with no countdown - and the entire info-box fades away fast, e.g. after 1 second. |
CONNECTION_ERROR |
string | This is a pretty worthless event. It comes from WebSocket.onerror. It will always be trailed by a WebSocket.onclose, which gives the event ConnectionEventType.LOST_CONNECTION. Notice that the ConnectionEvent contains the Event that caused the error. User Info Tip: Show a info-box, which is some reddish color (no need for text since next event ConnectionEventType.LOST_CONNECTION) comes immediately). |
LOST_CONNECTION |
string | This comes when WebSocket.onclose is fired "unexpectedly", and the reason for this close is NOT a SessionClosed Event (The latter will instead invoke the listeners registered with MatsSocket#addSessionClosedEventListener). A LOST_CONNECTION will start a reconnection attempt after a very brief delay (couple of hundred milliseconds), and the next state transition and thus event is ConnectionEventType.CONNECTING. Notice that the ConnectionEvent contains the CloseEvent that caused the lost connection. User Info Tip: Show a info-box, stating "Connection broken!", which is some orange color (unless it already is red due to ConnectionEventType.CONNECTION_ERROR), fading over to the next color when next event (ConnectionEventType.CONNECTING comes in. |
COUNTDOWN |
string | Events fired every 100ms while in state ConnectionEventType.CONNECTING, possibly continuing over to ConnectionEventType.WAITING. Notice that you will most probably not get an event with 0 seconds left, as that is when we (re-)transition to ConnectionEventType.CONNECTING and the countdown starts over (possibly with a larger timeout). Read more at ConnectionEvent#countdownSeconds. User Info Tip: Read more at ConnectionEventType.CONNECTING and ConnectionEventType.WAITING. |
- Source:
(constant) ConnectionState :string
States for MatsSocket's state.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
NO_SESSION |
string | This is the initial State of a MatsSocket. Also, the MatsSocket is re-set back to this State in a Session-Closed-from-Server situation (which is communicated via listeners registered with MatsSocket#addSessionClosedEventListener), OR if you have explicitly performed a MatsSocket#close. Only transition out of this state is into ConnectionState.CONNECTING. |
CONNECTING |
string | Read doc at ConnectionEventType.CONNECTING. |
WAITING |
string | Read doc at ConnectionEventType.WAITING. |
CONNECTED |
string | Read doc at ConnectionEventType.CONNECTED. |
SESSION_ESTABLISHED |
string | Read doc at ConnectionEventType.SESSION_ESTABLISHED. |
- Source:
(constant) DebugOption :string
Copied directly from AuthenticationPlugin.java:
Types of debug information you can request, read more at MatsSocket#debug and MessageEvent#debug.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
TIMESTAMPS |
string | Timing info of the separate phases. Note that time-skew between different nodes must be taken into account. |
NODES |
string | Node-name of the handling nodes of the separate phases. |
CUSTOM_A |
string | AuthenticationPlugin -specific "Option A" - this is not used by MatsSocket itself, but can be employed
and given a meaning by the AuthenticationPlugin .
Notice: You might be just as well off by implementing such functionality on the Principal returned by
the AuthenticationPlugin ("this user is allowed to request these things") - and on the request DTOs
from the Client ("I would like to request these things"). |
CUSTOM_B |
string | AuthenticationPlugin -specific "Option B" - this is not used by MatsSocket itself, but can be employed
and given a meaning by the AuthenticationPlugin .
Notice: You might be just as well off by implementing such functionality on the Principal returned by
the AuthenticationPlugin ("this user is allowed to request these things") - and on the request DTOs
from the Client ("I would like to request these things"). |
- Source:
(constant) InitiationProcessedEventType :string
Type of InitiationProcessedEvent - the type of the initiation of a flow, which also
determines which fields of the
InitiationProcessedEvent
are set.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
SEND |
string | Flow initiated with MatsSocket#send(). Fields whose name does not start with "reply" or "request" will be set. |
REQUEST |
string | Flow initiated with MatsSocket#request(). Will have all fields except InitiationProcessedEvent#replyToTerminatorId set. |
REQUEST_REPLY_TO |
string | Flow initiated with MatsSocket#requestReplyTo(). Will have all fields set. |
- Source:
(constant) MatsSocketCloseCodes :int
Copied directly from MatsSocketServer.java:
WebSocket CloseCodes used in MatsSocket, and for what. Using both standard codes, and MatsSocket-specific/defined
codes.
Note: Plural "Codes" since that is what the JSR 356 Java WebSocket API does..!
Type:
- int
Properties:
Name | Type | Description |
---|---|---|
VIOLATED_POLICY |
int | Standard code 1008 - From Server side, Client should REJECT all outstanding and "crash"/reboot application: used when the we cannot authenticate. |
UNEXPECTED_CONDITION |
int | Standard code 1011 - From Server side, Client should REJECT all outstanding and "crash"/reboot application. This is the default close code if the MatsSocket "onMessage"-handler throws anything, and may also explicitly be used by the implementation if it encounters a situation it cannot recover from. |
SERVICE_RESTART |
int | Standard code 1012 - From Server side, Client should REISSUE all outstanding upon reconnect: used when MatsSocketServer#stop(int) is invoked. Please reconnect. |
GOING_AWAY |
int | Standard code 1001 - From Client/Browser side, client should have REJECTed all outstanding: Synonym for #CLOSE_SESSION, as the WebSocket documentation states "indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page.", the latter point being pretty much exactly correct wrt. when to close a session. So, if a browser decides to use this code when the user navigates away and the client MatsSocket library or employing application does not catch it, we'd want to catch this as a Close Session. Notice that I've not experienced a browser that actually utilizes this close code yet, though! Notice that if a close with this close code is initiated from the Server-side, this should NOT be considered a CLOSE_SESSION by the neither the client nor the server! At least Jetty's implementation of JSR 356 WebSocket API for Java sends GOING_AWAY upon socket close due to timeout. Since a timeout can happen if we loose connection and thus can't convey PINGs, the MatsSocketServer must not interpret Jetty's timeout-close as Close Session. Likewise, if the client just experienced massive lag on the connection, and thus didn't get the PING over to the server in a timely fashion, but then suddenly gets Jetty's timeout close with GOING_AWAY, this should not be interpreted by the client as the server wants to close the session. |
CLOSE_SESSION |
int | 4000: Both from Server side and Client/Browser side, client should REJECT all outstanding:
|
SESSION_LOST |
int | 4001: From Server side, Client should REJECT all outstanding and "crash"/reboot application: A HELLO:RECONNECT was attempted, but the session was gone. A considerable amount of time has probably gone by since it last was connected. The client application must get its state synchronized with the server side's view of the world, thus the suggestion of "reboot". |
RECONNECT |
int | 4002: Both from Server side and from Client/Browser side: REISSUE all outstanding upon reconnect:
|
DISCONNECT |
int | 4003: From Server side: Currently used in the specific situation where a MatsSocket client connects with the same MatsSocketSessionId as an existing WebSocket connection. This could happen if the client has realized that a connection is wonky and wants to ditch it, but the server has not realized the same yet. When the server then gets the new connect, it'll see that there is an active WebSocket already. It needs to close that. But the client "must not do anything" other than what it already is doing - reconnecting. |
MATS_SOCKET_PROTOCOL_ERROR |
int | 4004: From Server side: Client should REJECT all outstanding and "crash"/reboot application: Used when the client does not speak the MatsSocket protocol correctly. Session is closed. |
nameFor |
int | Resolves the numeric "close code" to the String key name of this enum, or "UNKNOWN("+closeCode+")"
for unknown numeric codes. |
- Source:
(constant) MessageEventType :string
Types of MessageEvent.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
RESOLVE |
string | |
REJECT |
string | |
SEND |
string | |
REQUEST |
string | |
PUB |
string | |
TIMEOUT |
string | "Synthetic" event in that it is not a message from Server: A Client-to-Server Request was not replied to by the server within the default request timeout - or a specific timeout specified in the request invocation. In these situations, the Request Promise is rejected with a MessageEvent of this type, and the MessageEvent#data value is undefined. |
SESSION_CLOSED |
string | "Synthetic" event in that it is not a message from Server: This only happens if the MatsSocketSession is closed with outstanding Client-to-Server Requests not yet replied to by the server. In these situations, the Request Promise is rejected with a MessageEvent of this type, and the MessageEvent#data value is undefined. |
- Source:
(constant) MessageType :string
Copied directly from MatsSocketServer.java:
All Message Types (aka MatsSocket Envelope Types) used in the wire-protocol of MatsSocket.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
HELLO |
string | A HELLO message must be part of the first Pipeline of messages, preferably alone. One of the messages in the first Pipeline must have the "auth" field set, and it might as well be the HELLO. |
WELCOME |
string | The reply to a #HELLO, where the MatsSocketSession is established, and the MatsSocketSessionId is returned. If you included a MatsSocketSessionId in the HELLO, signifying that you want to reconnect to an existing session, and you actually get a WELCOME back, it will be the same as what you provided - otherwise the connection is closed with MatsSocketCloseCodes#SESSION_LOST. |
SEND |
string | The sender sends a "fire and forget" style message. |
REQUEST |
string | The sender initiates a request, to which a #RESOLVE or #REJECT message is expected. |
RETRY |
string | The sender should retry the message (the receiver could not handle it right now, but a Retry might fix it). |
ACK |
string | The specified message was Received, and acknowledged positively - i.e. the other party has decided to process it. The sender of the ACK has now taken over responsibility of the specified message, put it (at least the reference ClientMessageId) in its Inbox, and possibly started processing it. The reason for the Inbox is so that if it Receives the message again, it may just insta-ACK/NACK it and toss this copy out the window (since it has already handled it). When an ACK is received, the receiver may safely delete the acknowledged message from its Outbox. |
NACK |
string | The specified message was Received, but it did not acknowledge it - i.e. the other party has decided to NOT process it. The sender of the NACK has now taken over responsibility of the specified message, put it (at least the reference Client/Server MessageId) in its Inbox - but has evidently decided not to process it. The reason for the Inbox is so that if it Receives the message again, it may just insta-ACK/NACK it and toss this copy out the window (since it has already handled it). When an NACK is received, the receiver may safely delete the acknowledged message from its Outbox. |
ACK2 |
string | An "Acknowledge ^ 2", i.e. an acknowledge of the #ACK or #NACK. When the receiver gets this, it may safely delete the entry it has for the specified message from its Inbox. The message is now fully transferred from one side to the other, and both parties again has no reference to this message in their Inbox and Outbox. |
RESOLVE |
string | A RESOLVE-reply to a previous #REQUEST - if the Client did the {@code REQUEST}, the Server will answer with either a RESOLVE or #REJECT. |
REJECT |
string | A REJECT-reply to a previous #REQUEST - if the Client did the {@code REQUEST}, the Server will answer with either a REJECT or #RESOLVE. |
SUB |
string | Request from Client: The Client want to subscribe to a Topic, the TopicId is specified in 'eid'. |
UNSUB |
string | Request from Client: The Client want to unsubscribe to a Topic, the TopicId is specified in 'eid'. |
SUB_OK |
string | Reply from Server: Subscription was OK. If this is a reconnect, this indicates that any messages that was lost "while offline" will now be delivered/"replayed". |
SUB_LOST |
string | Reply from Server: Subscription went OK, but you've lost messages: The messageId that was referenced in the #SUB was not known to the server, implying that there are at least one message that has expired, and as such it can be many - so you won't get any "replayed". |
SUB_NO_AUTH |
string | Reply from Server: Subscription was not authorized - no messages for this Topic will be delivered. |
PUB |
string | Topic message from Server: A message is issued on Topic, the TopicId is specified in 'eid', while the message is in 'msg'. |
REAUTH |
string | The server requests that the Client re-authenticates, where the Client should immediately get a fresh authentication and send it back using either any message it has pending, or in a separate #AUTH message. Message processing - both processing of received messages, and sending of outgoing messages (i.e. Replies to REQUESTs, or Server-initiated SENDs and REQUESTs) will be stalled until such auth is gotten. |
AUTH |
string | From Client: The client can use a separate AUTH message to send over the requested #REAUTH (it could just as well put the 'auth' in a PING or any other message it had pending). |
PING |
string | A PING, to which a #PONG is expected. |
PONG |
string | A Reply to a #PING. |
- Source:
(constant) ReceivedEventType :string
Types of ReceivedEvent.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
ACK |
string | If the Server-side MatsSocketEndpoint/Terminator accepted the message for handling (and if relevant, forwarded it to the Mats fabric). The returned Promise of send() is resolved with this type of event. The 'receivedCallback' of a request() will get both "ack" and "nack", thus must check on the type if it makes a difference. |
NACK |
string | If the Server-side MatsSocketEndpoint/Terminator dit NOT accept the message, either explicitly with context.deny(), or by failing with Exception. The returned Promise of send() is rejected with this type of event. The 'receivedCallback' of a request() will get both "nack" and "ack", thus must check on the type if it makes a difference. Notice that a for a Client-initiated Request which is insta-rejected in the incomingHandler by invocation of context.reject(..), this implies acknowledge of the reception of the message, but reject as with regard to the reply (the Promise returned from request(..)). |
TIMEOUT |
string | "Synthetic" event in that it is not a message from Server: A Client-to-Server Request was not ACKed or NACKed by the server within the default request timeout - or a specific timeout specified in the request invocation. In these situations, any nack- or receivedCallback will be invoked with a ReceivedEvent of this type. |
SESSION_CLOSED |
string | "Synthetic" event in that it is not a message from Server: This only happens if the MatsSocketSession is closed with outstanding Initiations not yet Received on Server. In these situations, any nack- or receivedCallback will be invoked with a ReceivedEvent of this type. |
- Source:
(constant) SubscriptionEventType :string
Type of SubscriptionEvent.
Type:
- string
Properties:
Name | Type | Description |
---|---|---|
OK |
string | The subscription on the server side went ok. If reconnect, any missing messages are now being sent. |
NOT_AUTHORIZED |
string | You were not authorized to subscribe to this Topic. |
LOST_MESSAGES |
string | Upon reconnect, the "last message Id" was not known to the server, implying that there are lost messages. Since you will now have to handle this situation by other means anyway (e.g. do a request for all stock ticks between the last know timestamp and now), you will thus not get any of the lost messages even if the server has some. |
- Source:
Type Definitions
addPingPongCallback(pingPong)
Callback function for MatsSocket#addPingPongListener.
Parameters:
Name | Type | Description |
---|---|---|
pingPong |
PingPong | information about the ping and the pong. |
- Source:
authorizationExpiredCallback(authorizationRequiredEvent)
Callback function for MatsSocket#setAuthorizationExpiredCallback.
Parameters:
Name | Type | Description |
---|---|---|
authorizationRequiredEvent |
AuthorizationRequiredEvent | information about why authorization information is requested. |
- Source:
connectionEventCallback(connectionEvent)
Callback function for MatsSocket#addConnectionEventListener.
Parameters:
Name | Type | Description |
---|---|---|
connectionEvent |
ConnectionEvent | giving information about what happened. |
- Source:
errorEventCallback(errorEvent)
Callback function for MatsSocket#addErrorEventListener.
Parameters:
Name | Type | Description |
---|---|---|
errorEvent |
ErrorEvent | information about what error happened. |
- Source:
initiationProcessedEventCallback(initiationProcessedEvent)
Callback function for MatsSocket#addInitiationProcessedEventListener.
Parameters:
Name | Type | Description |
---|---|---|
initiationProcessedEvent |
InitiationProcessedEvent | information about the processing of the initiation. |
- Source:
sessionClosedEventCallback(closeEvent)
Callback function for MatsSocket#addSessionClosedEventListener.
Parameters:
Name | Type | Description |
---|---|---|
closeEvent |
CloseEvent | the WebSocket's CloseEvent. |
- Source:
subscriptionEventCallback(subscriptionEvent)
Callback function for MatsSocket#addSubscriptionEventListener.
Parameters:
Name | Type | Description |
---|---|---|
subscriptionEvent |
SubscriptionEvent | giving information about what the server had to say about subscriptions. |
- Source: