查看本类的 API文档回源码主页

   /*
    * Copyright 2019 The Netty Project
    *
    * The Netty Project licenses this file to you under the Apache License,
    * version 2.0 (the "License"); you may not use this file except in compliance
    * with the License. You may obtain a copy of the License at:
    *
    *   https://www.apache.org/licenses/LICENSE-2.0
    *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   * License for the specific language governing permissions and limitations
   * under the License.
   */
  package io.netty.handler.codec.http.websocketx;
  
  import static io.netty.util.internal.ObjectUtil.checkNotNull;
  
  /**
   * WebSocket status codes specified in RFC-6455.
   * <pre>
   *
   * RFC-6455 The WebSocket Protocol, December 2011:
   * <a href="https://tools.ietf.org/html/rfc6455#section-7.4.1"
   *         >https://tools.ietf.org/html/rfc6455#section-7.4.1</a>
   *
   * WebSocket Protocol Registries, April 2019:
   * <a href="https://www.iana.org/assignments/websocket/websocket.xhtml#close-code-number"
   *         >https://www.iana.org/assignments/websocket/websocket.xhtml</a>
   *
   * 7.4.1.  Defined Status Codes
   *
   * Endpoints MAY use the following pre-defined status codes when sending
   * a Close frame.
   *
   * 1000
   *
   *    1000 indicates a normal closure, meaning that the purpose for
   *    which the connection was established has been fulfilled.
   *
   * 1001
   *
   *    1001 indicates that an endpoint is "going away", such as a server
   *    going down or a browser having navigated away from a page.
   *
   * 1002
   *
   *    1002 indicates that an endpoint is terminating the connection due
   *    to a protocol error.
   *
   * 1003
   *
   *    1003 indicates that an endpoint is terminating the connection
   *    because it has received a type of data it cannot accept (e.g., an
   *    endpoint that understands only text data MAY send this if it
   *    receives a binary message).
   *
   * 1004
   *
   *    Reserved. The specific meaning might be defined in the future.
   *
   * 1005
   *
   *    1005 is a reserved value and MUST NOT be set as a status code in a
   *    Close control frame by an endpoint. It is designated for use in
   *    applications expecting a status code to indicate that no status
   *    code was actually present.
   *
   * 1006
   *
   *    1006 is a reserved value and MUST NOT be set as a status code in a
   *    Close control frame by an endpoint. It is designated for use in
   *    applications expecting a status code to indicate that the
   *    connection was closed abnormally, e.g., without sending or
   *    receiving a Close control frame.
   *
   * 1007
   *
   *    1007 indicates that an endpoint is terminating the connection
   *    because it has received data within a message that was not
   *    consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
   *    data within a text message).
   *
   * 1008
   *
   *    1008 indicates that an endpoint is terminating the connection
   *    because it has received a message that violates its policy. This
   *    is a generic status code that can be returned when there is no
   *    other more suitable status code (e.g., 1003 or 1009) or if there
   *    is a need to hide specific details about the policy.
   *
   * 1009
   *
   *    1009 indicates that an endpoint is terminating the connection
   *    because it has received a message that is too big for it to
   *    process.
   *
   * 1010
  *
  *    1010 indicates that an endpoint (client) is terminating the
  *    connection because it has expected the server to negotiate one or
  *    more extension, but the server didn't return them in the response
  *    message of the WebSocket handshake. The list of extensions that
  *    are needed SHOULD appear in the /reason/ part of the Close frame.
  *    Note that this status code is not used by the server, because it
  *    can fail the WebSocket handshake instead.
  *
  * 1011
  *
  *    1011 indicates that a server is terminating the connection because
  *    it encountered an unexpected condition that prevented it from
  *    fulfilling the request.
  *
  * 1012 (IANA Registry, Non RFC-6455)
  *
  *    1012 indicates that the service is restarted. a client may reconnect,
  *    and if it choses to do, should reconnect using a randomized delay
  *    of 5 - 30 seconds.
  *
  * 1013 (IANA Registry, Non RFC-6455)
  *
  *    1013 indicates that the service is experiencing overload. a client
  *    should only connect to a different IP (when there are multiple for the
  *    target) or reconnect to the same IP upon user action.
  *
  * 1014 (IANA Registry, Non RFC-6455)
  *
  *    The server was acting as a gateway or proxy and received an invalid
  *    response from the upstream server. This is similar to 502 HTTP Status Code.
  *
  * 1015
  *
  *    1015 is a reserved value and MUST NOT be set as a status code in a
  *    Close control frame by an endpoint. It is designated for use in
  *    applications expecting a status code to indicate that the
  *    connection was closed due to a failure to perform a TLS handshake
  *    (e.g., the server certificate can't be verified).
  *
  *
  * 7.4.2. Reserved Status Code Ranges
  *
  * 0-999
  *
  *    Status codes in the range 0-999 are not used.
  *
  * 1000-2999
  *
  *    Status codes in the range 1000-2999 are reserved for definition by
  *    this protocol, its future revisions, and extensions specified in a
  *    permanent and readily available public specification.
  *
  * 3000-3999
  *
  *    Status codes in the range 3000-3999 are reserved for use by
  *    libraries, frameworks, and applications. These status codes are
  *    registered directly with IANA. The interpretation of these codes
  *    is undefined by this protocol.
  *
  * 4000-4999
  *
  *    Status codes in the range 4000-4999 are reserved for private use
  *    and thus can't be registered. Such codes can be used by prior
  *    agreements between WebSocket applications. The interpretation of
  *    these codes is undefined by this protocol.
  * </pre>
  * <p>
  * While {@link WebSocketCloseStatus} is enum-like structure, its instances should NOT be compared by reference.
  * Instead, either {@link #equals(Object)} should be used or direct comparison of {@link #code()} value.
  */
 public final class WebSocketCloseStatus implements Comparable<WebSocketCloseStatus> {
 
     public static final WebSocketCloseStatus NORMAL_CLOSURE =
         new WebSocketCloseStatus(1000, "Bye");
 
     public static final WebSocketCloseStatus ENDPOINT_UNAVAILABLE =
         new WebSocketCloseStatus(1001, "Endpoint unavailable");
 
     public static final WebSocketCloseStatus PROTOCOL_ERROR =
         new WebSocketCloseStatus(1002, "Protocol error");
 
     public static final WebSocketCloseStatus INVALID_MESSAGE_TYPE =
         new WebSocketCloseStatus(1003, "Invalid message type");
 
     public static final WebSocketCloseStatus INVALID_PAYLOAD_DATA =
         new WebSocketCloseStatus(1007, "Invalid payload data");
 
     public static final WebSocketCloseStatus POLICY_VIOLATION =
         new WebSocketCloseStatus(1008, "Policy violation");
 
     public static final WebSocketCloseStatus MESSAGE_TOO_BIG =
         new WebSocketCloseStatus(1009, "Message too big");
 
     public static final WebSocketCloseStatus MANDATORY_EXTENSION =
         new WebSocketCloseStatus(1010, "Mandatory extension");
 
     public static final WebSocketCloseStatus INTERNAL_SERVER_ERROR =
         new WebSocketCloseStatus(1011, "Internal server error");
 
     public static final WebSocketCloseStatus SERVICE_RESTART =
         new WebSocketCloseStatus(1012, "Service Restart");
 
     public static final WebSocketCloseStatus TRY_AGAIN_LATER =
         new WebSocketCloseStatus(1013, "Try Again Later");
 
     public static final WebSocketCloseStatus BAD_GATEWAY =
         new WebSocketCloseStatus(1014, "Bad Gateway");
 
     // 1004, 1005, 1006, 1015 are reserved and should never be used by user
     //public static final WebSocketCloseStatus SPECIFIC_MEANING = register(1004, "...");
 
     public static final WebSocketCloseStatus EMPTY =
         new WebSocketCloseStatus(1005, "Empty", false);
 
     public static final WebSocketCloseStatus ABNORMAL_CLOSURE =
         new WebSocketCloseStatus(1006, "Abnormal closure", false);
 
     public static final WebSocketCloseStatus TLS_HANDSHAKE_FAILED =
         new WebSocketCloseStatus(1015, "TLS handshake failed", false);
 
     private final int statusCode;
     private final String reasonText;
     private String text;
 
     public WebSocketCloseStatus(int statusCode, String reasonText) {
         this(statusCode, reasonText, true);
     }
 
     public WebSocketCloseStatus(int statusCode, String reasonText, boolean validate) {
         if (validate && !isValidStatusCode(statusCode)) {
             throw new IllegalArgumentException(
                 "WebSocket close status code does NOT comply with RFC-6455: " + statusCode);
         }
         this.statusCode = statusCode;
         this.reasonText = checkNotNull(reasonText, "reasonText");
     }
 
     public int code() {
         return statusCode;
     }
 
     public String reasonText() {
         return reasonText;
     }
 
     /**
      * Order of {@link WebSocketCloseStatus} only depends on {@link #code()}.
      */
     @Override
     public int compareTo(WebSocketCloseStatus o) {
         return code() - o.code();
     }
 
     /**
      * Equality of {@link WebSocketCloseStatus} only depends on {@link #code()}.
      */
     @Override
     public boolean equals(Object o) {
         if (this == o) {
             return true;
         }
         if (null == o || getClass() != o.getClass()) {
             return false;
         }
 
         WebSocketCloseStatus that = (WebSocketCloseStatus) o;
 
         return statusCode == that.statusCode;
     }
 
     @Override
     public int hashCode() {
         return statusCode;
     }
 
     @Override
     public String toString() {
         String text = this.text;
         if (text == null) {
             // E.g.: "1000 Bye", "1009 Message too big"
             this.text = text = code() + " " + reasonText();
         }
         return text;
     }
 
     public static boolean isValidStatusCode(int code) {
         return code < 0 ||
             1000 <= code && code <= 1003 ||
             1007 <= code && code <= 1014 ||
             3000 <= code;
     }
 
     public static WebSocketCloseStatus valueOf(int code) {
         switch (code) {
             case 1000:
                 return NORMAL_CLOSURE;
             case 1001:
                 return ENDPOINT_UNAVAILABLE;
             case 1002:
                 return PROTOCOL_ERROR;
             case 1003:
                 return INVALID_MESSAGE_TYPE;
             case 1005:
                 return EMPTY;
             case 1006:
                 return ABNORMAL_CLOSURE;
             case 1007:
                 return INVALID_PAYLOAD_DATA;
             case 1008:
                 return POLICY_VIOLATION;
             case 1009:
                 return MESSAGE_TOO_BIG;
             case 1010:
                 return MANDATORY_EXTENSION;
             case 1011:
                 return INTERNAL_SERVER_ERROR;
             case 1012:
                 return SERVICE_RESTART;
             case 1013:
                 return TRY_AGAIN_LATER;
             case 1014:
                 return BAD_GATEWAY;
             case 1015:
                 return TLS_HANDSHAKE_FAILED;
             default:
                 return new WebSocketCloseStatus(code, "Close status #" + code);
         }
     }
 
 }