Package com.facilita.fc.web

Class WebSocket

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public class WebSocket
extends java.lang.Object
implements java.lang.AutoCloseable
    Represents a WebSocket

    A WebSocket object is created by calling WebBrowser.createWebSocket(Url, int). The WebSocket can then be opened by calling the open() method. Once the WebSocket has been opened, then messages can be sent to the server using the sendMessage(String) method. Messages arriving from the server can be processed by registering a callback by calling the registerReceivedMessageCallback(WebSocketReceivedMessageCallback) method.

    The following example demonstrates creating and opening a WebSocket: 

    
 Url url = new Url("ws://echo.websocket.org/");
 WebSocket webSocket = getWebBrowser().createWebSocket(url, 1);
 webSocket.open();

    • Constructor Summary

      Constructors 
      Constructor Description
      WebSocket​(long cPtr, boolean cMemoryOwn)
      For internal use only.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clearHeaders()
      Clears the list of HTTP headers for this WebSocket.
      void close()
      (non-Javadoc)
      void close​(java.lang.String reason)
      Closes the WebSocket.
      boolean containsHeader​(java.lang.String header)
      Determines whether this WebSocket contains a particular HTTP header.
      void delete()  
      java.lang.String getContentType()
      Gets the value of the "Content-Type" HTTP header.
      static long getCPtr​(WebSocket obj)
      For internal use only.
      java.util.List<java.lang.String> getHeaderKeys()
      Gets a list of names of all the HTTP request headers set in this Request.
      java.lang.String getHeaderValue​(java.lang.String header)
      Gets the value of the specified HTTP request header.
      int getID()
      Gets the unique ID that has been assigned to this WebSocket.
      java.lang.String getReferer()
      Gets the value of the "Referer" HTTP header.
      Url getUrl()
      Gets the Url that this WebSocket is targeting.
      java.lang.String getUserAgent()
      Gets the value of the "User-Agent" HTTP header.
      WebBrowserVirtualUser getVU()
      Gets the VirtualUser instance that this WebSocket is associated with.
      boolean hasReferer()
      Gets a value that indicates whether the "Referer" HTTP header has been set for this Request.
      void open()
      Opens the WebSocket.
      void registerClosedCallback​(WebSocketClosedCallback callback)
      Register a callback to be invoked when the WebSocket is closed.
      void registerErrorCallback​(WebSocketErrorCallback callback)
      Register a callback to be invoked when an error occurs on the WebSocket.
      void registerReceivedMessageCallback​(WebSocketReceivedMessageCallback callback)
      Register a callback to be invoked when a message is received from the server.
      void removeHeader​(java.lang.String header)
      Removes an HTTP header from this WebSocket.
      void sendMessage​(byte[] data)
      Send a binary message to the server.
      void sendMessage​(byte[] data, boolean isBinary)
      Send a message to the server.
      void sendMessage​(WebSocketMessage message)
      Send a message to the server.
      void sendMessage​(java.lang.String text)
      Send a text message to the server.
      void sendMessageFromFile​(java.lang.String path, boolean isBinary)
      Send a message to the server, by loading the message data from a file.
      void sendMessageFromFile​(java.lang.String path, boolean isBinary, int chunkSize)
      Send a message to the server, by loading the message data from a file.
      void setContentType​(java.lang.String contentType)
      Sets the value of the "Content-Type" HTTP header.
      void setHeader​(java.lang.String header)
      Sets an HTTP header to use in the opening handshake request for this WebSocket, using the contents of the specified string.
      void setHeader​(java.lang.String header, java.lang.String value)
      Sets an HTTP header to use in the opening handshake request for this WebSocket, as a name/value pair.
      void setReferer​(Url url)
      Sets the value of the "Referer" HTTP header.
      void setReferer​(java.lang.String referer)
      Sets the value of the "Referer" HTTP header.
      void setUrl​(Url url)
      Sets the Url that this WebSocket is targeting.
      void setUserAgent​(java.lang.String userAgent)
      Sets the value of the "User-Agent" HTTP header.
      void setVU​(WebBrowserVirtualUser vu)
      Sets the VirtualUser instance that this WebSocket is associated with.
      void unsetReferer()
      Removes the "Referer" HTTP header.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • WebSocket

        public WebSocket​(long cPtr,
                 boolean cMemoryOwn)
        For internal use only. Of no interest to the user.
        Parameters:
        cPtr - Pointer to the CPP wrapped object.
        cMemoryOwn - Indicates if this object is responsible for memory management of the CPP object.

    • Method Detail

      • getCPtr

        public static long getCPtr​(WebSocket obj)
        For internal use only. Of no interest to the user.
        Parameters:
        obj - A reference to an object of this class.
        Returns:
        A long containing the address of the CPP wrapped object.

      • delete

        public void delete()

      • close

        public void close()
           throws java.lang.Exception
        (non-Javadoc)
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.lang.Exception
        See Also:
        AutoCloseable.close()

      • sendMessage

        public void sendMessage​(java.lang.String text)
        Send a text message to the server.

        The WebSocket must be opened, by calling the open() method, before any messages can be sent to the server. The text will be encoded as UTF-8 before being sent to the server.

        Parameters:
        text - The message to send
        See Also:
        sendMessage(byte[], boolean), open()

      • sendMessage

        public void sendMessage​(byte[] data,
                        boolean isBinary)
        Send a message to the server.

        The WebSocket must be opened, by calling the open() method, before any messages can be sent to the server.

        Parameters:
        data - The data to send to the server
        isBinary - If set to true, then the message will be flagged as binary data. Otherwise, it will be flagged as text.
        See Also:
        sendMessage(String), open()

      • sendMessage

        public void sendMessage​(byte[] data)
        Send a binary message to the server.

        The WebSocket must be opened, by calling the open() method, before any messages can be sent to the server.

        Parameters:
        data - The data to send to the server
        See Also:
        sendMessage(String), open()

      • registerReceivedMessageCallback

        public void registerReceivedMessageCallback​(WebSocketReceivedMessageCallback callback)
        Register a callback to be invoked when a message is received from the server.

        Once the WebSocket has been opened, the server may send messages at any time. A callback registered with this method is called whenever a message arrives from the server. Note that the method will be called on a different thread to the thread that opened the WebSocket.

        Parameters:
        callback - The instance of WebSocketReceivedMessageCallback that will be called when messages arrive from the server.

      • registerClosedCallback

        public void registerClosedCallback​(WebSocketClosedCallback callback)
        Register a callback to be invoked when the WebSocket is closed.

        Note that the WebSocket close may be triggered by either the client or the server.

        Parameters:
        callback - The instance of WebSocketClosedCallback that will be called when the WebSocket is closed.
        See Also:
        close(String)

      • registerErrorCallback

        public void registerErrorCallback​(WebSocketErrorCallback callback)
        Register a callback to be invoked when an error occurs on the WebSocket.

        An error could occur during sending, receiving, or closing of the WebSocket.

        Parameters:
        callback - The instance of WebSocketErrorCallback that will be called when an error occurs.

      • open

        public void open()
        Opens the WebSocket.

        Opens the WebSocket by performing the opening handshake. The opening handshake is an HTTP Upgrade request. If the handshake is successful, then the server will respond with a 101 Switching Protocols HTTP response.

        See Also:
        close(String)

      • close

        public void close​(java.lang.String reason)
        Closes the WebSocket.
        Parameters:
        reason - The reason for closing the websocket to send to the server
        See Also:
        open()

      • sendMessageFromFile

        public void sendMessageFromFile​(java.lang.String path,
                                boolean isBinary,
                                int chunkSize)
        Send a message to the server, by loading the message data from a file.

        The WebSocket must be opened, by calling the open() method, before any messages can be sent to the server.

        If you are using this method in your script, make sure that the file containing the data is in the data/Files directory within your project.

        Parameters:
        path - The path of the filename, relative to the Virtual User's data directory.
        isBinary - If set to true, then the message will be flagged as binary data. Otherwise, it will be flagged as text.
        chunkSize - The number of bytes to send at a time.
        See Also:
        sendMessage(String), open()

      • sendMessageFromFile

        public void sendMessageFromFile​(java.lang.String path,
                                boolean isBinary)
        Send a message to the server, by loading the message data from a file.

        The WebSocket must be opened, by calling the open() method, before any messages can be sent to the server.

        If you are using this method in your script, make sure that the file containing the data is in the data/Files directory within your project. 4096 bytes will be sent to the server at a time. If you want to use a different chunk size, then use the sendMessageFromFile(String, boolean, int) overload.

        Parameters:
        path - The path of the filename, relative to the Virtual User's data directory.
        isBinary - If set to true, then the message will be flagged as binary data. Otherwise, it will be flagged as text.
        See Also:
        sendMessage(String), open()

      • getID

        public int getID()
        Gets the unique ID that has been assigned to this WebSocket.
        Returns:
        This ID number is created by the WebBrowser. It is the value that is displayed in the web log viewer.

      • setHeader

        public void setHeader​(java.lang.String header,
                      java.lang.String value)
        Sets an HTTP header to use in the opening handshake request for this WebSocket, as a name/value pair.

        The header will be sent to the web server when this WebSocket is opened.

        The following example demonstrates setting the "X-Requested-With" header on the request. 

        
 webSocket.setHeader("X-Requested-With", "XMLHttpRequest");
        Parameters:
        header - The header to set.
        value - The value to assign to the header.
        See Also:
        removeHeader(String), clearHeaders()

      • setHeader

        public void setHeader​(java.lang.String header)
        Sets an HTTP header to use in the opening handshake request for this WebSocket, using the contents of the specified string.

        The header will be sent to the web server when this WebSocket is opened. The following example demonstrates setting the "X-Requested-With" header on the request. 

        
 webSocket.setHeader("X-Requested-With: XMLHttpRequest");
        Parameters:
        header - The header to set, including the value, which should be separated from the name with a colon.
        See Also:
        removeHeader(String), clearHeaders()

      • removeHeader

        public void removeHeader​(java.lang.String header)
        Removes an HTTP header from this WebSocket.
        Parameters:
        header - The header to remove.
        See Also:
        setHeader(String, String), clearHeaders()

      • setReferer

        public void setReferer​(Url url)
        Sets the value of the "Referer" HTTP header.
        Parameters:
        url - The value to set.
        See Also:
        getReferer()

      • setUserAgent

        public void setUserAgent​(java.lang.String userAgent)
        Sets the value of the "User-Agent" HTTP header.
        Parameters:
        userAgent - The value of the "User-Agent" HTTP header.
        See Also:
        getUserAgent()

      • setReferer

        public void setReferer​(java.lang.String referer)
        Sets the value of the "Referer" HTTP header.
        Parameters:
        referer - The value to set.
        See Also:
        getReferer()

      • setContentType

        public void setContentType​(java.lang.String contentType)
        Sets the value of the "Content-Type" HTTP header.
        Parameters:
        contentType - The value of the "Content-Type" HTTP header.
        See Also:
        getContentType()

      • unsetReferer

        public void unsetReferer()
        Removes the "Referer" HTTP header.

      • containsHeader

        public boolean containsHeader​(java.lang.String header)
        Determines whether this WebSocket contains a particular HTTP header. The following example demonstrates getting the "Content-Type" header of a WebSocket request. 
        
 if (webSocket.containsHeader("Content-Type"))
 {
     writeMessage(String.format("Content-Type=%s", webSocket.getHeaderValue("Content-Type")));
 }
        Parameters:
        header - The HTTP header to check for.
        Returns:
        true if this WebSocket contains the specified header; otherwise, false.

      • getHeaderValue

        public java.lang.String getHeaderValue​(java.lang.String header)
        Gets the value of the specified HTTP request header.
        Parameters:
        header - The header to get the value of.
        Returns:
        The value of the header.
        See Also:
        setHeader(String, String), removeHeader(String)

      • getUserAgent

        public java.lang.String getUserAgent()
        Gets the value of the "User-Agent" HTTP header.
        Returns:
        the value of the "User-Agent" HTTP header.

      • getReferer

        public java.lang.String getReferer()
        Gets the value of the "Referer" HTTP header.
        Returns:
        the value of the "Referer" HTTP header.

      • hasReferer

        public boolean hasReferer()
        Gets a value that indicates whether the "Referer" HTTP header has been set for this Request.
        Returns:
        true if the "Referer" header has been set; otherwise, false.

      • getContentType

        public java.lang.String getContentType()
        Gets the value of the "Content-Type" HTTP header.
        Returns:
        the value of the "Content-Type" HTTP header.

      • getHeaderKeys

        public java.util.List<java.lang.String> getHeaderKeys()
                                               throws com.facilita.exception.InternalError
        Gets a list of names of all the HTTP request headers set in this Request.
        Returns:
        A list of names of all the HTTP request headers set in this Request.
        Throws:
        com.facilita.exception.InternalError - An error occurred