package com.foundation.web.interfaces;

/**
 * The context object available to the web application where connection related data can be stored and released within the context of a single connection between the client and server.
 * Used to store data related to a single socket between the web browser and web server, such as a socket to a service that the server needs in order to service the client's requests.
 * The data will be given an opportunity to be cleaned up upon the socket's closure if it implements com.foundation.web.interfaces.ISessionLifecycleAware.
 */
public interface IConnectionContext {
/**
 * Gets the application data in the connection context's application data map by the given key.
 * This is connection specific data, not client specific data which should be stored in the session.
 * <br/>Warning: Websocket connections are multi threaded and as such, threads must synchronize before calling this method.
 * @return The application specific data element.
 */
public Object getApplicationData(String key);
/**
 * Stores the application data in the connection context's application data map by the given key.
 * The applicationData may implement ISessionLifecycleAware (ignore that this is not a session) if it should be called when the connection is being closed.
 * This is connection specific data, not client specific data which should be stored in the session.
 * <br/>Warning: Websocket connections are multi threaded and as such, threads must synchronize before calling this method.
 * @param key The key for the data.  If the key is logically equal (equivalent) to an existing key, then the existing data will be replaced and returned.
 * @param applicationData The application specific data element.
 */
public void setApplicationData(String key, Object applicationData);
/**
 * Upgrades the connection context to be a HTML5 websocket using the given optional protocol.
 * @param protocol The optional protocol which will be passed to the application when frames are received.
 * @param maxMessageLength The maximum number of bytes in an allowed websocket message (may be composed of multiple frames, does not include the frame header sizes).
 * @param websocketHandler The application provided handler of websocket messages.
 */
public void upgradeToWebsocket(String protocol, long maxMessageLength, WebsocketHandler websocketHandler);
/**
 * Sends the message to the client if this connection has been upgraded to a websocket.
 * <br/>The call is ignored if this is not a websocket.
 * <br/>This is a thread safe call.
 * @param message The message.  The message will be queued for sending and the call will return immediately.
 */
public void sendWebsocketMessage(byte[] message);
/**
 * Sends the message to the client if this connection has been upgraded to a websocket.
 * <br/>The call is ignored if this is not a websocket.
 * <br/>This is a thread safe call.
 * @param message The message.  The message will be queued for sending and the call will return immediately.
 */
public void sendWebsocketMessage(String message);
/**
 * Sends the message to the client if this connection has been upgraded to a websocket.
 * <br/>The call is ignored if this is not a websocket.
 * <br/>This is a thread safe call.
 * @param message The message.  The message will be queued for sending and the call will return immediately.
 */
public void sendWebsocketMessage(IStreamedWebsocketMessage message);
/**
 * Sends the PING message to the client if this connection has been upgraded to a websocket.
 * <br/>The call is ignored if this is not a websocket.
 * <br/>This is a thread safe call.
 */
public void sendWebsocketPing();
/**
 * Gets the protocol associated with this websocket.
 * @return The optional protocol associated with the connection context when it was upgraded to a websocket, or null if this context was never upgraded.
 */
public String getWebsocketProtocol();
/**
 * Determines whether this connection context has been upgraded to a websocket.
 * @return Whether this is a websocket connection.
 */
public boolean isWebsocket();
}//IConnectionContext//