# 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](../fx-integration-api/fxapi-upgrade-guide-v2-to-v3.md).

## 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

## 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,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/BuySell.html)` | icon:arrow-right[] | `[com.caplin.motif.fx.trading.BuySell,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/fx/trading/BuySell.html)` |
| `[com.caplin.motif.fx.Tenor,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/Tenor.html)` | icon:arrow-right[] | `[com.caplin.motif.fx.common.Tenor,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/fx/common/Tenor.html)` |
| `[com.caplin.motif.fx.trading.rfs.RFSTrade,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/rfs/RFSTrade.html)` | icon:arrow-right[] | `[com.caplin.generated.motif.fx.trading.rfs.RFSTrade,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/rfs/RFSTrade.html)` |

**❗ IMPORTANT**\
A number of internal classes in the FX Integration API 2 have been relocated to the `[com.caplin.motif,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/package-summary.html)` 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,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/esp/package-summary.html)` | icon:arrow-right[] | `[com.caplin.generated.motif.fx.trading.rfs,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/rfs/package-summary.html)` |
| `[com.caplin.motif.fx.trading.esp,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/esp/package-summary.html)` | icon:arrow-right[] | `[com.caplin.generated.motif.fx.trading.esp,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/esp/package-summary.html)` |

For more information about the new generated RFS and ESP Trading API, see [Trading API](../fx-integration-api/fxapi-upgrade-guide-v2-to-v3.md#trading-api) in the [FX Integration API v2 to v3 upgrade guide](../fx-integration-api/fxapi-upgrade-guide-v2-to-v3.md).

### New inheritance model

The FX Integration API v3 classes [`ESPTrade`,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/esp/ESPTrade.html), [`RFSTrade`,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/rfs/RFSTrade.html), and [`BlockTrade`,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/fx/trading/block/BlockTrade.html) now inherit from `[com.caplin.motif.UserTrade,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/UserTrade.html)` instead of `[com.caplin.motif.fx.trading.FXTrade,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/FXTrade.html)`, 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,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/rfs/events/client/SubmitTradeEvent.html)`).
* 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,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/rfs/events/client/SubmitTradeEvent.html)`:

  ```java
  public void onSubmit(final SubmitTradeEvent submitEvent) {
      submitEvent.getLegById(1);
      if (submitEvent.isSwap()) {
          submitEvent.getLegById(2);
      }
  }
  ```

  **📌 NOTE**\
  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,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/FXExecutionTradeLeg.html)` | icon:arrow-right[] | To retrieve trade legs, use the `getLegById(int)` method on the standard trade event classes. For example, `[SubmitTradeEvent.getLegById(int),opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/generated/motif/fx/trading/rfs/events/client/SubmitTradeEvent.html)`. |
| `[com.caplin.motif.fx.rates.QuoteBuilder,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/rates/QuoteBuilder.html)` | icon:arrow-right[] | For information and examples on building quotes using the FX Integration API 3, see [Rates](../fx-integration-api/fxapi-upgrade-guide-v2-to-v3.md#rates) and [Code examples](../fx-integration-api/fxapi-upgrade-guide-v2-to-v3.md#code-examples) in the [FX Integration API v2 to v3 Upgrade Guide](../fx-integration-api/fxapi-upgrade-guide-v2-to-v3.md). |

**RET Adapter Toolkit**

| RET Adapter Toolkit v2 |  | RET Adapter Toolkit v3 |
| --- | --- | --- |
| `[com.caplin.motif.fx.ret.fxtrading.extension.quote.QuoteBuilderFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/2/com/caplin/motif/fx/ret/fxtrading/extension/quote/QuoteBuilderFactory.html)` | icon:arrow-right[] | The constructors for the following RET Adapter Toolkit factories no longer take a `[QuoteBuilderFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/2/com/caplin/motif/fx/ret/fxtrading/extension/quote/QuoteBuilderFactory.html)` object in their constructor: `[DefaultQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultQuoteFactory.html)`, `[DefaultBlockQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultBlockQuoteFactory.html)`, `[DefaultSwapQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultSwapQuoteFactory.html)`, `[DefaultSalesQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultSalesQuoteFactory.html)`, and `[DefaultSalesSwapQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultSalesQuoteFactory.html)`. |

### Changed method signatures

The following method signatures have changed:

**RET Adapter Toolkit**

| RET Adapter Toolkit 2 |  | RET Adapter Toolkit 3 |
| --- | --- | --- |
| `[TradingConnectionRouter.getConnectionKey(FXTrade),opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/2/com/caplin/motif/fx/ret/fxtrading/connection/TradingConnectionRouter.html)` | icon:arrow-right[] | `[TradingConnectionRouter.getConnectionKey(UserTrade),opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/connection/TradingConnectionRouter.html)` |
| `[FxTradingAccountManager.getAccount(FXTrade, …),opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/2/com/caplin/motif/fx/ret/fxtrading/account/FxTradingAccountManager.html)` | icon:arrow-right[] | `[FxTradingAccountManager.getAccount(UserTrade, …),opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/account/FxTradingAccountManager.html)` |

### New method return types

In the FX Integration API v3, quote objects, and quote parts, now implement the `[com.caplin.motif.datasource.Message,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/datasource/Message.html)` interface rather than the `[com.caplin.motif.fx.rates.FXQuote,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/rates/FXQuote.html)` interface.

In accordance with the FX Integration API v3, the following RET Adapter Toolkit quote factory methods now return a `[Message,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/datasource/Message.html)` object instead of an `[FXQuote,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/rates/FXQuote.html)` object:

* `[QuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/quote/QuoteFactory.html).createFwdQuote(…)`, implemented by [`DefaultQuoteFactory`,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultQuoteFactory.html)
* `[QuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/quote/QuoteFactory.html).createSpotQuote(…)`, implemented by [`DefaultQuoteFactory`,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultQuoteFactory.html)
* `[BlockQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/quote/BlockQuoteFactory.html).createBlockQuote(…)`, implemented by [`DefaultBlockQuoteFactory`,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultBlockQuoteFactory.html)
* `[SwapQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/quote/SwapQuoteFactory.html).createSwapQuote(…)`, implemented by [`DefaultSwapQuoteFactory`,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultSwapQuoteFactory.html)
* `[SalesQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/quote/SalesQuoteFactory.html).createSalesFwdQuote(…)`, implemented by [`DefaultSalesQuoteFactory`,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultSalesQuoteFactory.html)
* `[SalesQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/quote/SalesQuoteFactory.html).createSalesSpotQuote(…)`, implemented by [`DefaultSalesQuoteFactory`,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultSalesQuoteFactory.html)
* `[SalesSwapQuoteFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/quote/SalesSwapQuoteFactory.html).createSalesSwapQuote(…)`, implemented by [`DefaultSalesSwapQuoteFactory`,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/extension/quote/DefaultSalesSwapQuoteFactory.html)

### com.motif.fx.trading.FXTradingType

The definition of `[com.caplin.motif.fx.trading.FXTradingType,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/fx/trading/FXTradingType.html)` has changed over FX Integration API versions:

**Definition of FXTradingType**

| FX integration API 2 |  | FX Integration API 3 |
| --- | --- | --- |
| `[public enum FXTradingType,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/FXTradingType.html)` | icon:arrow-right[] | `[final class FXTradingType,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/fx/trading/FXTradingType.html)` |

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" |

**❗ IMPORTANT**\
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,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/2/com/caplin/motif/fx/ret/fxtrading/submission/rfs/RFSStateEventFactory.html)` | icon:arrow-right[] | `[BlockStateEventFactory,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/submission/block/BlockStateEventFactory.html)` |
| `[RFSStateEvent,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/2/com/caplin/motif/fx/ret/fxtrading/submission/rfs/RFSStateEvent.html)` | icon:arrow-right[] | `[BlockStateEvent,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/submission/block/BlockStateEvent.html)` |
| `[TradeTypeHandler,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/2/com/caplin/motif/fx/ret/fxtrading/submission/rfs/events/TradeTypeHandler.html)` | icon:arrow-right[] | `[BlockHandler,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/submission/block/BlockHandler.html)` |

**FX Integration API**

| FX Integration API 2 |  | FX Integration API 3 |
| --- | --- | --- |
| `[com.caplin.motif.fx.trading.FXTrade,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/FXTrade.html)` | icon:arrow-right[] | `[com.caplin.motif.UserTrade,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/UserTrade.html)` |

### New classes for ESP and RFS trading

The RET Adapter Toolkit v3 uses the toolkit’s `[RFSStateEvent,opts="nofollow"](https://docs.caplin.com/developer/api/rettoolkit/3/com/caplin/motif/fx/ret/fxtrading/submission/rfs/RFSStateEvent.html)` class in place of the FX Integration API v2 class, `[FXResponder,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/FXResponder.html)`.

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,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/trading/FXTrade.html)` | icon:arrow-right[] | `[com.caplin.motif.UserTrade,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/UserTrade.html)` |
| `[com.caplin.motif.fx.rates.FXQuote,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/2/com/caplin/motif/fx/rates/FXQuote.html)` | icon:arrow-right[] | `[com.caplin.motif.datasource.Message,opts="nofollow"](https://docs.caplin.com/developer/api/fxintegration/3/com/caplin/motif/datasource/Message.html)` |