SocketAdapter

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.

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.

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

  

  Enabling this property

  • disables the properties Connection Idle Timeout and Is Synchronous? too.
  • makes the following properties property available for configuration:
    • (11.0) SocketAdapter#Block Clients 
    • (11.0) SocketAdapter#Close Idle Connections

• 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

Message Type

Mode of the message transfer classified as below:

• Text Message: Messages will be encoded and decoded as Strings.
• Byte Message: Messages will be encoded and decoded as bytes.

Sending Message Type and Receiving Message Type are the two Messages Types to 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

If the Decoding Type property value is 'Delimiter', then the following properties will be visible,

• Delimiter
• Append Delimiter while sending message

• Include Delimiter in the received message

• Maximum Message Length (bytes)

The Decoding Type is set to 'Delimiter' by default.

Delimiter

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

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

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.

In a simple Client-Server Socket scenario, the Append Delimiter while sending message property should be enabled. As the message received at the input port of the Server does not contain a 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

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.

• 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.

Length

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 visible only when the property Decoding Type is Length based.

Figure 4: Length decoding type option

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

If the Decoding Type property value is 'ISO', then the following properties will be visible above the Decoding Type property,

• Message Length Numeric Type 

• No of Chars in Message Length Field

Figure 5: ISO decoding type option

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.

This property is visible only when the Message Length Numeric Type property is set to either 'Hexadecimal' or 'Decimal'.

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.

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.

• 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 sent by a client takes more time than the Suspend Timeout to execute, then the next message is sent.

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.

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 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.

• For steps to generate a .pem key, please follow the link below for instructions:
  https://www.ibm.com/support/knowledgecenter/en/SSWHYP_4.0.0/com.ibm.apimgmt.cmc.doc/task_apionprem_gernerate_self_signed_openSSL.html
• The path of the key must be provided in CPS at both server side and client side. Generally, RSA Algorithm is used to generate a .pem key.

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. 

• This needs to be used only in such circumstances.
• If sequential processing is not required, please use sessions on the input port.

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

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.

A single range of a series of IP addresses may be specified as well as multiple ranges may be provided separated by semicolons.

Examples of various patterns

Single Range - 192.168.1.0 to 192.168.1.99

 192.168.1.\b([0-9]|[0-9][0-9])\b

Multiple Range - 192.168.1.0 to 192.168.1.100 & 192.168.1.101 to 192.168.1.200 & 192.168.1.201 to 192.168.1.255

 192.168.1.\b([0-9]|[0-9][0-9]|100)\b;192.168.1.\b(1[0-9][0-9])|200)\b;192.168.1.\b(2[0-4][0-9]|25[0-5])\b

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.

It is displayed only when the Create Socket option is enabled. 

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.

If the value is zero, it waits infinitely for the session to be idle.

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.

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.

Scenario 1: Decoding Type as 'Delimiter'

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

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

Scenario 2: Decoding Type as 'Length'

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

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

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.

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

aaa,bbb,cc

aaa 

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

In Synchronous mode

• When the same input is sent once again, the output will be the delimiter specified; in this example, it is comma - ,
• A single output will be received even if two or more messages are are attempted to be sent at once.

In Asynchronous mode

• All messages are sent at once after getting processed by the server.

• The output will be:

  CODE

  aaa,,bbb,,ccc,,

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.

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.

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