Websocket Adapter allows two-way (full-duplex) communication and transfer of messages until the connection is terminated between web servers and clients. The microservice connects to the server configured in the component property sheet. Once a connection is created, messages coming to the INPUT_PORT will be sent to the connected server and the messages received from the server will be sent to the OUTPUT_PORT. After sending a message to the server, the "Message sent successfully" message will be sent to the STATUS_PORT. The Message event takes place usually when the server sends some data. Messages sent by the server to the client can include plain text messages. After the connection is successful, whenever the server sends data, the message will be received by the output port.
Component Configuration
Configuration attributes in the Websocket Configuration Property Sheet (CPS) are explained below.
Figure 1: WebSocket CPS Component Configuration panel
Error Handling Configuration
The remedial actions to be taken when a particular error occurs can be configured using this attribute.
Click the ellipsis button against this property to configure Error Handling properties for different types of Errors. By default, the options Log to error logs, Stop service and Send to error port are enabled.
Refer to the Error Handling section in Common Configurations for detailed information.
Connection Configuration
Click the ellipsis button to configure the Connection configuration properties.
Figure 2: Connection Configuration properties
Once a connection has been established between the client and the server, the message configured in the Connection open Message property will be sent to the server. Errors are generated in the event of invalid URLs, or any non-availability of connection during the communication.
Service Provider
Web socket protocol has a schema similar to HTTP defined in its URL pattern. The default value is ws://localhost:8887.
The following image shows the Web Socket URL in tokens.
Figure 3: Web Socket URL elements
In case of a secured connection scheme, provide the schema as "wss" instead of "ws" and SSL configuration has to be enabled in the component as well.
Connection open Message
If a successful connection is made, the message provided here will be sent to the server. This can be used to send an initial request to the server for registration.
Click the button on the right side to configure the same.
Figure 4: Sample message for Connection open Message
Use Connection Details From Input
Enable this option to enable sending connection details in the input.
If this option is disabled, it is mandatory to provide the Service Provider URL in the Connection Configuration.
Connect Timeout
Connects this socket to the server with a mentioned timeout value (in milliseconds). A timeout of zero is interpreted as an infinite timeout. The connection will then block until established or an error occurs.
Enable Ping Mechanism
Enable this property to configure Ping Expiry Timeout.
Ping Expire Timeout
If the amount of time the client waits for the ping from the server exceeds the time specified here, then the message gets discarded.
Figure 5: Ping Mechanism enabled with the default timeout value
SSL Security
Please refer to the following sections to configure SSL Settings:
- Configuring SSL Settings
- SSL Security section in the Common Configurations page.
Expert Properties
Enable the Expert Properties view to configure these properties.
Figure 6: WebSocket CPS with the Expert Properties enabled
Pre Processing XSL Configuration
Pre Processing XSL configuration can be used to transform request message before processing it. Click the ellipses button against the property to configure the properties.
Refer to the Pre/Post Processing XSL Configuration section under the Common Configurations page for details regarding Pre Processing XSL configuration and Post Processing XSL configuration (below).
Post Processing XSL Configuration
Post Processing XSL configuration can be used to transform the response message before sending it to the output port.
Process Message Based on Property
The property helps components to skip certain messages from processing.
Refer to the Process Message Based On a Property section under the Common Configurations page.
Threadpool Configuration
This property is used when there is a need to process messages in parallel within the component, still maintaining the sequence from the external perspective.
Refer to the Threadpool Configuration section under the Common Configurations page.
Message Type Configuration
There are 3 connection parameter elements along with Input message element enabled in the XSD for Websocket input by default.
Figure 7: Schema with 3 connection parameters
Functional Demonstration
Scenario 1 - Multiple clients connecting to the same server
Prerequisite: Start Non- SSL Server
The following sample flow has two WebSocket microservices, both act as clients connected to the same server using the URL "ws://localhost:8887". Upon successful connection, the message mentioned in the CPS will be sent to the server. After receiving requests from the client, the server will broadcast the message to all the connected clients which will be sent to the respective output ports as shown in the display window.
Figure 8: Event Process for multiple clients connecting to the same server
Figure 9: Connection open message for Client One in the CPS
Figure 10: Connection open message for Client two in the CPS
Figure 11: Sending message from Feeder1
Figure 12: Sending message from Feeder2
Figure 13: Acknowledgement message from Client1 displayed in Display1
Figure 14: Messages from Client1 displayed in Display2
Figure 15: Acknowledgement message from Client2 displayed in Display3
Figure 16: Messages from Client2 displayed in Display4
Scenario 2 - Enabling Ping mechanism
In this scenario, when Ping Mechanism is enabled, if the ping is not received between the client and the server until the time mentioned in the 'Ping Expire Timeout' property, the message sent by the client will get discarded after the timeout.
Figure 17: Enabling Ping Mechanism in the CPS
Enable Error port in the event process by clicking the button in the eStudio and connect a Display microservice to the Error port display the error message. The error message can be found in the logs too.
Figure 18: Event Process demonstrating Ping Mechanism
Figure 19: Message in the Display window
Figure 20: Error message highlighted in the Display window after scrolling to the right
Scenario 3 - Based on Input Parameters
Configure an event process with one feeder and two displays connected to a WebSocket and then repeat the same to have one more similar flow as shown in the figure below. Other conditions are mentioned in the respective sections below.
Figure 21: Event process for Scenario 3
If the Action element is entered as “create”
Create action is used to initialize new connection if not present or can be used to recreate a new websocket tunnel if already a websocket connection exists.
- Provide the Service Provider as the Websocket service provider URL.
- Connection Open Message can be configured to provide the required connection message on the creation of the socket connection.
The input message represents the message to be sent in the socket.
Figure 22: XML text in the Feeder window with Action element as “create” to establish a connection
Figure 23: Message in the Display window indicating that a connection is established
If the Action element is entered as “close”
The existing WebSocket connection is closed with a message saying that it left the chat room.
Figure 24: XML text in the Feeder window with Action element as “close” to initiate a new connection
Figure 25: Message in the Display window indicating that a new connection is established
If No Action is provided
- If a connection does not exist and no action is provided, then it is prone to errors.
- If a connection exists and no action is provided, then the older socket connection is used to send the input message.
Figure 26: XML text in the Feeder window without Action and Connection Properties
Figure 27: Message in the Display window indicating that a connection is established