Package io.mats3.matssocket

Enum Class MatsSocketServer.MatsSocketCloseCodes

java.lang.Object
java.lang.Enum<MatsSocketServer.MatsSocketCloseCodes>
io.mats3.matssocket.MatsSocketServer.MatsSocketCloseCodes
All Implemented Interfaces:
Serializable, Comparable<MatsSocketServer.MatsSocketCloseCodes>, Constable, javax.websocket.CloseReason.CloseCode
Enclosing interface:
MatsSocketServer
public static enum MatsSocketServer.MatsSocketCloseCodes extends 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..!

  • Nested Class Summary

    Nested classes/interfaces inherited from class java.lang.Enum

    Enum.EnumDesc<E extends Enum<E>>

  • Enum Constant Summary

    Enum Constants
    Enum Constant
    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
    Description
    static javax.websocket.CloseReason.CloseCode
    getCloseCode(int code)
     
    int
    getCode()
     
    static MatsSocketServer.MatsSocketCloseCodes
    valueOf(String name)
    Returns the enum constant of this class with the specified name.
    static MatsSocketServer.MatsSocketCloseCodes[]
    values()
    Returns an array containing the constants of this enum class, in the order they are declared.

    Methods inherited from class java.lang.Enum

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

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Enum Constant Details

    • 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 Details

    • values

      public static MatsSocketServer.MatsSocketCloseCodes[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static MatsSocketServer.MatsSocketCloseCodes valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (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:
      IllegalArgumentException - if this enum class has no constant with the specified name
      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)".