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.