Page History

...

SOAtest and Virtualize include a framework that allows you to extend their built-in message formats. The framework can support any message format that you are working with, for example, mainframe message formats, binary formats, or any other kind of proprietary custom message format. The message formats are defined by creating a conversion between the native format and XML. This conversion allows the user to construct and validate messages using the rich XML tooling that is available. This extension is done using Java.Once  Once a custom message format has been added, Virtualize will automatically make a new responder available for responder available for configuring and sending request or response messages using that format. You   You can add instances of the new client/responder to your test scenarios or responder suites.See  See Custom Message Responder for details about how to use them. The new message format will also appear in the XML Converter tool, which is described in XML Converter.

...

This is a required class that is used to implement the conversion logic to and from the native format and XML. The toXML() method should return your message in XML format, while the toNative() method should return your message in its native format. The methods take:

• An INativeMessage or IXMLMessage, which can be used to retrieve a representation of the message to be converted.
• An IConversionContext, which provides configuration settings and a way to share data between the different methods. In addition, IConversionContext extends ScriptingContext, which is a standard Parasoft scripting context that allows for accessing variables, data source values, and setting/getting objects for sharing across tools.

toXML() returns an INativeMessage while toNative() returns an IXMLMessage. There are default implementations of these interfaces when can be used for convenience (DefaultNativeMessage and DefaultXMLMessage).

For toNative, implementors must handle the case where the message type for the xmlMessage parameter is {@code null}. If the particular conversion being defined does not know how to convert from XML to the native message without being passed the specific message type, then a {@link CustomConversionException} should be thrown.

For toXML, the conversion may optionally be written so that it can auto-detect the message type for the passed-in nativeMessage. This auto-detection is used to determine the message type when switching from literal to form views or when using the traffic wizards to generate assets. If the conversion does not support auto-detection, you will need to explicitly choose the message type, or else SOAtest/Virtualize will try to detect the message type (which in some cases may be incorrect). To support auto-detection, implementors should ignore the message type for the passed-in nativeMessage. They should instead determine the message type themselves and set it into the returned XML message. 

Implementors must handle the case where the message type for the nativeMessage parameter is {@code null}, because that is how support for auto-detection is determined. If the particular conversion being defined does not support auto-detection and thus does not know how to do the conversion without being passed the message type, then a {@link CustomConversionException} should be thrown.

Errors that are encountered during conversion can be handled in two different ways. If the error is a fatal error that must abort the conversion, a CustomConversionException with an appropriate error message should be thrown. If the error is non-fatal (meaning the conversion can continue), a message can be reported using IConversionContext.report(String message) and a (possibly partial) converted message should still be returned by the method. If an error is reported by throwing an exception or calling report(), it will be reported either as a dialog in the client/responder UI, or as an error message when the client/responder is run.

...

When defining specific message types for a given message format, you must provide an XML schema for each message type. This is an optional class that provides one method of providing an XML schema for a given specific message type. If you don’t implement this class and reference it in parasoft-extension.xml, you must instead provide references to schema files (see Defining parasoft-extension.xml for a Custom Message Format below).

This interface has one method, generateSchema(), which takes:

• An IMessageType, which provides information about the message type for which a schema should be generated. The instance of IMessageType that is passed in will contain the id and name of a message type that was defined in parasoft-extension.xml.

• An ICustomXMLConverterConfiguration, which provides access to the values that come from the Conversion Options tab of the custom message format clients/responders.

generateSchema() returns a URI that is a reference to a schema file. It can be a reference to a dynamically generated schema, a reference to a schema that lives in the jar file providing the custom message format extension, or a reference to an external resource. An empty URI can be returned if there is an error in generating the schema; this will result in the Form Input view not being populated appropriately for the given message type. 

...

After you have implemented the necessary classes, define parasoft-extension.xml (introduced in General Procedure of Adding an Extension in Virtualize) using the following schema:

<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="urn:ocm/parasoft/extensibility-framework/extension"
		type="messageFormat"
		name='the name of your message format, appears in menus' description='A more detailed description'>
    <class>com.myCompany.MyConverter</class> <!-- implements ICustomXMLConverter -->
    <messageFormat xmlns="http://schemas.parasoft.com/extensibility-framework/messageFormat">
		<defaultMimeType>text/plain</defaultMimeType>
		<messageTypes generatorClass="com.myCompany.SchemaGenerator">
		<messageType id='unique ID' name='name' xsd='path to schema in jar'/>
			. . .
		</messageTypes>
		<client icon="myClient.gif" defaultTransport='default transport' /> 
		<responder icon="myResponder.gif" /> 
    </messageFormat>
    <version id='your version ID' updaterClass="com.myCompany.myUpdater"/>    
	<form xmlns="urn:com/parasoft/extensibility-framework/gui">
		<section label="field group 1">
			<field id="key 1" label="field 1"/>
			<field id="key 2" label="field 2"/>
		</section>
		<section label="field group 2">
			<field id="key 3" label="field 3"/>
			. . . 
		</section>
		. . .
    </form> 
</extension>

The field ids IDs under the section elements are used to retrieve values from the ICustomXMLConverterConfiguration instance that is passed in to the various API methods, and that allows for the values provided by the user to be passed in to your implementation. They are also used to persist the userprovided values to the responder deployment descriptor file when it is saved. The field labels appear in the in the GUI that is constructed based on this XML. The section layout does not have a programmatic impactprogrammatic impact; it merely helps organize the various GUI fields into sections or categories for easy access and usability and usability by the end user. 

The fully qualified class name of the class that implements ICustomXMLConverter, along with the name of the extension, is used to identify the message format that is being used in clients/responders. Changing the qualified class name or the name of the extension after you have saved .tst or .pva files will prevent saved clients or responders from being able to resolve the message format that they are using. 

...

• <defaultMimeType>: Specifies the default MIME type for your message format. The MIME type is used to identify the type of information that your message contains. The default MIME type is used as the Content Type in message headers when sending messages.
• <messageTypes>: This is an optional element that defines a set of specific message types. If no messageTypes element is provided, you are defining a general conversion between a native format and XML that has no specific message types defined. An example of such a format is CSV.
  • generatorClass - An optional attribute that holds the fully - qualified name of a class which implements ISchemaGenerator.
• <messageType>: Defines a message type for your custom message format.

  • id - A string identifier for your message type. Must be unique within a given message format. Also is used when saving clients/responders, so changing it will result in saved clients or responders not being able to resolve the message type that they are using.

  • name - Used to display the name of your message type in the GUI.
  • xsd - A URL path to your xsd. This attribute is required if you did not provide a generator class. Otherwise, it is ignored.

...