Page History

...

Protobuf is a language-agnostic, schema-based data serialization system created by Google. The Protobuf message format is binary and is considered more efficient than other formats like JSON & XML. The Protobuf extension enables SOAtest and Virtualize to support the Protobuf message format. It can read schemas from a Confluent Schema Registry or saved to a local drive.

Installing the extension adds the Protobuf Client for SOAtest and the Protobuf Message Responder for Virtualize.

...

Command Line Installation

Add the Protobuf protobuf-extension.jar file to the system.properties.classpath property in your settings properties file. For example:

...

You can add standalone Protobuf clients to your suite using the Add Test wizard or chain Protobuf tools as a payload output of an existing tool using the Add Output wizard. See Adding Projects tst files and Test Suites for details.

Configuration and Usage

Protobuf clients function in a manner similar to other messaging clients but are configured to use the Protobuf format by default. In addition, there are a few configuration options that are unique to Protobuf clients:

...

• Message type: Choose from the type definitions available in the schemas in the Protobuf schemas folder or Confluent schema registry specified previously (see Configuring Protobuf Schemas Location).When a local schema folder has been specified, you will see the names of available schema types in this list. When a Confluent Schema Registry has been specified, subject/version pairs will be shownbuilt into your protobuf-extension.jar.

Adding Protobuf Message Responders

You can add Protobuf message responders to your suite using the Add Responder wizard. See Creating Message Responders Manually for details. 

Configuration and Usage

Protobuf message responders function in a manner similar to other responders. Refer to Message Responder Overview for information on configuring and using responders.  There are a few configuration options that are unique to Protobuf message responders:

...

• Message type: Choose from the type definitions available in the schemas in the Protobuf schemas folder or Confluent schema registry specified previously (see Configuring Protobuf Schemas Location).When a local schema folder has been specified, you will see the names of available schema types in this list. When a Confluent Schema Registry has been specified, subject/version pairs will be shown.built into your protobuf-extension.jar.

You can also configure the responder to use a different Protobuf message type for incoming requests. To do so:

1. In the message responder, click the Options tab and choose Request Handling.
2. Enable Convert incoming request to XML using different message format than response.
3. Choose Protobuf from the Format menu.
4. Choose the message type that is expected to come into the virtual asset from the Message type menu that appears. Type definitions available in the schemas in the Protobuf schemas folder or Confluent schema registry specified previously (see Configuring Protobuf Schemas Location).When a local schema folder has been specified, you will see the names of available schema types in this list. When a Confluent Schema Registry has been specified, subject/version pairs will be shown

Specifying Conversion Options

In the Protobuf message format, when an option is blank, the conversion will use the default option for that option. Otherwise, if a value is selected or entered, the conversion will attempt to use that value. Note that if an invalid value is entered manually, you may get an error when trying to switch between Form Input/Form XML and Literal views, or when running the test.

The following conversion options are available on the Conversion Options tab:

• Package: An optional package name to use for parsing native Protobuf messages.
• Message: An optional message type name to use for parsing native Protobuf messages.
• Format: Controls whether to expect Protobuf messages in the standard binary format or in ProtoJSON format. By default, messages are generated in binary format. The message format for parsing native messages is detected automatically unless specified.
• Log Level: Specify how much information you want logged to the console. The default is 2 (warn).

Package and Message Usage

In the Protobuf Client, the outgoing request is configured by specifying a type in the Message type field. By default, the incoming response is parsed using this message type, but you can use the Package and Message conversion options to specify a different message type for parsing the incoming response.

In the Protobuf Responder, the outgoing response is configured by specifying a type in the Message type field. By default, the incoming request is parsed using this message type, but you can use the Request Handling options to select a different message type for parsing the incoming request. See Request Handling for more information. The Package and Message conversion options should be left blank.

In traffic wizards, the message type of each request and response is detected automatically. The Package and Message conversion options should be left blank. However, in some situations there may be more than one message type that can correctly identify a binary Protobuf message. The Package and Message conversion options can be used to force the expected message type if there is any such ambiguity.

In XML Converter tools, use the Message type field to select the expected message type. If a message type is not selected, a compatible type will be automatically chosen at execution. The Package and Message conversion options should be left blank.

In Traffic Viewers, Protobuf messages are automatically parsed and displayed on the Tree and Element tabs. The labels shown for each field are contrived because Protobuf messages are binary and do not actually contain named fields. The field names are based on the definition of a compatible message type that is automatically selected to parse the message.

Working with ProtoJSON

The Protobuf extension can generate and consume messages in ProtoJSON format or the standard binary format. Specify the format in the Format field on the XML Conversion Options tab. By default, messages are generated in binary format. The message format for parsing native messages is detected automatically unless specified.

In the Protobuf Client and the Protobuf Responder tool, the outgoing message can be initialized from ProtoJSON:

1. Set Input mode to Literal and provide the JSON version of the Protobuf message in the text area.
2. Switch to the Form Input view. The Message type field and Form Input fields will be automatically populated from the JSON message. At runtime, the Protobuf message generated from the Form Input view will be in binary format by default.

The Protobuf Client and the Protobuf Responder tools have a Payload Converted to XML output that allows the incoming message to be validated in XML format, typically with an XML Assertor tool or a Diff tool in XML mode. If you instead want to validate messages as ProtoJSON, first chain an XML Converter tool. In the XML Converter tool under Tool Options, set Format to Protobuf and Conversion direction to From XML to native. The Message type can be left blank because it will be inferred from the XML. Under Options, set Format to JSON. A JSON Assertor can then be chained to the XML Converter tool, for example.

Using Protobuf with gRPC

One of the benefits of using the Protobuf extension is the ability to use it in conjunction with the gRPC Transport in order to send messages in one format and receive messages in another format.