001/* 002 * Copyright (C) 2015-2016 Neo Visionaries Inc. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package NeoVisionaries.WebSockets; 017 018 019/** 020 * WebSocket state. 021 * 022 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE><BR /> 023 * 024 * <p> 025 * The initial state of a {@link WebSocket} instance is 026 * <b><code>CREATED</code></b>. {@code WebSocket.}{@link 027 * WebSocket#connect() connect()} method is allowed to be called 028 * only when the state is {@code CREATED}. If the method is called 029 * when the state is not {@code CREATED}, a {@link WebSocketException} 030 * is thrown (its error code is {@link WebSocketError#NOT_IN_CREATED_STATE 031 * NOT_IN_CREATED_STATE}). 032 * </p> 033 * 034 * <p> 035 * At the beginning of the implementation of {@code connect()} method, 036 * the state is changed to <b><code>CONNECTING</code></b>, and then 037 * {@link WebSocketListener#onStateChanged(WebSocket, WebSocketState) 038 * onStateChanged()} method of each registered listener ({@link 039 * WebSocketListener}) is called. 040 * </p> 041 * 042 * <p> 043 * After the state is changed to {@code CONNECTING}, a WebSocket 044 * <a href="https://tools.ietf.org/html/rfc6455#section-4">opening 045 * handshake</a> is performed. If an error occurred during the 046 * handshake, the state is changed to {@code CLOSED} ({@code 047 * onStateChanged()} method of listeners is called) and a {@code 048 * WebSocketException} is thrown. There are various reasons for 049 * handshake failure. If you want to know the reason, get the error 050 * code ({@link WebSocketError}) by calling {@link 051 * WebSocketException#getError() getError()} method of the exception. 052 * </p> 053 * 054 * <p> 055 * After the opening handshake succeeded, the state is changed to 056 * <b><code>OPEN</code></b>. Listeners' {@code onStateChanged()} method 057 * and {@link WebSocketListener#onConnected(WebSocket, java.util.Map) 058 * onConnected()} method are called in this order. Note that {@code 059 * onConnected()} method is called by another thread. 060 * </p> 061 * 062 * <p> 063 * Upon either sending or receiving a <a href= 064 * "https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>, 065 * a <a href="https://tools.ietf.org/html/rfc6455#section-7">closing 066 * handshake</a> is started. The state is changed to 067 * <b><code>CLOSING</code></b> and {@code onStateChanged()} method of 068 * listeners is called. 069 * </p> 070 * 071 * <p> 072 * After the client and the server have exchanged close frames, the 073 * state is changed to <b><code>CLOSED</code></b>. Listeners' 074 * {@code onStateChanged()} method and {@link 075 * WebSocketListener#onDisconnected(WebSocket, WebSocketFrame, 076 * WebSocketFrame, boolean) onDisconnected()} method is called in 077 * this order. 078 * </p> 079 */ 080public enum WebSocketState 081{ 082 /** 083 * The initial state of a {@link WebSocket} instance. 084 */ 085 CREATED, 086 087 088 /** 089 * An <a href="https://tools.ietf.org/html/rfc6455#section-4">opening 090 * handshake</a> is being performed. 091 */ 092 CONNECTING, 093 094 095 /** 096 * The WebSocket connection is established (= the <a href= 097 * "https://tools.ietf.org/html/rfc6455#section-4">opening handshake</a> 098 * has succeeded) and usable. 099 */ 100 OPEN, 101 102 103 /** 104 * A <a href="https://tools.ietf.org/html/rfc6455#section-7">closing 105 * handshake</a> is being performed. 106 */ 107 CLOSING, 108 109 110 /** 111 * The WebSocket connection is closed. 112 */ 113 CLOSED 114}