Pluggable embedded server

B2Bi supports embedded server extensibility through pluggable servers for customized message consumption. This enables custom code to control message exchanges with any back-end application or custom trading protocol without changing the base code.

Delivery exchanges define the connection points between:

  • B2Bi and back-end systems.
  • B2Bi and remote trading partners.

B2Bi supports many types of native embedded-server exchange points, including HTTP, FTP, and SFTP and OFTP. When a customized transport protocol is desired, developers can use the pluggable server API to create servers to run inside of B2Bi.

Java interfaces

The pluggable-server framework interacts abstractly with external transport servers via Java Interfaces. The two interfaces are PluggableServer and PluggableMessage. These interfaces offer an implementation-agnostic framework for enabling custom servers to consume messages within B2Bi.

The following sections provide more details about the interfaces. For detailed implementation details of each interface, see the Swagger API Javadoc for each class.

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

PluggableServer

The PluggableServer interface defines methods for the trading engine to generically run custom embedded servers. B2Bi has no knowledge of the actual communication protocol the embedded server runs. The interface defines methods such as:

  • init()
  • start()
  • stop()
  • systemThrottleEngaged()
  • systemThrottleDisengaged()

PluggableServer implementations are created and called by B2Bi at runtime.

PluggableMessage

The PluggableMessage interface stores information about the messages to be processed by B2Bi. You can set the payload data as well as metadata about the payload.

A message object may only have one payload, which must be set by the PluggableServer.

The PluggableMessage class exposes the payload through a mechanism called VirtualData, which is a payload file wrapper. VirtualData provides complete access and control of the payload file, but adds a layer of extraction that enables B2Bi to add in-memory caching, streaming and backup-directory management. Although the file can be accessed directly, we strongly recommended using VirtualData.

As a message is processed, it is continuously loaded with additional information about the payload and the context in which it has been processed. This information is called metadata. The PluggableMessage object offers setters and getters for string-based metadata. Each metadata item has a name and a value. These are stored in an accessible map. The name values are defined by two Java interfaces:

  • com.cyclonecommerce.collaboration.MetadataDictionary
  • com.cyclonecommerce.webservices.collaboration.ebxml.EbxmlMetadataDictionary

Runtime behavior

Pluggable servers are hosted and run within B2Bi cluster framework. For each defined pluggable server, one instance of it is created and run per host in the cluster. For example, in a two-host cluster, each host starts an instance of the pluggable server. However, for a cluster of two processing nodes on the same host, one node launches the pluggable server, but the other node does not. If the node hosting the pluggable server fails, the second node starts the pluggable server.

The PluggableServer interface has a stop() method, but it is important to know that there is no guarantee the method will be called. If B2Bi server stops or a processing node dies, the stop() method is not called. Although the JVM running the pluggable server is killed, if the PluggableServer is running in a separate process, and the start() and stop() methods are relied on to start and stop that external process, the stop() method cannot be guaranteed to be called.

Implementing a pluggable server

A developer must implement the pluggable server interface defined in com.cyclonecommerce.tradingengine.transport.pluggable.api.PluggableServer.

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

The following are the general steps for implementing a pluggable server:

  1. Determine the parameters necessary to configure the pluggable server. These parameters are entered in the user interface and passed in the initialization method of the pluggable server.
  2. Implement the PluggableServer interface. The implementation must be able to handle the notification from B2Bi system throttle. The system throttle prevents the B2Bi trading engine from taking on too much work when resources are low.
  3. Implement the Java interface for PluggableMessage. B2Bi has a simple implementation of this interface within com.cyclonecommerce.tradingengine.transport.pluggable.PluggableMessageImpl.
  4. When the custom server implementation needs to take a message and submit it to B2Bi trading engine for processing, there is a class with a static method for facilitating this for pluggable servers. The class is com.cyclonecommerce.tradingengine.transport.pluggable.api.PluggableServerAPI. See the API Javadoc for information on how to use this class.

Configuring a pluggable server

The pluggable server configuration is performed in the user interface. The UI allows defining the full class name to instantiate the custom pluggable server. Name-value pairs of configuration data for the pluggable server also can be entered. These values are passed into the init() method of the pluggable server as a java.util.Properties object.

Configure an application pickup

Follow these steps to configure an application pickup:

  1. On the summary page for a community profile, click Application pickup on the navigation graphic at the top of the page.
  2. Click Add an application pickup to open the delivery exchange wizard.
  3. On the Choose transport protocol page, select Pluggable server and click Next.
  4. Enter the additional information as prompted, such as the From Address and the To Address, the directory path for the message exchange, and a name for the new exchange.
  5. Click the Finish button.

Configure an application delivery

Follow these steps to configure an application delivery:

  1. On the summary page for a community profile, click Application delivery on the navigation graphic at the top of the page.
  2. Click Add an application delivery to open the delivery exchange wizard.
  3. On the Choose transport protocol page, select Pluggable server and click Next.
  4. Enter the additional information as prompted, such as the directory path for the message exchange and a name for the new exchange.
  5. Click the Finish button.

Pluggable server example

An example pluggable server implementation — PluggableServerExample.java — is included in the SDK. The example class is located at sdk/java-src/examples/transport.

This example is a basic server example for monitoring a file system directory for files. Any file found in that directory is submitted to B2Bi.

Note   This is just an example of a pluggable server. It is not designed to handle real consumption of files from a file system.

Related topics

Related Links