In this section:

Overview

The asynchronous socket listener supports high levels of concurrency from socket-based clients using asynchronous reads and writes. It can be configured to read fixed-length, prefixed-variable-length, or token-delimited messages from the socket. Connections from the client are kept open until the client closes the connection or an error occurs in the listener. The listener logs an error and closes the client connection if a matching response is not heard. This is to prevent clients from waiting for responses to requests that the listener will not send.

Installation

The tool can be installed from the UI or command line. 

UI Installation

  1. Choose Parasoft > Preferences and click System Properties.
  2. Click Add JARs and choose the com.parasoft.virtualize.listener.asynchronous.socket-1.1.0.jar file. Once this jar file is added to the Virtualize classpath, all of the required dependencies will be loaded.
  3. Click Apply.
  4. Restart Virtualize.

Command Line Installation

Add the com.parasoft.virtualize.listener.asynchronous.socket-1.1.0.jar file to the system.properties.classpath property in your settings properties file. For example:

system.properties.classpath=<path to jar>/com.parasoft.virtualize.listener.asynchronous.socket-1.1.0.jar

Once the classpath is modified, all of the required dependencies will be loaded.

Usage

Once the asynchronous socket listener is installed, Asynchronous Socket Listener will be available in the Transports > Custom tab of the Virtual Asset configuration panel. Open this panel by double-clicking a virtual asset’s Virtualize Server node.

If multiple custom listeners are available, you can select the one you want to use from the Select Implementation menu.

Configuration

You can configure the following settings.

Settings

Protocol

Specifies the protocol used to transmit messages. Options are TCP or UDP.

Default: TCP

Port

Specifies the port that the socket listener will listen on for incoming connections. Specify 0 to automatically select an open port. After the asset is deployed, the selected port will be printed in the console.

Acceptor Threads

Specifies the number of acceptor threads used to receive messages. Not applicable if Protocol is set to UDP.

1 is the minimum value allowed.

Default: 2

Worker Threads

Specifies the number of worker threads used to process messages.

1 is the minimum value allowed.

Default: 50 

Character Set

Specifies the character set used to decode and encode bytes.

Default: UTF-8 

Connection BacklogSpecifies the number of connections allowed in the backlog before new connections will be rejected. This configuration is optional. Leaving the field empty is recommended.
Read Mode

Specifies the listener mode for reading messages.

  • Specify fixed for fixed length messages that are always the same size.
  • Specify prefixed for messages that have an int (4 bytes) length prefix at the beginning of the message.
  • Specify prefixed-string for messages with a series of string digits prefixing the message.
  • Specify token for messages that are delimited by an end character or uni code sequence.

Default: prefixed 

Fixed Length

Specify the size of the fixed message in the Fixed Length [default: 1024] field.

For example, if the size of messages is always four bytes, a client might send the following request:

[0, 0, 0, 0] 

The listener would send back a response of the same size, for example:

[1, 1, 1, 1] 

Each 4-byte message from the client would be considered a message.

Token Delimited

Token Delimiter

Specifies the token that delimits messages.

Default: byte 23, End-Of-Transmission-Block 

Token Type

Specifies the type of conversion used to get bytes from the token.

  • Specify string and the listener will use getBytes with the configured character set to convert to bytes.
  • Specify hex and the string will be parsed as a sequence of hexadecimal values. For example, 0a 0d would be the bytes 10 13.
  • Specify byte and the listener will parse the string as a sequence of bytes in decimal values separated by spaces, e.g., 10 13.

Default: hex

Token Delimited Example

If a new line (\n) delimiter is specified, then if a client sends multiple requests, the listener would process each message individually and send back a response for each message.

Example message
hello world\n
foo bar\n
Example response
good night world\n
bar foo\n

The listener processes each request and then sends back the response before handling the next message, even if all the messages are received as one read.

Prefixed Variable-Length (Number) 

The settings in this section only apply if the read mode is set to prefixed

Length of the Length Field

Determines the length of the length field. The desired number of bytes will be read and converted to a number to determine the length of the message. You can specify the following values: 1 , 2 , 3 , 4 , or 8.

The default is to read 4 bytes and convert it to an integer.

Include Length Field Size in Length 

Indicates if the length read should also include the length field size.

For example, if the option is enabled, a 4-byte message would send a length value of 8. This is because the default length of the length field is 4 bytes and will be added to the message body length. 

Default: true

Format of Static Prefix/Suffix 

Specifies the type of conversion used to convert the static prefix/suffix into bytes.

  • Specify string and the listener will use getBytes with the configured character set to convert to bytes.
  • Specify hex and the string will be parsed as a sequence of hexadecimal values. For example, 0a 0d would be the bytes 10 13.
  • Specify byte and the listener will parse the string as a sequence of bytes in decimal values separated by spaces, e.g., 10 13.

Default: hex 

Static Prefix

Specifies a prefix segment to be added to the message that may be required. If specified, the message format will be <PREFIX_BYTES><LENGTH_FIELD_BYTES><MESSAGE_DATA_BYTES>.

Static Suffix

Specifies a suffix segment of the message that may be required by the socket. If specified, the message format will be <LENGTH_FIELD_BYTES><MESSAGE_DATA_BYTES><SUFFIX_BYTES>.

Prefixed Variable-Length (Number) Configuration Example

If the client sends a request containing request1 that was prefixed with an int using the character set CP037 and the length includes the prefix length, then the request would be represented by the following bytes:

[0, 0, 0, 12, 114, 101, 113, 117, 101, 115, 116, 49]

The first four bytes ([0, 0, 0, 12]) are the integer 12, which is the length of the entire message including the first 4 bytes of the prefix. The remaining bytes are the string request1 as encoded by the configured character set.

Prefixed Variable-Length (String)

The settings in this section only apply if the read mode is set to prefixed-string

String Prefix Length

Specifies the size of the message length prefix. The number of bytes to read is calculated based on the number of digits converted into bytes. The listener encodes 0 into bytes and multiplies the number by the number provided in this field.

Default: 4 

Include Prefix in Length

Setting to true indicates that the length reads from the prefix should also include the length of the prefix.

Default: true 

Prefixed Variable-Length (String) Configuration Example

If the client sends a request prefixed by a string with 6 characters that has the total length of the message in bytes, then using the character set CP037 would result in the following string message:

000014request1 

The 000014 part of the string is the length prefix and 14 is the total length in bytes of the entire message as encoded by the character set including the prefix. If the prefix is not included in the length, then the request from the client would be the following string:

000008request1 

The 000008 part of the string is the length of request1 as encoded by the character set.

SSL

Set SSL Enabled [ default:false ] to true to listen over SSL. 

Logging

Specify the Log Level field. This setting is optional.

  • Enter 1 to only log errors
  • Enter 2 to log errors and warnings.
  • Enter 3 to log errors, warnings, and info.
  • Enter 4 to log errors, warnings, info, and debug.

Default is 3 

Change Log

1.1

  • Added support for UDP.

1.0

  • Initial release.


  • No labels