2.6. Migrating scenarios to latest version

This chapter describes all you need to do in order to migrate PerfCake to a newer version.

2.6.1. From v1.0 to v2.x

The following list shows the steps that are needed to migrate from PerfCake version 1.0 to 2.x:

  • Rename scenario XML schema namespace
  • Rename message number constant name

The following sections describe each step in detail.

Migration steps

Rename XML schema namespace

The namespace of the XML schema for scenarios has been renamed from urn:perfcake:scenario:1.0 to urn:perfcake:scenario:2.0 so it must be updated in the scenario XML files.

Rename Message Number Constant Name

If your sender depends on message ordinal number you need to change the name of the particular constant from PerfCakeConst.MESSAGE_NUMBER_PROPERTY to PerfCakeConst.MESSAGE_NUMBER_HEADER

2.6.2. From v2.x to v3.x

There are several steps that are needed to migrate scenarios from PerfCake version 2.x to 3.x. The following list shows them:

  • Rename scenario XML schema namespace
  • Rename class names
  • Replace reporters
  • Update RequestResponseJmsSender

The following sections take a look at each step in detail.

Migration steps

Rename XML schema namespace

The namespace of the XML schema for scenarios has been renamed from urn:perfcake:scenario:2.0 to urn:perfcake:scenario:3.0 so it must be updated in the scenario XML files.

Rename class names

Following classes has been renamed to follow the naming conventions (See Developers' Guide).

Class name in version 2.xClass name in version 3.x
HTTPSenderHttpSender
HTTPSSenderHttpsSender
JDBCSenderJdbcSender
JMSSenderJmsSender
RequestResponseJMSSenderRequestResponseJmsSender
SOAPSocketSenderSoapSocketSender
SSLSocketSenderSslSocketSender
CSVDestinationCsvDestination
TextMessageValidatorRegExpValidator
RulesMessageValidatorRulesValidator

Table 2.6. Renamed classes in PerfCake v3.x


Replace reporters

There are several reporters that has been removed from PerfCake and has been replaced by others. The following sections illustrate that change and how to perform the migration at the same time.

AverageThroughputReporter -> ThroughputStatsReporter
  1    <reporter class="AverageThroughputReporter">
  2       ...
  3       (destinations)
  4       ...
  5    </reporter>

is replaced by

  1    <reporter class="ThroughputStatsReporter">
  2       <property name="minimumEnabled" value="false"/>
  3       <property name="maximumEnabled" value="false"/>
  4          ...
  5          (destinations)
  6          ...
  7    </reporter>
ResponseTimeReporter -> ResponseTimeStatsReporter
  1    <reporter class="ResponseTimeReporter">
  2       ...
  3       (destinations)
  4       ...
  5    </reporter>

is replaced by

  1    <reporter class="ResponseTimeStatsReporter">
  2       <property name="minimumEnabled" value="false"/>
  3       <property name="maximumEnabled" value="false"/>
  4          ... 
  5          (destinations)
  6          ...
  7    </reporter>
WindowResponseTimeReporter -> ResponseTimeStatsReporter
  1    <reporter class="WindowResponseTimeReporter">
  2       <property name="windowSize" value="10"/>
  3          ...
  4          (destinations)
  5          ...
  6    </reporter>

is replaced by

  1    <reporter class="ResponseTimeStatsReporter">
  2       <property name="windowSize" value="10"/>
  3       <property name="minimumEnabled" value="false"/>
  4       <property name="maximumEnabled" value="false"/>
  5          ...
  6          (destinations)
  7          ...
  8    </reporter>
Update RequestResponseJmsSender

The RequestResponseJmsSender newly introduces the possibility to specify different connection properties for request and response. But it changes the default behavior. To ensure the original behavior is kept, the security properties for the response has to be added to keep request and response credentials the same.

RequestResponseJMSSender -> RequestResponseJmsSender
  1    <sender class="RequestResponseJMSSender">
  2       ...
  3       <property name="connectionFactory"
  4                 value="${jms.connection.factory}"/>
  5    
  6       <property name="username" value="${username}"/>
  7       <property name="password" value="${password}"/>
  8       <!-- JNDI -->
  9       <property name="jndiContextFactory"
 10                 value="${jndi.ctx.factory}"/>
 11       <property name="jndiUrl" value="${jndi.url}"/>
 12       <property name="jndiSecurityPrincipal"
 13                 value="${jndi.username}"/>
 14       <property name="jndiSecurityCredentials"
 15                 value="${jndi.password}"/>
 16       ...
 17    </sender>

is replaced by

  1    <sender class="RequestResponseJmsSender">
  2       ...
  3       <property name="connectionFactory"
  4                 value="${jms.connection.factory}"/>
  5       <property name="username" value="${username}"/>
  6       <property name="password" value="${password}"/>
  7       <property name="responseUsername" value="${username}"/>
  8       <property name="responsePassword" value="${password}"/>
  9       <!-- JNDI -->
 10       <property name="jndiContextFactory"
 11                 value="${jndi.ctx.factory}"/>
 12       <property name="jndiUrl" value="${jndi.url}"/>
 13       <property name="jndiSecurityPrincipal"
 14                 value="${jndi.username}"/>
 15       <property name="jndiSecurityCredentials"
 16                 value="${jndi.password}"/>
 17       <property name="responseJndiSecurityPrincipal"
 18                 value="${jndi.username}"/>
 19       <property name="responseJndiSecurityCredentials"
 20                 value="${jndi.password}"/>
 21       ...
 22    </sender>

Scenario conversion using XSLT

After understanding all the steps needed to migrate PerfCake scenarios from version 2.x to version 3.x we can take a look at an option to make the migration automatically using XSL transformation [5] . The particular XSLT is available as a part of the PerfCake distribution and it can be found at $PERFCAKE_HOME/resources/xslt/scenario-2.0-to-3.0.xsl .

There is a way to perform tha automated transformation using PerfCake sources. Please refer to the section "Transformation of Scenarios" in the Developers' Guide.

2.6.3. From v3.x to v4.x

The following list shows the steps that are needed to migrate from PerfCake version 3.x to 4.x:

  • Rename scenario XML schema namespace

The following sections describe each step in detail.

Migration steps

Rename XML schema namespace

The namespace of the XML schema for scenarios has been renamed from urn:perfcake:scenario:3.0 to urn:perfcake:scenario:4.0 so it must be updated in the scenario XML files.

2.6.4. From v4.x to v5.x

The following list shows the steps that are needed to migrate from PerfCake version 4.x to 5.x:

  • Rename scenario XML schema namespace
  • Move run element out of generator
  • Change target property of senders to a dedicated <target> element.

The following sections describe each step in detail.

Migration steps

Rename XML schema namespace

The namespace of the XML schema for scenarios has been renamed from urn:perfcake:scenario:4.0 to urn:perfcake:scenario:5.0 so it must be updated in the scenario XML files.

Move run element out of generator

The run element of generator has been moved out of generator to a dedicatd element.

  1    <generator class="...">
  2       <run type="..." value="..."/>
  3       ...
  4       (properties)
  5       ...
  6    </reporter>

is replaced by

  1    <run type="..." value="..."/>
  2       <generator class="...">
  3       ...
  4       (properties)
  5       ...
  6    </reporter>
Change target property of senders to a dedicated <target> element.

The target property of senders was ascended from ordinary property to a dedicated element.

  1    <sender class="...">
  2       <property name="target" value="..."/>
  3       ...
  4       (properties)
  5       ...
  6    </sender>

is replaced by

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

Scenario conversion using XSLT

It is possible to automatically migrate scenarios from version 4 to version 5. For instructions on running the migration using PerfCake sources, please refer to "Transformation of Scenarios" section in the Developers' Guide.

2.6.5. From v5.x to v6.x

The following list shows the steps that are needed to migrate from PerfCake version 5.x to 6.x:

  • Rename scenario XML schema namespace

The following sections describe each step in detail.

Migration steps

Rename XML schema namespace

The namespace of the XML schema for scenarios has been renamed from urn:perfcake:scenario:5.0 to urn:perfcake:scenario:6.0 so it must be updated in the scenario XML files.

2.6.6. From v6.x to v7.x

The following list shows the steps that are needed to migrate from PerfCake version 6.x to 7.x:

  • Rename scenario XML schema namespace.
  • RegExp validator now needs to have the backslashed in the patter specification escaped as well.

  • Due to an update in the templating engine, we now longer support arithmetic expressions in templates and the default values in property placeholders are replaced by colon (instead of the pipe "|" character).

  • There is no sequence defined by default (although the default sequences were not documented).

  • The implicit message header storing the Message Number was removed, instead the same value is now available in message attributes passed to every sender and available for usage in both message headers and payload. It is now correctly stored under the key perfcake.iteration.number (which is defined in the constant PerfCakeConst.ITERATION_NUMBER_PROPERTY). If there are more messages or any of the messages has multiplicity higher than one in the scenario definition, all of the messages will have the same iteration number for each iteration.

  • We changed the configuration of sequences to be aligned with validators. This means that the sequence name attribute has been changed to sequence id.

  • We unified and corrected component package names. This required changing org.perfcake.reporting.reporters and org.perfcake.reporting.destinations to singular org.perfcake.reporting.reporter and org.perfcake.reporting.destination.

  • Sequences interface has updated the method to obtain the next value of the sequence.

  • Support for JMS API 2.0 in JmsSender and RequestResponseJmsSender.

The following sections describe some steps in more detail.

Migration steps

Rename XML schema namespace

The namespace of the XML schema for scenarios has been renamed from urn:perfcake:scenario:6.0 to urn:perfcake:scenario:7.0 so it must be updated in the scenario XML files.

Update RegExp Validator patterns

In every patter specified in the scenario, add one more backslash to places where a backslash was previously used to escape RegExp character. For example, change .*"I'm a [Ff]ish"!\.* to .*"I'm a [Ff]ish"!\\.* because the second dot is meant to match a dot character and not any character as it does in a RegExp.

Please refer to the section called “RegExpValidator” for more details.

Update template placeholders

Replace ${property||default} with ${property:default}. Replace arithmetic expressions like @{property + 1} with custom Section 4.6, “Sequences”.

For more details on the advanced features of proeprties filtering read Section 2.2.5, “Filtering properties”.

Rename the name attribute in sequences

In all scenario definitions change the sequence name attribute to sequence id. For example, in XML scenarios change the following:

Example 2.8. Old sequence configuration in XML

<sequence name="..." class="...">

To read like this:

Example 2.9. New sequence configuration in XML

<sequence id="..." class="...">

Rename of packages under org.perfcake.reporting

This would affect you only when you used the canonical package name in scenario configurations, or when you developed custom components and put them in the same packages as PerfCake components are. Namely under org.perfcake.reporting.reporters and org.perfcake.reporting.destinations. All the plural package names should be now converted to singular (i.e. org.perfcake.reporting.reporter and org.perfcake.reporting.destination).

Update Sequence implementations

In your Sequence implementations change the following:

Example 2.10. Old Sequence implementation

public String getNext() {
   ...
   return nextValue;
}

To the new implementation:

Example 2.11. New Sequence implementation

public void publishNext(final String sequenceId, final Properties values) {
   ...
   values.setProperty(sequenceId, nextValue);
}

This update allow a single section to publish more values. All the value keys should start with the sequence specific prefix from the sequenceId parameter.

Support for JMS API 2.0

By default, JmsSender and RequestResponseJmsSender now use JMS API 2.0. If you want to continue using JMS API 1.1, change your scenarios to use Jms11Sender, or RequestResponseJms11Sender respectively.