io.mats3.matssocket

Enum MatsSocketServer.MatsSocketCloseCodes

java.lang.Object

java.lang.Enum<MatsSocketServer.MatsSocketCloseCodes>

io.mats3.matssocket.MatsSocketServer.MatsSocketCloseCodes

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<MatsSocketServer.MatsSocketCloseCodes>, javax.websocket.CloseReason.CloseCode

Enclosing interface:

MatsSocketServer

public static enum MatsSocketServer.MatsSocketCloseCodes
extends java.lang.Enum<MatsSocketServer.MatsSocketCloseCodes>
implements javax.websocket.CloseReason.CloseCode

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..!

Enum Constant Summary

Enum Constants

Enum Constant and Description
CLOSE_SESSION 4000: Both from Server side and Client/Browser side, client should REJECT all outstanding: From Client/Browser: Used when the client closes WebSocket "on purpose", wanting to close the session - typically when the user explicitly logs out, or navigates away from web page.
DISCONNECT 4003: From Server side: Currently used in the specific situation where a MatsSocket client connects with the same MatsSocketSessionId as an existing open WebSocket connection.
GOING_AWAY 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.
MATS_SOCKET_PROTOCOL_ERROR 4004: From Server side: Client should REJECT all outstanding and "crash"/reboot application: Used when the client does not speak the MatsSocket protocol correctly.
RECONNECT 4002: Both from Server side and from Client/Browser side: REISSUE all outstanding upon reconnect: From Client: The client just fancied a little break (just as if lost connection in a tunnel), used from integration tests. From Server: We ask that the client reconnects.
SERVICE_RESTART Standard code 1012 - From Server side, Client should REISSUE all outstanding upon reconnect: used when MatsSocketServer.stop(int) is invoked.
SESSION_LOST 4001: From Server side, Client should REJECT all outstanding and "crash"/reboot application: A HELLO:RECONNECT was attempted, but the session was gone.
UNEXPECTED_CONDITION Standard code 1011 - From Server side, Client should REJECT all outstanding and "crash"/reboot application.
VIOLATED_POLICY Standard code 1008 - From Server side, Client should REJECT all outstanding and "crash"/reboot application: used when we cannot authenticate.

Method Summary

Modifier and Type	Method and Description
static javax.websocket.CloseReason.CloseCode	getCloseCode(int code)
int	getCode()
static MatsSocketServer.MatsSocketCloseCodes	valueOf(java.lang.String name) Returns the enum constant of this type with the specified name.
static MatsSocketServer.MatsSocketCloseCodes[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

VIOLATED_POLICY

public static final MatsSocketServer.MatsSocketCloseCodes VIOLATED_POLICY

Standard code 1008 - From Server side, Client should REJECT all outstanding and "crash"/reboot application: used when we cannot authenticate.

May also be used locally from the Client: If the PreConnectOperation return status code 401 or 403 or the WebSocket connect attempt raises error too many times (e.g. total 3x number of URLs), the MatsSocket will be "Closed Session" with this status code.

UNEXPECTED_CONDITION

public static final MatsSocketServer.MatsSocketCloseCodes UNEXPECTED_CONDITION

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

public static final MatsSocketServer.MatsSocketCloseCodes SERVICE_RESTART

Standard code 1012 - From Server side, Client should REISSUE all outstanding upon reconnect: used when MatsSocketServer.stop(int) is invoked. Please reconnect.

GOING_AWAY

public static final MatsSocketServer.MatsSocketCloseCodes GOING_AWAY

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 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 MatsSocketSession.

CLOSE_SESSION

public static final MatsSocketServer.MatsSocketCloseCodes CLOSE_SESSION

4000: Both from Server side and Client/Browser side, client should REJECT all outstanding:

• From Client/Browser: Used when the client closes WebSocket "on purpose", wanting to close the session - typically when the user explicitly logs out, or navigates away from web page. All traces of the MatsSocketSession are effectively deleted from the server, including any undelivered replies and messages ("push") from server.
• From Server: MatsSocketServer.closeSession(String, String) was invoked, and the WebSocket to that client was still open, so we close it.

SESSION_LOST

public static final MatsSocketServer.MatsSocketCloseCodes SESSION_LOST

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

public static final MatsSocketServer.MatsSocketCloseCodes RECONNECT

4002: Both from Server side and from Client/Browser side: REISSUE all outstanding upon reconnect:

• From Client: The client just fancied a little break (just as if lost connection in a tunnel), used from integration tests.
• From Server: We ask that the client reconnects. This gets us a clean state and in particular new authentication (In case of using OAuth/OIDC tokens, the client is expected to fetch a fresh token from token server).

DISCONNECT

public static final MatsSocketServer.MatsSocketCloseCodes DISCONNECT

4003: From Server side: Currently used in the specific situation where a MatsSocket client connects with the same MatsSocketSessionId as an existing open 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 for this MatsSocketSessionId already existing. This is probably a transitory situation, which would have resolved itself after a while - but the MatsSocketServer will anyway close that existing connection to clean up - and uses this close code. (Note that in the current test suite, this double-connection situation is emulated using two different client instances using the same MatsSocketSessionId, something that shall never happen in actual use. In this case the "original" client being closed with this close code must not start reconnecting!)

MATS_SOCKET_PROTOCOL_ERROR

public static final MatsSocketServer.MatsSocketCloseCodes MATS_SOCKET_PROTOCOL_ERROR

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.

Method Detail

values

public static MatsSocketServer.MatsSocketCloseCodes[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (MatsSocketServer.MatsSocketCloseCodes c : MatsSocketServer.MatsSocketCloseCodes.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static MatsSocketServer.MatsSocketCloseCodes valueOf(java.lang.String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

java.lang.IllegalArgumentException - if this enum type has no constant with the specified name

java.lang.NullPointerException - if the argument is null

getCode

public int getCode()

Specified by:

getCode in interface javax.websocket.CloseReason.CloseCode

getCloseCode

public static javax.websocket.CloseReason.CloseCode getCloseCode(int code)

Parameters:

code - the code to get a CloseCode instance of.

Returns:

either a MatsSocketServer.MatsSocketCloseCodes, or a standard CloseReason.CloseCodes, or a newly created object containing the unknown close code with a toString() returning "UNKNOWN(code)".