websocket-spec
  1. websocket-spec
  2. WEBSOCKET_SPEC-174

Add more detail to javax.websocket.Session JavaDoc about which methods do not throw IllegalStateException

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.0
    • Fix Version/s: None
    • Labels:
      None

      Description

      Current JavaDoc says this:

      Once the session is closed, it is no longer valid for use by applications. Calling any of its methods once the session has been closed will result in an IllegalStateException being thrown. Developers should retrieve any information from the session during the Endpoint.onClose(javax.websocket.Session, javax.websocket.CloseReason) method.

      I believe this needs more clarification. I submit the following:

      • close() and close(CloseReason), in accordance with the java.io.Closeable contract, must NOT throw an exception if the Session is already closed, but instead calling these after Session close should be a no-op. Since this is specified already in Closeable, it may or may not be necessary to specify this in Session, but I suggest it doesn't hurt, and makes it 100% unambiguous.
      • isOpen() should NOT throw an exception, since it is used to indicate whether the Session is open (and, thus, whether a subsequent call to some other method is unlikely to throw an IllegalStateException).
      • getId() should NOT throw an exception, since the String it returns cannot be acted upon, and the ID could be useful debugging/tracking/logging/troubleshooting information post-close.

        Activity

          People

          • Assignee:
            dannycoward
            Reporter:
            Nick Williams
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Time Tracking

              Estimated:
              Original Estimate - 15 minutes
              15m
              Remaining:
              Remaining Estimate - 15 minutes
              15m
              Logged:
              Time Spent - Not Specified
              Not Specified