In-line processing

The extensible architecture of the trading engine enables developers to apply custom logic to messages in the processing pipeline. Custom processing logic, implemented as a Java class, can be applied at runtime to inbound or outbound messages at three points:

  • Immediately after a message has been consumed
  • After a message has been parsed and based on user-defined criteria
  • Immediately before a message is produced.

In-line processing just after consumption or before production is configured at an exchange point in the user interface. Custom processing is enabled for messages with specific sources and destinations.

In-line processing based on user criteria is configured in the Message Handler area of the user interface. Full control is provided over when custom logic is applied to messages, based on source, destination or logical constraints.

For any in-line processing, developers implement the same Java interface: MessageProcessor. From within a MessageProcessor, developers have access to the message's payload as well as metadata about the message payload or the processing context. The API also provides access to a string parameter configured by an application administrator in the user interface. This string can specify the location of a properties file or perhaps a flag to control what processing is performed.

You can use in-line processing to:

  • Write message metadata to a custom database table for purposes such as billing, reporting or monitoring.
  • Write message payloads to a shared directory and replace the content with XML-based metadata.
  • Exchange metadata with back-end servers by wrapping the metadata and message payload together in an XML wrapper.
  • Replace the document’s current content with translated or entirely different content (for example, ASCII <-> EBCDIC).

Runtime use of in-line processing

The following describes how MessageProcessors are used at runtime to process a message. For detailed information on each method, see the API Javadoc.

To configure in-line processing in the user interface, an application administrator enters a Java class name and an optional parameter. If configuring at an exchange point, a short description also can be entered. This information is persisted to the database.

When an in-line process is required at runtime, B2Bi:

  • Dynamically constructs an instance of the Java class, implementing a MessageProcessor based on the configuration in the user interface. (The MessageProcessor class must have a default constructor.)
  • Passes the optional parameter specified in the user interface to the class by calling setParameters().
  • Invokes the MessageProcess.process() method, passing the message being processed. At this point, custom logic is executed.

There are no technical differences in the operation of a MessageProcessor called from an exchange point or the Message Handler. However, the available metadata are different. For example, at a consumer exchange point, the received message has not been parsed, so routing IDs are unknown and not populated in the metadata. For your processing scenarios, make sure the metadata you need are available.

Implementing in-line processing

A developer must implement the in-line processing interface defined in com.cyclonecommerce.api.inlineprocessing.MessageProcessor.

Use the API Javadoc for a detailed description of each method.

The following are the general steps needed to implement in-line processing:

  1. Determine the required logic. You have access to the message payload and metadata, but follow guidelines for processing in a distributed cluster. Perform tests to make sure the metadata you want is present when expected in your particular version and configuration.
  2. Create a Java class that implements the MessageProcessor interface. Use the string passed into init() as an optional configuration parameter. Use the message passed to process() as the source of message data.
  3. Deploy the new MessageProcessor to B2Bi by copying the JAR file you create to <install directory>/jars. Any files in this directory are automatically added to the classpath at startup.

Java does not support dynamic reloading of Java classes. Restart after recompiling the in-line processor.

To access metadata or payload content from a message related to the message object passed into the in-line processor, use the MessageQuery class. The MessageQuery class supports querying for message objects by CoreId, IntegrationId or MessageId.

Add an in-line processing task

You can configure in-line processes in the user interface at exchange points and in the Message Handler area.

Here is an example demonstrating in-line processing:

  1. On a community summary page, click either the icon for Application pickup or Application delivery at the top of the page.
  2. Click a pickup or delivery exchange name to open its maintenance page.
  3. Click the In-line processing tab for that pickup or delivery exchange.
  4. To zip all files passing through the exchange, type the following in the Class name field: examples.inlineprocess.Zippit. To unzip all files passing through the exchange, type the following in the Class name field: examples.inlineprocess.Unzippit.
  5. Click Save changes.
  6. From the menu bar at the top, click Processing configuration.
  7. At the top of the Processing configuration page, in the navigation graphic, click either of the Message Handler icons.
  8. In the Related tasks area, click "Add a new message processing action" to open the Message Processing Action Wizard.
  9. Add a new condition and define criteria for executing the in-line process, then click Next.
  10. On the Operator and value page of the Message Processing Action Wizard, select Perform inline processing via a Java class and enter the class name and an optional parameter.
  11. Click Finish.

For more information about the REST API classes, see the Swagger API Javadoc.

To open Swagger and consult the Javadoc, open a browser and enter the URL https://<host>:<port>/apidocs/ui.

Related Links