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.
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.
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 name | Description | Required | Default value |
---|---|---|---|
method | A name of CoAP method. One of GET , POST ,
PUT
or DELETE is supported
[a]
.
| No | POST |
requestType | CoAP request type that the sender will use. Either
confirmable
or nonConfirmable is supported
[b]
.
| No | nonConfirmable |
[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>
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 name | Description | Required | Default value |
---|---|---|---|
messageFrom | Specifies where the message is taken from by the sender. The supported values
are stdin or arguments
| No | stdin |
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!
".
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 name | Description | Required | Default value |
---|---|---|---|
delay | Time duration in milliseconds that the sender will simulate waiting for a response. If set to 0 (default) it will not wait at all. | No | 0 |
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>
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 name | Description | Required | Default value |
---|---|---|---|
groovyExecutable | Path to the Groovy binary, that would be used to execute the script. | No | $GROOVY_HOME/bin/groovy |
classpath | Classpath 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>
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 name | Description | Required | Default value |
---|---|---|---|
expectedResponseCodes | A comma separated list of HTTP response code(s) that is expected to be returned. | No | 200 |
method | An HTTP method to be used. [a] | No | POST |
storeCookies | Should the individual threads store cookies between requests? When true, the cookies are stored. | No | false |
[a] See http://docs.oracle.com/javase/7/docs/api/java/net/HttpURLConnection.html#setRequestMethod(java.lang.String) for a complete list of available methods. |
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>
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 name | Description | Required | Default value |
---|---|---|---|
keyStore | Path to the key store | No | - |
keyStorePassword | Key store password | No | - |
trustStore | Path to the trust store | No | - |
trustStorePassword | Trust store password | No | - |
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>
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 name | Description | Required | Default value |
---|---|---|---|
awaitResponse | Determines whether we should wait for the response from the channel. | No | false |
maxResponseSize | Expected 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
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 name | Description | Required | Default value |
---|---|---|---|
awaitResponse | Determines whether we should wait for the response from the channel. | No | false |
maxResponseSize | Expected 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
Sends messages through NIO
[8]>
SocketChannel
[11]
.
The sender's target is an URL of a socket in a form of<host>:<port>
.
Property name | Description | Required | Default value |
---|---|---|---|
awaitResponse | Determines whether we should wait for the response from the channel. | No | false |
maxResponseSize | Expected 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
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 name | Description | Required | Default value |
---|---|---|---|
driverClass | A fully qualified JDBC Driver class. | Yes | - |
username | A database user | no | "" |
password | A database password | no | "" |
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>
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 name | Description | Required | Default value |
---|---|---|---|
connectionFactory | A name of a JMS Connection factory. | Yes | - |
jndiContextFactory | A fully qualified name of the JNDI ContextFactory class. | Yes | - |
jndiUrl | A JNDI location URL. | Yes | - |
jndiSecurityPrincipal | A JNDI username | No | |
jndiSecurityCredentials | A JNDI password | No | |
autoAck | Indicates whether the received message will be auto-acknowledged. | No | true |
replyTo | The destination where the reply is supposed to be sent by server. JMS 'replyTo' header. | No | "" |
persistent | Indicate whether the message is to be persisted by JMS provider. | No | true |
transacted | Indicate whether the message transport is to be transacted. | No | false |
messageType | Indicate the type of the message. The supported values are
object , string and bytearray . | No | string |
username | A JMS security username. If not provided - JMS transport will be performed unsecured. | No | "" |
password | A JMS security password. If not provided - JMS transport will be performed unsecured. | No | "" |
safePropertyNames | Use 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. | No | true |
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>
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 name | Description | Required | Default value |
---|---|---|---|
searchBase | DN (distinguished name) to use as the search base | Yes | - |
filter | The search filter | Yes | - |
ldapUsername | LDAP server user | No | - |
ldapPassword | LDAP server password | No | - |
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>
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 name | Description | Required | Default value |
---|---|---|---|
qos | Quality 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
|
userName | MQTT broker user name | No | - |
password | MQTT broker password | No | - |
responseTarget | An 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 | - |
responseQos | Quality of service level for receiving a response. (see
qos
property description for more details).
| No | The value of
qos
property.
|
responseUserName | MQTT broker user name for response | No | - |
responsePassword | MQTT broker password for response | No | - |
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
.
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 name | Description | Required | Default value |
---|---|---|---|
tokenServerUrl | URL 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 |
tokenServerData | Data 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 |
responseParser | RegEx to create a capture group around the token value in the server's response. | No | .*"access_token":"([^"]*)".* |
oauthHeader | Header where the token is passed to the target service. The default value works with Keycloak. | No | Authorization |
oauthHeaderFormat | String formatting the value of authorization header. The token is placed instead of %s .
The default value works with Keycloak.
| No | Bearer %s |
tokenTimeout | How long in milliseconds is a token valid before a new one is needed. Defaults to 60s. | No | 60000L |
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&client_id=jboss-javaee-webapp&username=marvec&password=abc123"/> 6 <property name="responseParser" value=".*"access_token":"([^"]*)".*"/> 7 <property name="oauthHeader" value="Authorization"/> 8 <property name="oauthHeaderFormat" value="Bearer %s"/> 9 <property name="tokenTimeout" value="60000"/> 10 </sender>
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>
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 name | Description | Required | Default value |
---|---|---|---|
responseTarget | A JMS destination where the sender will wait and receive a response message from. | Yes | - |
responseConnectionFactory | A name of a JMS Connection factory for response. | No |
Value of
connectionFactory
of
JmsSender
|
responseJndiContextFactory | A fully qualified name of the JNDI ContextFactory class for response. | No |
Value of
jndiContextFactory
of
JmsSender
|
responseJndiUrl | A JNDI location URL for response. | No |
Value of
jndiUrl
of
JmsSender
|
responseJndiSecurityPrincipal | A JNDI username for response | No | - |
responseJndiSecurityCredentials | A JNDI password for response | No | - |
responseUsername | A JMS security username for response. If not provided - JMS transport will be performed unsecured. | No | - |
responsePassword | A JMS security password for response. If not provided - JMS transport will be performed unsecured. | No | - |
receivingTimeout | A time duration in ms of specifying how long the sender will wait to receive the response message. | No | 1000 |
receiveAttempts | A Number of attempts to receive the message. | No | 5 |
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.
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 name | Description | Required | Default value |
---|---|---|---|
engine | A 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'];
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 name | Description | Required | Default value |
---|---|---|---|
keyStore | Path to the key store. | No | - |
keyStorePassword | Key store password. | No | - |
trustStore | Path to the trust store. | No | - |
trustStorePassword | Trust 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>
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 name | Description | Required | Default value |
---|---|---|---|
remoteEndpointType |
One of
basic
or
async
.
| No | basic |
payloadType |
One of
text
,
binary
or
ping
.
[a]
| No | text |
[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.