Order Router

Overview

Ember provides several APIs to customize default behavior. One of them is the Order Router. This component is responsible for selecting the destination for trading requests that arrive to the Order Management System (OMS).

The diagram below illustrates the role of the Order Router in Ember's OMS:

Here are some key characteristics of the Order Router:

• Performant: The Order Router is part of the Ember OMS service. This API is called from the OMS request processing thread. Its implementation must be fast and non-blocking to ensure efficient order routing.
• Deterministic: The Order Router must be deterministic. Its decisions are not stored in the Ember Journal, as inbound messages are stored in the journal before the OMS processes them.
• Immutable: The Order Router applies to OrderNewRequests. Once a destination for an order is established, it is cached in the Ember order state. As a result, all subsequent requests for the same order, such as order modification and cancellation requests, will be routed to the same destination.

API

API is very simple, given original order submission request and internal order representation (with all set of attributes) custom implementation must return order destination ID. Here as in many other cases in Ember, the API uses ALPHANUMERIC(10) to identify destination. See Trading Data Model for more information about Source/Destination identification and ALPHANUMERIC(10) encoding.

/**
 * Customizable function that runs inside Ember OMS thread to determine order destination.
 * Warning: implementation must be deterministic. 
 *          Routing decisions should be based on order information and static configuration.
 * After system restart this component should re-route historical orders to the same destinations.
 */
public interface OrderRouter {

    /**
     * @param request original order request
     * @param order Ember OMS state kept for new order (usually derived from request)
     * @return order destination or {@link deltix.anvil.util.TypeConstants#ALPHANUMERIC_NULL} */
    @Alphanumeric
    long getServiceId(OrderNewRequest request, Order order) throws RouteException;  
}

API Contact

• Implementation may return TypeConstants.ALPHANUMERIC_NULL. In which case order will be automatically rejected with “No destination” reject reason.
• Ember will automatically store destination provided by Order Router in Order state object.
• Implementation is discouraged from modifying any attributes of input request or order object.
• OrderRouter API is not suitable to re-route Order Replace and Order Cancel requests. Use Request Transformer API for this purpose.

Sample

Here is a sample implementation of an Order Router in Java:

class SimpleOrderRouter implements OrderRouter {

    private final @Alphanumeric long defaultDestination;

    SimpleOrderRouter(long defaultDestination) {
        this.defaultDestination = defaultDestination;
    }

    @Override
    @Alphanumeric
    public long getServiceId(OrderNewRequest request, Order order) throws RouteException {
        @Alphanumeric long result = order.getDestinationId();
        if (result == TypeConstants.ALPHANUMERIC_NULL)
            result = order.getExchangeId();
        return (result == TypeConstants.ALPHANUMERIC_NULL) ? defaultDestination : result;
    }
}

In this implementation, the SimpleOrderRouter class implements the OrderRouter interface. It takes a defaultDestination value in the constructor, which represents the default destination for trading requests.

The getServiceId() method is responsible for determining the service ID (destination) for a OrderNewRequest. It first checks if the order has a specific destination ID set. If not, it falls back to using the exchange ID as the destination. If neither is available, it returns the default destination.

This is a simplified example to demonstrate the basic functionality of an Order Router. Actual implementations may vary based on specific requirements and business logic.

Deployment of a Custom Order Router

To deploy a custom Order Router in Ember, you need to specify it in the Ember configuration file.

Here is an example:

engine.router {
  factory = "deltix.ember.service.engine.router.SimpleOrderRouterFactory"
  settings {
    defaultDestination = SIMULATOR  
  }
}

In this configuration snippet, the engine.router section defines the settings for the Order Router. The factory parameter specifies the fully qualified name of the factory class responsible for creating the Order Router instance.

The settings block contains additional configuration options specific to the custom Order Router. In this example, the defaultDestination parameter is set to SIMULATOR, which represents the default destination for trading requests.

Refer to the Ember Configuration Guide for more detailed information on Ember's configuration options and how to customize them.

Predefined Order Routers

Ember provides several predefined Order Router implementations that you can use out-of-the-box.

Here are some examples:

• deltix.ember.service.engine.router.DefaultOrderRouterFactory

  • Ember uses this Order Router by default.
  • Routing preference:
    1. Order destination (if specified)
    2. Broker ID defined in the security metadata for the order symbol

• deltix.ember.service.engine.router.SimpleOrderRouterFactory

  • This is another out-of-the box Order Router implementation.
  • Routing preference:
    1. Order destination (if specified)
    2. Order exchange (if specified)
    3. Default destination

• deltix.ember.service.engine.router.custom.TraderGroupOrderRouterFactory

  • A custom Order Router factory that you can use to implement your own routing logic specific to trader groups.

note

Changing the Order Router on a production system may result in a change of system behavior.

All historical trading requests that relied on previous routing destinations will be routed according to the new router logic after a restart.