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 the 'Create Socket?' property is enabled. In the Server mode, this microservice creates 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 the output port.
• Client
  Acts as a client if the 'Create Socket ?' property is disabled. In the Client mode, this microservice connects 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 need 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.

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.
  • makes the following properties property available for configuration:
    • Block Clients 
    • Close Idle Connections
    • Session Limit

• 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

Sending Message Type

Mode of the message transfer while sending a message is classified as below:

• Text Message: Messages will be encoded as string.
• Byte Message: Messages will be encoded as bytes.

Figure 3: Message Type options

Receiving Message Type

Mode of the message transfer while receiving a message is classified as below:

• Text Message: Messages will be decoded as string.
• Byte Message: Messages will be decoded as bytes.

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 decoding type

Delimiter

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

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.

Include Delimiter in the received message

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. While decoding messages based on the delimiter, if a delimiter is not received till this length, then a BufferDataException will occur.

Length decoding type

If enabled, messages will be decoded based on the length of the message.

Message Length (bytes)

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

This property is given by the 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.

ISO decoding type

Message Length Numeric Type 

This property specifies the numeric type in which the total message length is present in the message.

Numeric types available are:

• Hexadecimal
• Decimal
• Bytes

The Message Length Numeric Type is set to 'Decimal' by default.

No of Chars in Message Length Field

This property specifies the number of characters to be present in the ISO message length field.

Includes Header Length

Select this property if the Header length (in bytes) needs to be included in the input message.

Write Timeout for Session (milliseconds)

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.

Enable SSL?

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

Figure 7: SSL Configuration

Encoding Charset

The Charset, such as UTF-8, used while encoding the message.

Decoding Charset

The Charset, such as UTF-8, used while decoding the message.

Is synchronous?

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. 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 6: Synchronous Communication options

Suspend Timeout (milli seconds)

If the message sent by a client takes more time than the Suspend Timeout to execute, then the next message is sent.

Is SSH Enabled?

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

SSH Password

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

Is KeyPair Needed

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.

Key Pair Path

Key pair should be provided at runtime 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.

Figure 8: CPS with SSH and Key Pair properties enabled

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. 

Click the Threadpool Configuration ellipsis button to configure the Threadpool Configuration properties.

Figure 9: Threadpool Configuration dialog box

Enable Thread Pool

Enable this option to configure the properties that appear as below.

Pool Size

Number of requests to be processed in parallel within the component. Default value is '1'.

Batch Eviction Interval (in ms)

Time in milliseconds after which the threads are evicted in case of inactivity. New threads are created in place of evicted threads when new requests are received. Default value is '1000'.

Block Clients ?

This property will be visible in the CPS only if the Create Socket property is enabled and hence is displayed only on the server side. This property is used to deny access to a particular client or a set of clients as specified using the IP addresses.

When this property is enabled, Blocked Clients IP Pattern property gets visible where the IP pattern referring to the clients who need to be blocked can be specified.

Blocked Clients IP Pattern

Provide the IP address or a range of IP addresses to deny access to a particular client or multiple clients respectively.

Figure 10: Attributes to specify the IP address(es) to be blocked

Close Idle Connections

When the Close idle connections check box is enabled, it acts as a server and closes inactive client connections based on the idle time which can be set for a session of connection specified in milliseconds.

Idle time (ms)

Idle time is the maximum time interval for the client to not to send a request to the server. If the time taken to send the request from the client is more than the idle time, the session is closed. A new session gets created only when the client is sending another request.

Figure 11: Attributes to specify the Idle time

Session Limit

The number of active sessions connecting to the server; it restricts to the number that is specified. The default value is "0" which indicates that the server has no limit in creating sessions.

Send error message when session is closed?

Enable this property to send a message from the error port stating that the session is closed because of a server failure or a server disconnection. This property helps to get notified that the session is destroyed between the server and the client.

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 12: Sample Event Process

Scenario 1: Decoding Type as 'Delimiter'

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

Figure 13: Socket Adapter Configuration in Server mode

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

Figure 14: Socket Adapter Configuration in Client mode

Scenario 2: Decoding Type as 'Length'

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

Figure 15: Socket Adapter Configuration in Server mode

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

Figure 16: Socket Adapter Configuration in Client mode

Scenario 3: Decoding Type as 'None'

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

Scenario 4: Decoding Type as 'Delimiter' in Synchronous mode

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

Figure 17: Socket Adapter Configuration in Server mode

'SampleClient' Component Configuration with the Is Synchronous property enabled as shown in the following figure.

Figure 18: Socket Adapter Configuration in Client mode

Synchronous Use Case

The following Sample flow has one socket adapter acting as a 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 a response within the configured suspendtimeout (10 sec), then the next request message sent by the client will be processed and a timeout error message is sent to the Error port of the client.

Figure 19: Sample Event Process

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

Figure 21: Sample Request

Figure 22: Sample Response

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.