Socket Adapter can be used in sending data to sockets and receiving data from sockets. This adapter will have two modes of operation.

Server
Acts as a server if 'Create Socket?' property is set to true. In server mode adapter will create a socket on the configured port provided in the component property sheet and listens for connections. Once a connection is created, messages coming on the input port will be sent to the connected client/clients and the messages received from the client will be sent to output port.
Client
Acts as a client if 'Create Socket ?' property is set to false. In client mode adapter will connect to the socket configured. If a successful connection is made then the message coming on the input port will be sent to the server and the received messages will be sent to the output port.

Configuration

Component Configuration

Configuration attributes in the SocketAdapter Configuration Property Sheet (CPS) with Expert Properties enabled are explained below.

Figure 1: SocketAdapter Configuration CPS

Error handling configuration

The actions that needs 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.

Icon

Refer Error Handling section in Common Configurations for detailed information.

CreateSocket?

Enable - Acts as a server by creating a socket on the specified port and listens to client connections.

Icon

Enabling this property disables the properties Connection Idle Timeout and Is Synchronous? too.
Disable - Acts as a client assuming that the server is already running on the specified port and connects to it.

Connection Configuration

Click the ellipsis button to configure the properties as below.

Server IP: IP address of the socket
Port: Port of the socket

Figure 2: Connection Configuration dialog box

MessageType

Mode of the message transfer classified as below:

TextMessage: Messages will be encoded and decoded as Strings.
ByteMessage: Messages will be encoded and decoded as bytes.

Figure 3: Message Type options

Icon

Sending Message Type and Receiving Message Type are the two Messages Types t be configured for the messages that you send and receive respectively.

DecodingType

Messages received in the communication will be decoded in the following ways.

- Delimiter: Messages are decoded based on the delimiter configured.
- Length: Messages are decoded based on the length of the message.
- None: All the messages present in the stream are fetched.
- ISO: Messages are decoded based on the ISO standards.

Delimiter

Delimiter is to be used as an end of the message.

Icon

Hexadecimal Delimiters can also be used. For hexadecimal delimiter, it should start with "0x" . For example, if you want to use "1F" as hexadecimal delimiter, then provide delimiter as "0x1F"

Icon

This message gets enabled only when the Decoding Type property value is 'Delimiter'.

Append Delimiter while sending message

If enabled, delimiter provided in the configuration will be appended to the input message before sending it to the socket.

Icon

In a simple Client-Server Socket scenerio, the Append Delimiter while sending message property should be enabled. As the message received at the input port of Server does not contain delimiter (message is processed based on client configuration, based on delimiter), this property appends the delimiter to the message on the input port of Server.

Include Delimiter in the received message

This property is visible only when Decoding type is Delimiter Based. Upon decoding the received data from the socket, messages will be sent to the output port with the delimiter included in it.

Maximum Message Length (bytes)

Length of the largest message in the messages that are expected to receive. This property is visible only when Decoding type is Delimiter Based. While decoding messages based on delimiter if a delimiter is not received till this length then a BufferDataException will occur.

Icon

Instead of waiting forever to match a delimiter, this property helps if a receiving stream is invalid or corrupted.
Specify a larger value if the length of the receiving messages is unknown.

MessageLength(bytes)

This property specifies the length of the message in case of Length Based decoding.

Icon

This property is visible only when the property Decoding Type is set to Length Based.

Figure 4: Length decoding typ option

This property is given by number of bytes. For the Message Type' 'Text', for UTF-8 charset:1 char is 1 byte;for UTF-16 charset: 1 char is 2 bytes.

Write Timeout for Session (milli seconds)

Session expires if a write operation (while sending messages to socket) exceeds the value of time provided for this property.

Connection Idle Timeout

The actual time taken to close the idle connections will be between the configured time and double that time. The default value is 240000 milliseconds.

IsSynchronous?

Synchronous communication happens between a client and the server. Messages from the client are sent to the server till the client receives a response and if no response is received from the server till the given Suspend Timeout (gets visible when this property is enabled), then a timeout message is sent to the exception port and the next request is processed.

Figure 5: Synchronous Communication options

Icon

This property is enabled for Client only.
It is visible only when Create Socket ? property is disabled, for Client.

Suspend Timeout (milli seconds)

If the message send by client takes more time than suspend timeout to execute, then the next message is sent.

Icon

This property is visible only when IsSynchronous? property is disabled, for Client.

Enable SSL?

By enabling SSL and providing the required key store/trust store with respective passwords, secure message transfer can be achieved.

Figure 6: SSL Configuration

IsSSHEnabled?

If Enabled, the communication will take place through a secured channel; only if the server authenticates itself to the client through Key Pair and the client authenticates to the server using an SSH login name and password.

SSH login username

User Name for the SSH Session, used by the client to authenticate itself to the server

SSHPassword

Password for the SSH Session, used by the client to authenticate itself to the server

IsKeyPairNeeded

This is a property present at the Client side. If enabled, it specifies that the client needs to communicate with the server authenticated by a specified Key Pair. If disabled, the client will accept any server key pairs.

KeyPairPath

Key pair should be provided at run time by the user at both client side and the server side for proper authentication. A key pair in ".pem" format is required by the SSH library to perform the key exchange and verification.

Icon

Steps to generate a .pem key can be found in the link http://grahamc.com/blog/openssl-madness-how-to-create-keys-certificate-signing-requests-authorities-and-pem-files/.
The path of the key must be provided in CPS at both server side and client side. Generally, RSA Algorithm is used to generate .pem key.

Figure 7: CPS with SSH and Key Pair properties enabled

Functional Demonstration

The following Sample flow has two socket microservices, one acting as the server and the other as client. After receiving requests from the client, the server will send it to the SMTP component connected to its output port, and then the response from the SMTP component is, in turn, sent back to the client.

Figure 8: Sample Event Process

Scenario 1: Decode Type as 'Delimiter'

'SampleServer' Component Configuration is shown in the following figure.

Figure 9: Socket Adapter Configuration in Server mode

'SampleClient' Component Configuration is shown in the following figure.

Figure 10: Socket Adapter Configuration in Client mode

Scenario 2: Decode Type as 'Length'

'SampleServer' Component Configuration is shown in the following figure.

Figure 11: Socket Adapter Configuration in Server mode

'SampleClient' Component Configuration is shown in the following figure.

Figure 12: Socket Adapter Configuration in Client mode

Scenario 3: Decode Type as 'None'

In this case, whatever message is sent to the 'SampleServer', will be received by the 'SampleClient'.

Synchronous Use Case

The following Sample flow has one socket adapter acting as client. After receiving requests from the client, the configured WSSStub (as Server) sends the response back to the client. In the client configuration, SuspendTimeout is 10 sec. If the client fails to receive response within the configured suspendtimeout (10 sec), then the next request message sent by client will be processed and a timeout error message is sent to the Error port of the client.

Figure 13: Sample Event Process

Figure 14: Socket Adapter Configuration in Client mode for Synchronous Communication

Figure 15: Sample Request

Figure 16: Sample Response

Icon

Is Synchronous? option can be used with any Decode Type (Delimiter/ Length/None).

Useful Tips

In the Delimiter-based decoding, instead of waiting forever to match a delimiter, the Maximum Message Length property helps if the stream being received is invalid or corrupted.
Specify a larger value if the length of the receiving messages is unknown.

Icon

To understand the service better, refer the Socket Read/Write example which demonstrates SocketAdapter service features.