RET Adapter Toolkit upgrade guide: v2 to v3

The document provides guidance on migrating from version 2 to version 3 of the RET Adapter Toolkit.

The RET Adapter Toolkit Version 3 is based on the FX Integration API Version 3. For more information on upgrading to the FX Integration API version 3, see FX Integration API upgrade guide: v2 to v3.

Contents:

Requirements
Breaking changes

Requirements

RET Adapter Toolkit Version 3 requires:

Java:

RET Adapter Toolkit version Supported JVMs (64-bit)

3.12.0

Oracle Java 8 (<= 8u202), Red Hat OpenJDK 8

3.0.0–3.11.0

Oracle Java 8 (<= 8u202)
FX Integration API version 3

RET Adapter Toolkit version	Supported JVMs (64-bit)
3.12.0	Oracle Java 8 (<= 8u202), Red Hat OpenJDK 8
3.0.0–3.11.0	Oracle Java 8 (<= 8u202)

Breaking changes

Breaking changes have been introduced in the following components.

Relocated classes

The following classes have moved to a new location:

FX Integration API
FX Integration API 2		FX Integration API 3
`com.caplin.motif.fx.BuySell`		`com.caplin.motif.fx.trading.BuySell`
`com.caplin.motif.fx.Tenor`		`com.caplin.motif.fx.common.Tenor`
`com.caplin.motif.fx.trading.rfs.RFSTrade`		`com.caplin.generated.motif.fx.trading.rfs.RFSTrade`

A number of internal classes in the FX Integration API 2 have been relocated to the com.caplin.motif package in the FX Integration API 3. Do not use these classes; they are internal classes and may be changed in a later release.

The classes for RFS trading and ESP trading are now generated from trade-model definitions. These generated classes are housed under the com.caplin.generated namespace:

FX Integration API
FX Integration API 2		FX Integration API 3
`com.caplin.motif.fx.trading.rfs`		`com.caplin.generated.motif.fx.trading.rfs`
`com.caplin.motif.fx.trading.esp`		`com.caplin.generated.motif.fx.trading.esp`

For more information about the new generated RFS and ESP Trading API, see Trading API in the FX Integration API v2 to v3 upgrade guide.

New inheritance model

The FX Integration API v3 classes ESPTrade, RFSTrade, and BlockTrade now inherit from com.caplin.motif.UserTrade instead of com.caplin.motif.fx.trading.FXTrade, as they did in the FX Integration API v2.

To access standard fields in a trade, use the standard trade event classes (for example, com.caplin.generated.motif.fx.trading.rfs.events.client.SubmitTradeEvent).
To access the individual legs of a swap, use the getLegById(int) method on the standard trade event classes. See the example below for an RFS SubmitTradeEvent:
```
public void onSubmit(final SubmitTradeEvent submitEvent) {
    submitEvent.getLegById(1);
    if (submitEvent.isSwap()) {
        submitEvent.getLegById(2);
    }
}
```
The isSwap() method is only available on RFS submit events.
To access custom fields in a trade, use UserTrade.getBackingTrade().getField(…)
To access the trading protocol, use UserTrade.getBackingTrade().getFields("TradingProtocol")

Deleted classes

The following FX Integration API 2 classes are no longer included in the FX Integration API 3:

FX Integration API
FX Integration API 2		FX Intregration API 3
`com.caplin.motif.fx.trading.FXExecutionTradeLeg`		To retrieve trade legs, use the `getLegById(int)` method on the standard trade event classes. For example, `SubmitTradeEvent.getLegById(int)`.
`com.caplin.motif.fx.rates.QuoteBuilder`		For information and examples on building quotes using the FX Integration API 3, see Rates and Code examples in the FX Integration API v2 to v3 Upgrade Guide.

RET Adapter Toolkit
RET Adapter Toolkit v2		RET Adapter Toolkit v3
`com.caplin.motif.fx.ret.fxtrading.extension.quote.QuoteBuilderFactory`		The constructors for the following RET Adapter Toolkit factories no longer take a `QuoteBuilderFactory` object in their constructor: `DefaultQuoteFactory`, `DefaultBlockQuoteFactory`, `DefaultSwapQuoteFactory`, `DefaultSalesQuoteFactory`, and `DefaultSalesSwapQuoteFactory`.

Changed method signatures

The following method signatures have changed:

RET Adapter Toolkit
RET Adapter Toolkit 2		RET Adapter Toolkit 3
`TradingConnectionRouter.getConnectionKey(FXTrade)`		`TradingConnectionRouter.getConnectionKey(UserTrade)`
`FxTradingAccountManager.getAccount(FXTrade, …)`		`FxTradingAccountManager.getAccount(UserTrade, …)`

New method return types

In the FX Integration API v3, quote objects, and quote parts, now implement the com.caplin.motif.datasource.Message interface rather than the com.caplin.motif.fx.rates.FXQuote interface.

In accordance with the FX Integration API v3, the following RET Adapter Toolkit quote factory methods now return a Message object instead of an FXQuote object:

QuoteFactory.createFwdQuote(…), implemented by DefaultQuoteFactory
QuoteFactory.createSpotQuote(…), implemented by DefaultQuoteFactory
BlockQuoteFactory.createBlockQuote(…), implemented by DefaultBlockQuoteFactory
SwapQuoteFactory.createSwapQuote(…), implemented by DefaultSwapQuoteFactory
SalesQuoteFactory.createSalesFwdQuote(…), implemented by DefaultSalesQuoteFactory
SalesQuoteFactory.createSalesSpotQuote(…), implemented by DefaultSalesQuoteFactory
SalesSwapQuoteFactory.createSalesSwapQuote(…), implemented by DefaultSalesSwapQuoteFactory

com.motif.fx.trading.FXTradingType

The definition of com.caplin.motif.fx.trading.FXTradingType has changed over FX Integration API versions:

Definition of FXTradingType
FX integration API 2		FX Integration API 3
`public enum FXTradingType`		`final class FXTradingType`

The values for FXTradingType.TIME_OPTION and FXTradingType.FWD have changed in the FX Integration API 3.4:

Change in values
	FX Integration API 2	FX Integration API 3
`FXTradingType.TIME_OPTION`	"TIME OPTION"	"TIME_OPTION"
`FXTradingType.FWD`	"FORWARD"	"FWD"

The new values are disabled by default to maintain compatibility with front-end applications that use the old values. To enable the new values, add the following configuration to the adapter.properties file: use_legacy_trading_types_format=false

New classes for block trading

Block trading uses new classes:

RET Adapter Toolkit
RET Adapter Toolkit 2		RET Adapter Toolkit 3
`RFSStateEventFactory`		`BlockStateEventFactory`
`RFSStateEvent`		`BlockStateEvent`
`TradeTypeHandler`		`BlockHandler`

FX Integration API
FX Integration API 2		FX Integration API 3
`com.caplin.motif.fx.trading.FXTrade`		`com.caplin.motif.UserTrade`

New classes for ESP and RFS trading

The RET Adapter Toolkit v3 uses the toolkit’s RFSStateEvent class in place of the FX Integration API v2 class, FXResponder.

The following classes have changed with the upgrade of the FX Integration API from v2 to v3:

FX Integration API
FX Integration API 2		FX Integration API 3
`com.caplin.motif.fx.trading.FXTrade`		`com.caplin.motif.UserTrade`
`com.caplin.motif.fx.rates.FXQuote`		`com.caplin.motif.datasource.Message`