Defining a new packet converter

A packet converter transforms a stream of recorder packets. Use packet converters for adapting the raw data that recorders capture into a suitable format for the test generators to use.

A converter typically follows one of these patterns:

  • A filtering converter removes input packets that do not meet a specific criterion. This converter does not modify packets, nor does the converter introduce new packets in the output stream. The product comes with a generic converter, with the com.ibm.rational.test.lt.testgen.core3.filter ID. You can add parameters to this converter with conditions.
  • An annotator converter does not remove or modify packets in the input stream, but rather introduces additional packets in the output stream. These packets are annotation packets that convey additional information that are inferred from the other packets. For instance, a converter might look for session, connection, or page boundaries in a packet stream, and then add a boundary packet whenever a boundary is detected in the input stream. This assists the test generator in identifying boundaries without the need to look ahead in the packet stream.
  • A reordering converter does not add, change, or remove packets from the input stream, but it outputs them in a different order. A typical example is the packet sorter that comes with the product, which outputs packets sorted by their start time stamp. The sorter ID is com.ibm.rational.test.lt.testgen.core3.packetSorter.
  • An aggregator converter has different input and output packet types. It aggregates multiple input packets into one output packet. The converter usually translates a lower-level protocol into a higher-level protocol. For example, the product comes with a converter that transforms raw data in a byte stream that is exchanged between a client and an HTTP server into aggregated HTTP packets (request/response pairs).

To define a new converter, you must complete these procedures:

  • Declare a new packet converter type in the plugin.xml file, using the com.ibm.rational.test.lt.testgen.core3. packetConverter extension point.
  • Assign the packet converter a unique ID and a name.
  • Declare the required properties of the packet input stream that the converter receives. The framework includes the required converters in the conversion stage, so these properties are verified when the packets reach the converter. For instance, if the converter requires the input packets to be ordered according to their start time stamps, specify the sorted parameter.
  • Declare which properties this converter adds to the output stream or removes from the output stream, as compared to the properties of the input stream. For example, a converter might disrupt the ordered property of the input stream; in this case, the sorted parameter must be included in removedProperties class.
  • If the converter has different input and output packet types and can be considered as a packet type converter, declare that it contributes to packet type conversions and specify the types of input and output packets that the converter produces.
  • Define an implementation class that implements the com.ibm.rational.test.lt.testgen.core.conversion.IPacketConverter interface.

Consider these facts about IPacketConverter implementations:

  • Typically, you extend the com.ibm.rational.test.lt.testgen.core.conversion.BasePacketConverter class, which provides a basic implementation and only requires overriding the specific methods.
  • A packet converter is an IPacketReferenceOutputStream interface that writes to another IPacketReferenceOutputStream interface. In other words, a packet converter has a writePacket() method, which is invoked by the framework for each input packet it processes. The packet converter is responsible for invoking the getContext().getOutputStream().writePacket() method whenever it needs to send a packet to its output.
  • A packet converter can have options. The options are available by using the getContext().getConfiguration() method, which is typically called in the initialize() method.
  • A packet converter can send additional packets to its output in the complete() method. This method is called when there are no more input packets to use.
  • Use the getContext().logMessage() method to report messages from the test generator to the user, including error messages. If the message pertains to an unrecoverable error, the framework stops the test generation process.

For scalability reasons, converters manipulate IRecorderPacketReference objects instead of IRecorderPacket objects. Follow these procedures to get the best results when you write packet converter code:

  • An IRecorderPacket interfacecan be obtained from a reference that uses the IRecorderPacketReference.getRecorderPacket() method.
  • A converter that must echo the same packet to its output as the one received must write the same reference instance that the converter has received.
  • When a converter instantiates a new recorder packet, the converter can wrap the packet into a new reference by using the getContext().createPacketReference() method so that the packet can be sent as output.
  • Just as recorders can produce packet attachments, converters can do so as well. To create a new attachment, use the getContext().createPacketAttachment() method.
  • If the converter must hold a packet a long time before the packet is sent as output, the converter can unload the packet and keep only a reference to the packet. To do so, call the unload() method on the packet reference.
  • Converters are provided with a facility for efficiently accumulating a large number of packets and atomically discarding them, or flushing them, to the output. See the com.ibm.rational.test.lt.testgen.core.store.IPacketReferenceStore class for more information. A packet store can be created using the getContext().createPacketStore() method.