Startup services

The extensible architecture of the B2Bi trading engine enables developers to configure tasks that are called during startup of B2Bi server. This provides an access point for running custom code during the startup sequence without changing the base code. Startup services can perform one-time initialization or launch background threads that periodically wake up and do something useful. Startup services allow custom processing logic independent of a message processing context.

Startup services are implementations of the Java interface named StartupService. They are essentially hooks to perform whatever setup is required for a node, which is an instance of a Java Virtual Machine.

There are two types of nodes:

  • The control node hosts the user interface, and
  • The trading engine node hosts message processing.

Depending on the license, there may be zero or more trading engine nodes in the cluster and on any given machine. The conf/license.xml file specifies the maximum number of nodes allowed.

Uses for startup services include:

  • Kick off background process to periodically reload configuration files used by other custom modifications.
  • Periodically purge old database and or file system data.
  • Monitor system processes for failure conditions.
  • Generate reports.
  • Initiate back-end application synchronization tasks.

Runtime use of startup services

The following describes how startup services are called at runtime. For detailed information on each method, see the API Javadoc.

Startup services are an implementation of the Java interface named StartupService. Zero or more StartupService implementations can be configured for any node type in the startup.xml file in <install directory>/conf.

All startup services for a given node type are started in every node of that type. During startup, each node assembles a list of all startup services for its node type. For each startup service in the list, the node:

  • Dynamically instantiates an instance of the configured StartupService implementation. (The StartupService class must provide a default constructor.)
  • Calls init(), passing the parameter configured for that startup service.
  • Calls start().

It is important to note that some system or user-defined startup services can spawn background processes that have not yet initialized or have finished initializing but have begun processing documents. There is no mechanism to synchronize startup services before a node begins processing.

There are three ways a node can be stopped:

  • A node crashes,
  • The StartupService.stop() method is called only when a user stops or deletes a node, or
  • Other situations cause the JVM to abruptly terminate.

Implement a startup service task

A developer must implement the startup service interface defined in com.cyclonecommerce.clustercontroller.StartupService.

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

The following are the general steps to implement a startup service:

  1. Determine the required logic. Note that a startup service runs on all nodes of the same type, and it is not guaranteed that all system-level startup services will have finished.
  2. Create a Java class that implements the StartupService interface. Use the string passed to the init() method as an optional configuration parameter.
  3. Deploy the new StartupService to the example classes by copying the JAR file you create to <B2Bi_install_directory>/Interchange/jars <install_directory>/Activator/jars. Any files in this directory are automatically added to the classpath at startup.

Java does not support dynamic reloading of Java classes. Therefore, restart B2Bi server after recompiling the startup service.

Add a startup service

To add a startup service to B2Bi, add the configuration to the startup.xml file. The following is an example of the file contents:

<Startup>

<CN>

<!--<Service class="com.acme.myControlNodeStartupService" param="abc"/>-->

</CN>

<TE>

<!--<Service class=".acme.myTradingEngineStartupService" param="123"/>-->

</TE>

<TX>

<!--<Service class=".acme.myTransactionDirectorStartupService" />-->

</TX>

</Startup>

The example PeriodicHello class demonstrates a startup service. To run the example, add the following element inside the node you are editing: <Service class="examples.startup.PeriodicHello" param="5"/>.

This starts the PeriodicHello service and logs "Hello World" every 5 seconds.

If you add the PeriodicHello service to the CN node, the resulting file is:

<Startup>

<CN>

<Service class="examples.startup.PeriodicHello" param="5"/>

</CN>

<TE>

<!--<Service class=".acme.myTradingEngineStartupService"

param="123"/>-->

</TE>

<TX>

<!--<Service class=".acme.myTransactionDirectorStartupService" />-->

</TX>

</Startup>

To run the example OneTimeHello service, add the following element inside the node you are editing: <Service class="examples.startup.OneTimeHello"/>.

This starts the OneTimeHello service and logs "Hello World" once.

For more information about the example 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