4.2. Where - Sending messages

As it was mentioned before, a sender is an object responsible for sending a message to the tested system and receiving the response in a specific way via a specific transport.

To tell the sender where to send the messages, there is a <target> element mandatory for all senders.

All message senders provided in PerfCake distribution are based on the AbstractSender class which cannot be used standalone but provides an important property available in all other senders. The property is keepConnection and instructs the sender to stay initialized for the whole run of the performance test. When set to false, the sender get initialized for each message. This influences the performance results and needs to be considered whether this is a required behavior. The default value of this property is true and it is not required in the scenario definition.

Example 4.7. An example of a Sender configuration

  1    <sender class="...">
  2       <target>...</target>
  3       ...
  4       sender properties
  5       ...
  6    </sender>

When specifying the sender class, unless you enter a fully classified class name, the default package org.perfcake.message.sender is assumed.

In the following sections you can find a complete description of all senders, that can be used by PerfCake including all of their properties.


4.2.1. CamelSender

The CamelSender can be used to send messages to any Apache Camel endpoint. The endpoint is defined in the target attribute in the configuration. Any Camel endpoints are allowed. Just make sure the corresponding Camel component JAR file and its dependencies are on the classpath. In the binary distribution, this means putting the JAR files in the lib/ext directory.

Endpoints can be usually configured by using message headers. To set the headers use the header element of the particular message element in the messages section of the scenario definition.

There are no extra configuration properties for CamelSender.

Example 4.8. An example of CamelSender configuration

  1    <sender class="CamelSender">
  2       <target>http:127.0.0.1:8283/perfcake?param1=value1</target>
  3    </sender>
  4    ...
  5    <messages>
  6       <message content="Hello from Camel">
  7          <header name="CamelHttpMethod" value="POST" />
  8       </message>
  9    </messages>

In this example, the CamelSender is configured to use the HTTP Camel component to send messages to an HTTP endpoint. The messages will be sent using the POST method as configured in the message header.


4.2.2. CoapSender

The sender can be used to send a single message using CoAP protocol [6] .

The target of the sender is a CoAP endpoint in a form of CoAP URI [7] .

Property nameDescriptionRequiredDefault value
methodA name of CoAP method. One of GET, POST, PUT or DELETE is supported [a] . NoPOST
requestTypeCoAP request type that the sender will use. Either confirmable or nonConfirmable is supported [b] . NononConfirmable

[a] See https://tools.ietf.org/html/rfc7252#section-5.8 for more detail on request methods of the CoAP protocol.

[b] See https://tools.ietf.org/html/rfc7252#section-2.1 for more detail on (non)confirmable requests of the CoAP protocol.

Table 4.6. CoapSender properties


Example 4.9. An example of CoapSender configuration

  1    <sender class="CoapSender">
  2       <target>coap://${server.host}:5683/resource</target>
  3       <property name="method" value="GET"/>
  4       <property name="requestType" value="confirmable"/>
  5    </sender>

4.2.3. CommandSender

The sender is able to invoke an external command (specified by the target property) in a separate process to send a message payload. The payload can be passed to the standard input of the process (default behavior) or as the command argument. That is configurable via messageFrom proerty.

The target of the sender is a path to the file containing the commands that are to be executed.

Message properties and headers are passed to the process as the environmental variables.

Property nameDescriptionRequiredDefault value
messageFromSpecifies where the message is taken from by the sender. The supported values are stdin or arguments Nostdin

Table 4.7. CommandSender properties


Example 4.10. An example of CommandSender configuration

  1    <sender class="CommandSender">
  2       <target>/tmp/script.sh</target>
  3    </sender>
  4    ...
  5    <messages>
  6       <message>
  7          <property name="GREETINGS" value="Be well!"/>
  8       </message>
  9    </messages>

In the example above there is a CommandSender configured to execute a script located in /tmp/script.sh file. The environmental variable GREETINGS is set to the value of " Be well! ".


4.2.4. DummySender

This sender is intended to work as a dummy sender and to be used for testing scenarios and developing purposes. It does not actually send any message. It can simulate a synchronous waiting for a reply by setting the delay property.

While the target of the sender is mandatory for all senders, it is irrelevant for the DummySender so it can be anything.

Property nameDescriptionRequiredDefault value
delayTime duration in milliseconds that the sender will simulate waiting for a response. If set to 0 (default) it will not wait at all.No0

Table 4.8. DummySender properties


Example 4.11. An example of DummySender configuration

  1    <sender class="DummySender">
  2       <target>out there!</target>
  3       <property name="delay" value="500"/>
  4    </sender>

4.2.5. GroovySender

Groovy sender can be used to implement the message sending in a Groovy script. By default the sender uses the groovy installed on the system, where the PerfCake is executed. PerfCake would try to find it at the following path: $GROOVY_HOME/bin/groovy on UNIX systems or %GROOVY_HOME%\bin\groovy in case of Windows, where GROOVY_HOME is an environment variable.

The Groovy binary doesn't have to be the one, that is installed on the system. There is a possibility to use groovyExecutable property to specify, what Groovy binaries would be used to execute the target script.

The message configured in the scenario is passed to the Groovy script through standard input, so it can be accessed via System.in . The response is supposed to be passed back through a standard output via System.out .

The target of the sender is a path or URL to the Groovy script that is to be executed.

The following table describes all the GroovySender's properties.

Property nameDescriptionRequiredDefault value
groovyExecutablePath to the Groovy binary, that would be used to execute the script.No$GROOVY_HOME/bin/groovy
classpathClasspath for groovy executable - specifies where to find the class or groovy files.No-

Table 4.9. GroovySender properties


Example 4.12. An example of GroovySender configuration

  1    <sender class="GroovySender">
  2       <target>/tmp/script.groovy"</target>
  3       <property name="classpath" value="~/common-classes"/>
  4    </sender>

4.2.6. HttpSender

The HttpSender can be used to send messages via HTTP protocol using POST method as default to the URL specified by the 'target' property. The HTTP method can be changed using the method property.

Various scenarios can lead to different HTTP response codes that are expected. The scenario can be set to expect one or more response codes. It can be set via the expectedResponseCodes property. Default expected response code is 200.

To set headers of the HTTP request use the header element of the particular message element in the messages section of the scenario definition.

The Content-Type header is set automatically by the sender for all messages to the value of text/plain; charset=utf-8 by default. Also Content-Length header is generated and set automatically to the value of message payload size if the payload is not empty.

The target of the sender is an URL, where the message is send.

Following table shows the properties of the HttpSender:

Property nameDescriptionRequiredDefault value
expectedResponseCodesA comma separated list of HTTP response code(s) that is expected to be returned. No200
method An HTTP method to be used. [a] NoPOST
storeCookies Should the individual threads store cookies between requests? When true, the cookies are stored. Nofalse

Table 4.10. HttpSender properties


Example 4.13. An example of HttpSender configuration

  1    <sender class="HttpSender">
  2       <target>http://domain.com/cool-url</target>
  3       <property name="method" value="GET"/>
  4       <property name="expectedResponseCodes" value="200,202"/>
  5    </sender>

4.2.7. HttpsSender

HttpsSender is similar to the HttpSender (see Section 4.2.6, “HttpSender” ), thus it inherits the same properties. The difference is that the HttpsSender uses HTTPS instead of plain HTTP protocol to send messages.

The HttpsSender's properties are described in the following table:

Property nameDescriptionRequiredDefault value
keyStorePath to the key storeNo-
keyStorePasswordKey store passwordNo-
trustStorePath to the trust storeNo-
trustStorePasswordTrust store passwordNo-

Table 4.11. HttpsSender additional properties


Example 4.14. An example of HttpsSender configuration

  1    <sender class="HttpsSender">
  2       <target>https://domain.com/secured_url</target>
  3       <property name="method" value="POST"/>
  4       <property name="trustStore" value="${my.keystores}/cacert.jks"/>
  5       <property name="trustStorePassword" value="ts_passsword"/>
  6    </sender>

4.2.8. ChannelDatagramSender

Sends messages through NIO [8] DatagramChannel [9] .

The sender's target is an URL of a datagram socket in a form of <host>:<port>.

Property nameDescriptionRequiredDefault value
awaitResponseDetermines whether we should wait for the response from the channel. Nofalse
maxResponseSizeExpected maximum response size. Defaults to -1 which means to instantiate the buffer of the same size as the request messages. No-1

Table 4.12. ChannelDatagramSender properties


4.2.9. ChannelFileSender

Sends messages through NIO [8] FileChannel [10] .

The sender's target is a path to the file to which message is sent (written) or received (read).

Property nameDescriptionRequiredDefault value
awaitResponseDetermines whether we should wait for the response from the channel. Nofalse
maxResponseSizeExpected maximum response size. Defaults to -1 which means to instantiate the buffer of the same size as the request messages. No-1

Table 4.13. ChannelFileSender properties


4.2.10. ChannelSocketSender

Sends messages through NIO [8]> SocketChannel [11] .

The sender's target is an URL of a socket in a form of<host>:<port>.

Property nameDescriptionRequiredDefault value
awaitResponseDetermines whether we should wait for the response from the channel. Nofalse
maxResponseSizeExpected maximum response size. Defaults to -1 which means to instantiate the buffer of the same size as the request messages. No-1

Table 4.14. ChannelSocketSender properties


4.2.11. JdbcSender

As the name of the sender clues JdbcSender is meant to be used to send JDBC queries. It can handle any query the JDBC is capable of.

The target of the sender is a JDBC URL of the target, where the query is send.

Property nameDescriptionRequiredDefault value
driverClassA fully qualified JDBC Driver class.Yes-
usernameA database userno""
passwordA database passwordno""

Table 4.15. JdbcSender properties


Example 4.15. An example of JdbcSender configuration

  1    <sender class="JdbcSender">
  2       <target>jdbc:postgresql://localhost:5432/db</target>
  3       <property name="username" value="me-the-first"/>
  4       <property name="password" value="guess_me"/>
  5       <property name="driverClass" value="org.postgresql.Driver"/>
  6    </sender>

4.2.12. Jms[11]Sender

There are two versions of JMS (Java Message Service) sender. An older one supporting JMS API 1.1 - Jms11Sender (introduced in PerfCake 7.0, previously known as JmsSender). And a new one supporting JMS API 2.0 - JmsSender (new in PerfCake 7.0). Except for the API version they use, there is no difference in their functionality and properties. They should also have the same performance, depending on the client driver used.

The Jms[11]Sender can be used to send a single JMS message.

The target of the sender is a JNDI name of the JMS destination where the JMS message is send. Both JNDI and messaging can be secured independently.

For the sender to work properly, you need to have a JMS client adaptor on the class path. In PerfCake, this means placing the messaging client driver to the lib/ext directory.

The following table describes the JmsSender's properties:

Property nameDescriptionRequiredDefault value
connectionFactoryA name of a JMS Connection factory.Yes-
jndiContextFactoryA fully qualified name of the JNDI ContextFactory class.Yes-
jndiUrlA JNDI location URL.Yes-
jndiSecurityPrincipalA JNDI usernameNo 
jndiSecurityCredentialsA JNDI passwordNo 
autoAckIndicates whether the received message will be auto-acknowledged.Notrue
replyToThe destination where the reply is supposed to be sent by server. JMS 'replyTo' header.No""
persistentIndicate whether the message is to be persisted by JMS provider.Notrue
transactedIndicate whether the message transport is to be transacted.Nofalse
messageType Indicate the type of the message. The supported values are object , string and bytearray . Nostring
usernameA JMS security username. If not provided - JMS transport will be performed unsecured.No""
passwordA JMS security password. If not provided - JMS transport will be performed unsecured.No""
safePropertyNamesUse safe message property names because some messaging implementations (e.g. Apache Artemis) do not allow anything but valid Java identifiers. When set to true (which is the default), anything else than letters, numbers and underscores is changed to underscores.Notrue

Table 4.16. JmsSender properties


Example 4.16. An example of JmsSender configuration

  1    <sender class="JmsSender">
  2       <target>jms/queue/YourQueue</target>
  3       <property name="connectionFactory" value="jms/ConnFactory"/>
  4       <property name="username" value="KingRoland"/>
  5       <property name="password" value="12345"/>
  6       <!-- JNDI properties-->
  7       <property name="jndiContextFactory" value="pkg.InitCtxFactory"/>
  8       <property name="jndiUrl" value="remote://${server.host}:4447"/>
  9       <property name="jndiSecurityPrincipal" value="KingRoland"/>
 10       <property name="jndiSecurityCredentials" value="12345"/>
 11    </sender>

4.2.13. LdapSender

The sender is able to query an LDAP server [12] .

The target of the sender is an URL of the LDAP server in the form of ldap://<server-host>:<server-port> .

Following table shows the properties of the HttpSender:

Property nameDescriptionRequiredDefault value
searchBaseDN (distinguished name) to use as the search baseYes-
filterThe search filterYes-
ldapUsernameLDAP server userNo-
ldapPasswordLDAP server passwordNo-

Table 4.17. HttpSender properties


Example 4.17. An example of LdapSender configuration

  1    <sender class="LdapSender">
  2       <target>ldap://localhost:389</target>
  3       <property name="searchBase" value="dc=example,dc=org"/>
  4       <property name="filter" value="(objectclass=*)"/>
  5    </sender>

4.2.14. MqttSender

The sender is capable to send MQTT [13] messages to a remote broker and receiving responses if needed. The response is expected only if responseTarget property is set.

The target of the sender is an URL of the remote broker with the topic name in a form of <protocol>://<host>:<port>/<topic name> , where the message is send.

Following table shows the properties of the MqttSender:

Property nameDescriptionRequiredDefault value
qosQuality of Service level [a] - guarantee for the message delivery from the sender to the remote broker. Supported values are EXACTLY_ONCE, AT_LEAST_ONCE and AT_MOST_ONCE. No EXACTLY_ONCE
userNameMQTT broker user nameNo-
passwordMQTT broker passwordNo-
responseTargetAn URL of the remote broker and a topic name, from which the response is received. If ordinary string is presented (not in a form of an URL), the string as a whole is considered to be a response topic name in the same broker where the original message was sent. No-
responseQosQuality of service level for receiving a response. (see qos property description for more details). NoThe value of qos property.
responseUserNameMQTT broker user name for responseNo-
responsePasswordMQTT broker password for responseNo-

Table 4.18. MqttSender properties


Example 4.18. An example of MqttSender configuration

  1    <sender class="MqttSender">
  2       <target>tcp://localhost:1883/request.topic</target>
  3       <property name="responseTarget" value="response.topic"/>
  4    </sender>

I the example above there is a MqttSender configured to send messages to topic with the name of request.topic in a broker listening on tcp://localhost:1883. The response is expected and received from the topic with the name of response.topic of the same broker. The quality of service level for both sending and receiving is default EXACTLY_ONCE.


4.2.15. OauthHttpSender

OauthHttpSender is similar to the HttpSender (see Section 4.2.6, “HttpSender” ), thus it inherits the same properties. The difference is that the OauthHttpSender allows token authentication to an HTTP based service using OAuth2[14] protocol.

The OauthHttpSender's properties are described in the following table, where the defaults works with Keycloak:[15]:

Property nameDescriptionRequiredDefault value
tokenServerUrlURL of the server granting us a token. Default value works with Keycloak, supposing your realm name is demo. No http://127.0.0.1:8180/auth/realms/demo/protocol/openid-connect/token
tokenServerDataData to send to the server to request a token. Default value works with Keycloak.No grant_type=password&client_id=jboss-javaee-webapp&username=marvec&password=abc123
responseParserRegEx to create a capture group around the token value in the server's response.No .*"access_token":"([^"]*)".*
oauthHeaderHeader where the token is passed to the target service. The default value works with Keycloak.No Authorization
oauthHeaderFormatString formatting the value of authorization header. The token is placed instead of %s. The default value works with Keycloak. No Bearer %s
tokenTimeoutHow long in milliseconds is a token valid before a new one is needed. Defaults to 60s.No60000L

Table 4.19. HttpsSender additional properties


Example 4.19. An example of OauthHttpSender configuration

  1    <sender class="OauthHttpSender">
  2       <target>http://domain.com/secured_url</target>
  3       <property name="method" value="POST"/>
  4       <property name="tokenServerUrl" value="http://127.0.0.1:8180/auth/realms/demo/protocol/openid-connect/token"/>
  5       <property name="tokenServerData" value="grant_type=password&amp;client_id=jboss-javaee-webapp&amp;username=marvec&amp;password=abc123"/>
  6       <property name="responseParser" value=".*&quot;access_token&quot;:&quot;([^&quot;]*)&quot;.*"/>
  7       <property name="oauthHeader" value="Authorization"/>
  8       <property name="oauthHeaderFormat" value="Bearer %s"/>
  9       <property name="tokenTimeout" value="60000"/>
 10    </sender>

4.2.16. PlainSocketSender

The sender uses a socket to send the message to and receive a response from.

The target of the sender is a socket in a form of "<host>:<port>"

Example 4.20. An example of PlainSocketSender configuration

  1    <sender class="PlainSocketSender">
  2       <target>127.0.0.1:12345</target>
  3    </sender>

4.2.17. RequestResponseJms[11]Sender

Similarily to JmsSender, there are two variants of this sender for both JMS API 1.1 (RequestResponseJms11Sender, new in PerfCake 7.0, formerly known as RequestResponseJmsSender) and 2.0 (RequestResponseJmsSender, new in PerfCake 7.0).

The RequestResponse[11]JmsSender is supposed to be used in request-response scenarios. First it sends a JMS message to the target destination (specified by the target property) and then waits to receive the response message from the response destination (specified by the responseTarget property).

It is based on Jms[11]Sender (see Section 4.2.12, “Jms[11]Sender” ) and inherits all its configuration properties. Some properties, when not specified, use the same value as those present in Jms[11]Sender. However, security credentials always need to be set separately. The following table contains additional properties of the RequestResponseJms[11]Sender:

Property nameDescriptionRequiredDefault value
responseTargetA JMS destination where the sender will wait and receive a response message from.Yes-
responseConnectionFactoryA name of a JMS Connection factory for response.No Value of connectionFactory of JmsSender
responseJndiContextFactoryA fully qualified name of the JNDI ContextFactory class for response.No Value of jndiContextFactory of JmsSender
responseJndiUrlA JNDI location URL for response.No Value of jndiUrl of JmsSender
responseJndiSecurityPrincipalA JNDI username for responseNo-
responseJndiSecurityCredentialsA JNDI password for responseNo-
responseUsernameA JMS security username for response. If not provided - JMS transport will be performed unsecured.No-
responsePasswordA JMS security password for response. If not provided - JMS transport will be performed unsecured.No-
receivingTimeoutA time duration in ms of specifying how long the sender will wait to receive the response message.No1000
receiveAttemptsA Number of attempts to receive the message.No5

Table 4.20. RequestResponseJms[11]Sender properties


Example 4.21. An example of RequestResponseJmsSender configuration

  1    <sender class="RequestResponseJmsSender">
  2       <target>jms/queue/RequestQueue</target>
  3       <property name="responseTarget" value="jms/queue/ResponseQueue"/>
  4       <property name="receivingTimeout" value="30000"/>
  5       <property name="receiveAttempts" value="1"/>
  6       <property name="connectionFactory" value="jms/ConnFactory"/>
  7       <property name="username" value="KingRoland"/>
  8       <property name="password" value="12345"/>
  9       <property name="responseUsername" value="KingRoland"/>
 10       <property name="responsePassword" value="12345"/>
 11       <!-- JNDI properties-->
 12       <property name="jndiContextFactory" value="pkg.InitCtxFactory"/>
 13       <property name="jndiUrl" value="remote://${server.host}:4447"/>
 14       <property name="jndiSecurityPrincipal" value="KingRoland"/>
 15       <property name="jndiSecurityCredentials" value="12345"/>
 16       <property name="responseJndiSecurityPrincipal" value="KingRoland"/>
 17       <property name="responseJndiSecurityCredentials" value="12345"/>
 18    </sender>

In the example above there is a RequestResponseJmsSender configured to send messages to the queue jms/queue/RequestQueue using a connection factory found at jms/ConnFactory in JNDI. After sending a JMS message the sender waits for the response from the response queue jms/queue/ResponseQueue for at most 30s. It uses the same JMS provider for both request and response, so the request and response credentials (both JMS and JNDI) are the same. Connection factory, JNDI context factory and JNDI URL for the response are inherited from the respective request properties.


4.2.18. ScriptSender

The sender can be used to send a single message using a JSR 223 [16] compliant script.

The target of the sender is a path to the file where the script is implemented. To specify the scripting language engine there is a engine property. The message and it's headers are passed to the script via script binding and should be available as variables or objects instances, according to the scripting language.

The following table shows the senders properties.

Property nameDescriptionRequiredDefault value
engineA scripting language engine name. groovy is available out-of-the-box. No-

Table 4.21. ScriptSender properties


Example 4.22. An example of ScriptSender configuration

Scenario:

  1    <sender class="ScriptSender">
  2       <target>/tmp/script.groovy</target>
  3       <property name="engine" value="groovy"/>
  4    </sender>
  5    ...
  6    <messages>
  7       <message content="Soylent green">
  8          <header name="what" value="people"/>
  9       </message>
 10    </messages>

script.groovy file:

  1 println message.payload + " is made out of " + message.headers['what']; 

4.2.19. SslSocketSender

SslSocketSender is similar to the PlainSocketSender (see Section 4.2.16, “PlainSocketSender” ) and so it shares the same properties. The difference is that the SslSocketSender uses a SSL socket.

Property nameDescriptionRequiredDefault value
keyStorePath to the key store.No-
keyStorePasswordKey store password.No-
trustStorePath to the trust store.No-
trustStorePasswordTrust store password.No-

Table 4.22. SslSocketSender additional properties


If neither keyStore or trustStore are set, the default Java SSLSocketFactory is used. Its configuration depends on system properties.

Example 4.23. An example of SslSocketSender configuration

  1    <sender class="SslSocketSender">
  2       <target>127.0.0.1:12345</target>
  3    </sender>

4.2.20. WebSocketSender

The WebSocketSender can be used to send a simple messages via websocket protocol to a remote websocket server endpoint. The websocket technology creates a full-duplex connection over TCP and is suitable for applications requiring fast responses. It was standardized as RFC 6455 and it is a part of Java EE 7 (JSR-356). Connections are initiated by sending an HTTP upgrade header. It is event driven on both client and server sides. Load of requests is generated after the connection session is successfully established.

There are two forms of remote endpoints, which can be set - basic and async. To set content of message payload, set the message element in the messages section of the scenario definition. Payload can be set text, binary and ping. In PerfCake 5.x only text messages are supported.

The target of the sender is an URL of the remote endpoint, where the message is send.

The following table shows the properties of the WebSocketSender:

Property nameDescriptionRequiredDefault value
remoteEndpointType One of basic or async . Nobasic
payloadType One of text , binary or ping . [a] Notext

[a] Only text messages are supported in PerfCake 7.x.

Table 4.23. WebSocketSender properties


Example 4.24. An example of WebSocketSender configuration

  1    <sender class="WebSocketSender">
  2       <target>ws://domain.com/ws-ctx/ws-ep</target>
  3       <property name="remoteEndpointType" value="basic"/>
  4       <property name="payloadType" value="text"/>
  5    </sender>



[6] Costrained Application Protocol http://coap.technology/

[7] See https://tools.ietf.org/html/rfc7252#section-6 for more detail on CoAP endpoint URI

[14] See https://oauth.net/2/ for the protocol details.

[15] See http://www.keycloak.org for more information about the Keycloak server.

[16] See https://www.jcp.org/en/jsr/detail?id=223 for more details on JSR 223 specification.