= websocket-client: WebSocket Java Client Example
:author: Paul Cowan
:productName: WildFly
:productNameFull: WildFly Application Server
:jbossHomeName: WILDFLY_HOME
:productVersion: 12
:buildRequirements: Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later
include::../shared-doc/attributes.adoc[]

:level: Intermediate
:technologies: Web Socket, CDI Events, JSON, SSL
:source: {githubRepoUrl}

[abstract]
Demonstrates use of a Javascript WebSocket client, WebSocket configuration, programmatic binding, and secure WebSocket.

:standalone-server-type: default
:archiveType: war

== What is it?

The `websocket-client` quickstart demonstrates how to use the Java API for WebSockets to create Java client endpoint connected to a remote WebSocket server.

The example is modeled as a relay between a front-end WebSocket server endpoint and a back-end WebSocket client endpoint.

Message Flow: +
`Browser Javascript WebSocket Client` -> `{productName} WebSocket Server Endpoint` -> ``{productName} Websocket Client Endpoint` -> `Remote WebSocket Echo Server`

CDI events are used to pass messages between the front-end and back-end servers. A single back-end WebSocket client endpoint is shared for all front-end clients.

The remote WebSocket server must be an `Echo` server; a simple WebSocket server that echos back messages the client sends for the purpose of testing. Such a server is publicly available at ws://echo.websocket.org, but any echo server will work.

`Frontend` does not use WebSocket annotations because it demonstrates how to use `ServerEndpointConfig` to modify the default `Configurator` to use an application scoped Endpoint, and how to deploy the Endpoint programatically.

`Backend` does not use WebSocket annotations because it demonstrates how to use `ClientEndpointConfig` to configure the WebSocket client to connect to a secure (wss) WebSocket.

//*************************************************
// Add System Requirements
//*************************************************
// == System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]

//*************************************************
// Add Use of JBoss Home Name
//*************************************************
// == Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]

//*************************************************
// Start the server with the default profile
//*************************************************
// == Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]

//*************************************************
// Build and deploy the quickstart WAR
//*************************************************
// == Build and Deploy the Quickstart
include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]

== Access the Application

Access the running application in a browser at the following URL: http://localhost:8080/{artifactId}/

You are presented with the `WebSocket Echo Replay` page confirming the connection to the remote WebSocket _Echo_ server.

[source,subs="+quotes,attributes+",options="nowrap"]
----
Connecting to ws://localhost:8080/{artifactId}/relay
RECV: Opened frontend session __FRONTEND_SESSION_ID__
----

Type a message in the text input field at the bottom of the page and click `Send`. The message is processed and the form displays the relayed results. The message `This is a test` was used in the following example.

[source,subs="+quotes,attributes+",options="nowrap"]
----
SEND: This is a test
RECV: BROADCAST: Connecting to backend wss://echo.websocket.org
RECV: BROADCAST: Opened backend session __BACKEND_SESSION_ID__
RECV: Sending message from frontend session __FRONTEND_SESSION_ID__
RECV: Received message from backend session __BACKEND_SESSION_ID__
RECV: This is a test
----


//*************************************************
// Undeploy the quickstart archive
//*************************************************
// == Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]


//*************************************************
// Add JBoss Developer Studio instructions
//*************************************************
// == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse
include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1]

//*************************************************
// Deploy the quickstart to OpenShift
//*************************************************
// == Deploy the Quickstart to OpenShift Online
include::../shared-doc/deploy-to-openshift-online.adoc[leveloffset=+1]


//*************************************************
// Add info to debug the application
//*************************************************
// == Debug the Application
include::../shared-doc/debug-the-application.adoc[leveloffset=+1]
