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}