/*
 * Copyright (c) 2010 The Netty Project
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.http;

import io.vertx.codegen.annotations.CacheReturn;
import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.ServiceHelper;
import io.vertx.core.buffer.Buffer;
import io.vertx.core.spi.WebSocketFrameFactory;

A WebSocket frame that represents either text or binary data.

A WebSocket message is composed of one or more WebSocket frames.

If there is a just a single frame in the message then a single text or binary frame should be created with final = true.

If there are more than one frames in the message, then the first frame should be a text or binary frame with
final = false, followed by one or more continuation frames. The last continuation frame should have final = true.
Author:
The Netty Project, Trustin Lee, Tim Fox
Version:
$Rev: 2080 $, $Date: 2010-01-26 18:04:19 +0900 (Tue, 26 Jan 2010) $/**
 * A WebSocket frame that represents either text or binary data.
 * <p>
 * A WebSocket message is composed of one or more WebSocket frames.
 * <p>
 * If there is a just a single frame in the message then a single text or binary frame should be created with final = true.
 * <p>
 * If there are more than one frames in the message, then the first frame should be a text or binary frame with
 * final = false, followed by one or more continuation frames. The last continuation frame should have final = true.
 *
 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
 * @author <a href="http://gleamynode.net/">Trustin Lee</a>
 * @author <a href="http://tfox.org">Tim Fox</a>
 * @version $Rev: 2080 $, $Date: 2010-01-26 18:04:19 +0900 (Tue, 26 Jan 2010) $
 */
@VertxGen
public interface WebSocketFrame {

  
Create a binary WebSocket frame.
Params:
data –  the data for the frame
isFinal –  true if it's the final frame in the WebSocket message
Returns:
the frame/**
   * Create a binary WebSocket frame.
   *
   * @param data  the data for the frame
   * @param isFinal  true if it's the final frame in the WebSocket message
   * @return the frame
   */
  static WebSocketFrame binaryFrame(Buffer data, boolean isFinal) {
    return factory.binaryFrame(data, isFinal);
  }

  
Create a text WebSocket frame.
Params:
str –  the string for the frame
isFinal –  true if it's the final frame in the WebSocket message
Returns:
the frame/**
   * Create a text WebSocket frame.
   *
   * @param str  the string for the frame
   * @param isFinal  true if it's the final frame in the WebSocket message
   * @return the frame
   */
  static WebSocketFrame textFrame(String str, boolean isFinal) {
    return factory.textFrame(str, isFinal);
  }

  
Create a ping WebSocket frame.  Will be a final frame. There is no option for non final ping frames.
Params:
data – the bytes for the frame, may be at most 125 bytes
Returns:
the frame/**
   * Create a ping WebSocket frame.  Will be a final frame. There is no option for non final ping frames.
   *
   * @param data the bytes for the frame, may be at most 125 bytes
   * @return the frame
   */
  static WebSocketFrame pingFrame(Buffer data) {
    return factory.pingFrame(data);
  }

  
Create a pong WebSocket frame.  Will be a final frame. There is no option for non final pong frames.
Params:
data – the bytes for the frame, may be at most 125 bytes
Returns:
the frame/**
   * Create a pong WebSocket frame.  Will be a final frame. There is no option for non final pong frames.
   *
   * @param data the bytes for the frame, may be at most 125 bytes
   * @return the frame
   */
  static WebSocketFrame pongFrame(Buffer data) {
    return factory.pongFrame(data);
  }

  
Create a continuation frame
Params:
data –  the data for the frame
isFinal – true if it's the final frame in the WebSocket message
Returns:
the frame/**
   * Create a continuation frame
   *
   * @param data  the data for the frame
   * @param isFinal true if it's the final frame in the WebSocket message
   * @return the frame
   */
  static WebSocketFrame continuationFrame(Buffer data, boolean isFinal) {
    return factory.continuationFrame(data, isFinal);
  }

  
Returns:
true if it's a text frame/**
   * @return true if it's a text frame
   */
  boolean isText();

  
Returns:
true if it's a binary frame/**
   * @return true if it's a binary frame
   */
  boolean isBinary();

  
Returns:
true if it's a continuation frame/**
   * @return true if it's a continuation frame
   */
  boolean isContinuation();

  
Returns:
true if it's close frame/**
   * @return true if it's close frame
   */
  boolean isClose();

  
Returns:
the content of this frame as a UTF-8 string and returns the
converted string. Only use this for text frames./**
   * @return the content of this frame as a UTF-8 string and returns the
   * converted string. Only use this for text frames.
   */
  @CacheReturn
  String textData();

  
Returns:
the data of the frame/**
   * @return the data of the frame
   */
  @CacheReturn
  Buffer binaryData();

  
Returns:
true if this is the final frame./**
   * @return true if this is the final frame.
   */
  boolean isFinal();

  
Returns:
status code of close frame. Only use this for close frames/**
   * @return status code of close frame. Only use this for close frames
   */
  short closeStatusCode();

  
Returns:
string explaining close reason. Only use this for close frames/**
   * @return string explaining close reason. Only use this for close frames
   */
  String closeReason();

  @GenIgnore
  WebSocketFrameFactory factory = ServiceHelper.loadFactory(WebSocketFrameFactory.class);
}