#138, #219 Reference resolution improvements. (#551)

Co-authored-by: andreas Halberkamp <andreas.halberkamp@commercetools.de>

Author: ahmetoz

README.md

@@ -2,9 +2,9 @@
 # commercetools sync
 [![Build Status](https://travis-ci.org/commercetools/commercetools-sync-java.svg?branch=master)](https://travis-ci.org/commercetools/commercetools-sync-java)
 [![codecov](https://codecov.io/gh/commercetools/commercetools-sync-java/branch/master/graph/badge.svg)](https://codecov.io/gh/commercetools/commercetools-sync-java)
-[![Benchmarks 1.9.1](https://img.shields.io/badge/Benchmarks-1.9.1-orange.svg)](https://commercetools.github.io/commercetools-sync-java/benchmarks/)
+[![Benchmarks 2.0.0](https://img.shields.io/badge/Benchmarks-2.0.0-orange.svg)](https://commercetools.github.io/commercetools-sync-java/benchmarks/)
 [![Download](https://api.bintray.com/packages/commercetools/maven/commercetools-sync-java/images/download.svg) ](https://bintray.com/commercetools/maven/commercetools-sync-java/_latestVersion)
-[![Javadoc](http://javadoc-badge.appspot.com/com.commercetools/commercetools-sync-java.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/1.9.1/)
+[![Javadoc](http://javadoc-badge.appspot.com/com.commercetools/commercetools-sync-java.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/)
 [![Known Vulnerabilities](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646/badge.svg)](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646)
 
 More at https://commercetools.github.io/commercetools-sync-java
@@ -36,7 +36,7 @@ The library supports synchronising the following entities in commercetools
     - [Ivy](#ivy)
 - [Roadmap](#roadmap)
 - [Release Notes](/docs/RELEASE_NOTES.md)
-- [Javadoc](https://commercetools.github.io/commercetools-sync-java/v/1.9.1/)
+- [Javadoc](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/)
 - [Benchmarks](https://commercetools.github.io/commercetools-sync-java/benchmarks/)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -78,26 +78,26 @@ Here are the most popular ones:
 <dependency>
   <groupId>com.commercetools</groupId>
   <artifactId>commercetools-sync-java</artifactId>
-  <version>1.9.1</version>
+  <version>2.0.0</version>
 </dependency>
 ````
 
 #### Gradle
 
 ````groovy
-implementation 'com.commercetools:commercetools-sync-java:1.9.1'
+implementation 'com.commercetools:commercetools-sync-java:2.0.0'
 ````
 
 #### SBT 
 
 ````
-libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "1.9.1"
+libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "2.0.0"
 ````
 
 #### Ivy 
 
 ````xml
-<dependency org="com.commercetools" name="commercetools-sync-java" rev="1.9.1"/>
+<dependency org="com.commercetools" name="commercetools-sync-java" rev="2.0.0"/>
 ````
 
 

docs/README.md

@@ -2,9 +2,9 @@
 # commercetools sync
 [![Build Status](https://travis-ci.org/commercetools/commercetools-sync-java.svg?branch=master)](https://travis-ci.org/commercetools/commercetools-sync-java)
 [![codecov](https://codecov.io/gh/commercetools/commercetools-sync-java/branch/master/graph/badge.svg)](https://codecov.io/gh/commercetools/commercetools-sync-java)
-[![Benchmarks 1.9.1](https://img.shields.io/badge/Benchmarks-1.9.1-orange.svg)](https://commercetools.github.io/commercetools-sync-java/benchmarks/)
+[![Benchmarks 2.0.0](https://img.shields.io/badge/Benchmarks-2.0.0-orange.svg)](https://commercetools.github.io/commercetools-sync-java/benchmarks/)
 [![Download](https://api.bintray.com/packages/commercetools/maven/commercetools-sync-java/images/download.svg) ](https://bintray.com/commercetools/maven/commercetools-sync-java/_latestVersion)
-[![Javadoc](http://javadoc-badge.appspot.com/com.commercetools/commercetools-sync-java.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/1.9.1/)
+[![Javadoc](http://javadoc-badge.appspot.com/com.commercetools/commercetools-sync-java.svg?label=Javadoc)](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/)
 [![Known Vulnerabilities](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646/badge.svg)](https://snyk.io/test/github/commercetools/commercetools-sync-java/4b2e26113d591bda158217c5dc1cf80a88665646)
 
 
@@ -55,18 +55,18 @@ Here are the most popular ones:
 <dependency>
   <groupId>com.commercetools</groupId>
   <artifactId>commercetools-sync-java</artifactId>
-  <version>1.9.1</version>
+  <version>2.0.0</version>
 </dependency>
 ````
 #### Gradle
 ````groovy
-implementation 'com.commercetools:commercetools-sync-java:1.9.1'
+implementation 'com.commercetools:commercetools-sync-java:2.0.0'
 ````
 #### SBT 
 ````
-libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "1.9.1"
+libraryDependencies += "com.commercetools" % "commercetools-sync-java" % "2.0.0"
 ````
 #### Ivy 
 ````xml
-<dependency org="com.commercetools" name="commercetools-sync-java" rev="1.9.1"/>
+<dependency org="com.commercetools" name="commercetools-sync-java" rev="2.0.0"/>
 ````

docs/RELEASE_NOTES.md

@@ -33,18 +33,38 @@
 [Commits](https://github.com/commercetools/commercetools-sync-java/compare/2.0.0...2.0.1) |
 [Javadoc](https://commercetools.github.io/commercetools-sync-java/v/2.0.1/) | 
 [Jar](https://bintray.com/commercetools/maven/commercetools-sync-java/2.0.1)
--->
+  
+--> 
 
-<!--### 2.0.0 -  Aug 21, 2020
+### 2.0.0 - Sept 14, 2020
 [Commits](https://github.com/commercetools/commercetools-sync-java/compare/1.9.1...2.0.0) |
 [Javadoc](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/) | 
 [Jar](https://bintray.com/commercetools/maven/commercetools-sync-java/2.0.0)
 
-- 🚧 **Breaking Changes** (1)
-    - **Refactoring of the error- and warning callbacks** - The signatures of the error- and warning callbacks was changed.
-        From now on the resource draft of the source project, the resource of the target-project and optinally the failed update actions
-        are passed to the callbacks. [#107](https://github.com/commercetools/commercetools-sync-java/issues/107)
--->
+- 🚧 **Breaking Changes** (2)
+    - Sync options:
+        - The signatures of the `errorCallback` and `warningCallback` changed and their parameter lists are extended.
+            From now on the resource draft of the source project, the resource of the target project and optionally the failed update actions
+            passed to the callbacks. Refer [sync options](./usage/SYNC_OPTIONS.md) for more details. [#107](https://github.com/commercetools/commercetools-sync-java/issues/107)
+    - Reference resolution utilities:
+        - **Commons** - Renamed `replaceCustomTypeIdWithKeys` to `mapToCustomFieldsDraft`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)
+        - **Commons** - Renamed `replaceAssetsReferencesIdsWithKeys` to `mapToAssetDrafts`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)
+        - **Category Sync** - Renamed `replaceCategoriesReferenceIdsWithKeys` to `mapToCategoryDrafts`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)
+        - **CartDiscount Sync** - Renamed `replaceCartDiscountsReferenceIdsWithKeys` to `mapToCartDiscountDrafts`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)
+        - **Inventory Sync** - Renamed `replaceInventoriesReferenceIdsWithKeys` to `mapToInventoryEntryDrafts`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)     
+        - **Product Sync** - Renamed `replaceProductsReferenceIdsWithKeys` to `mapToProductDrafts`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)
+        - **State Sync** - Renamed `replaceStateReferenceIdsWithKeys` to `mapToStateDrafts`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)
+        - **ProductType Sync** - Renamed `replaceProductTypesReferenceIdsWithKeys` to `mapToProductTypeDrafts`. [#138](https://github.com/commercetools/commercetools-sync-java/issues/138)
+
+- ✨ **Enhancements** (1)        
+    -  The library will fail fast for the non-existing references that found during the reference resolution. [#219](https://github.com/commercetools/commercetools-sync-java/issues/219)
+
+- 🛠️ **Dependency Updates** (4)
+    - `commercetools-jvm-sdk` `1.52.0` -> [`1.53.0`](http://commercetools.github.io/commercetools-jvm-sdk/apidocs/io/sphere/sdk/meta/ReleaseNotes.html#v1_53_0)
+    - `org.assertj.assertj-core` `3.16.0` ->  [`3.17.2`](https://assertj.github.io/doc/#assertj-core-3-17-2-release-notes)
+    - `junit.jupiterApiVersion` `5.6.2` ->  [`5.7.0`](https://github.com/junit-team/junit5/releases/tag/r5.7.0)
+    - `mockito-junit-jupiter` `3.4.4` -> [`3.5.10`](https://github.com/mockito/mockito/releases/tag/v3.5.10)
+    - `com.github.ben-manes.versions` `0.29.0` -> [`0.33.0`](https://github.com/ben-manes/gradle-versions-plugin/releases/tag/v0.33.0) 
 
 ### 1.9.1 -  Aug 5, 2020
 [Commits](https://github.com/commercetools/commercetools-sync-java/compare/1.9.0...1.9.1) |

docs/usage/CART_DISCOUNT_SYNC.md

@@ -28,24 +28,19 @@ against a [CartDiscountDraft](https://docs.commercetools.com/http-api-projects-c
 cart discounts in the target CTP project. Also, the cart discounts in the target project are expected to have the `key`
 fields set, otherwise they won't be matched.
 
-2. Every cartDiscount may have a reference to the `Type` of its custom fields. Types are matched by their `key`s. 
-Therefore, in order for the sync to resolve the actual ids of those references in the target project, the `key` of the 
-`Type` has to be supplied in the following way:
-    
-    - Provide the `key` **value** on the `id` field of the reference. This means that calling `getId()` on the
-    reference should return its `key`.
-
-   **Note**: When syncing from a source commercetools project, you can use this util which this library provides:
-    [`replaceCartDiscountsReferenceIdsWithKeys`](https://commercetools.github.io/commercetools-sync-java/v/1.9.1/com/commercetools/sync/cartdiscounts/utils/CartDiscountReferenceReplacementUtils.html#replaceCartDiscountsReferenceIdsWithKeys-java.util.List-)
-    that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:
+2. Every cartDiscount may have a reference to the `Type` of its custom fields. 
+Types are matched by their `key`s. Therefore, in order for the sync to resolve the 
+actual ids of the type reference, the `key` of the `Type` has to be supplied.
+
+   - When syncing from a source commercetools project, you can use [`mapToCartDiscountDrafts`](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/com/commercetools/sync/cartdiscounts/utils/CartDiscountReferenceResolutionUtils.html#mapToCartDiscountDrafts-java.util.List-)
+    method that maps from a `CartDiscount` to `CartDiscountDraft` in order to make them ready for reference resolution by the sync:
     ````java
-    // Puts the keys in the reference id fields to prepare for reference resolution
-    final List<CartDiscountDraft> cartDiscountDrafts = replaceCartDiscountsReferenceIdsWithKeys(cartDiscounts);
+    final List<CartDiscountDraft> cartDiscountDrafts = CartDiscountReferenceResolutionUtils.mapToCartDiscountDrafts(cartDiscounts);
     ````
 
 3. Create a `sphereClient` [as described here](IMPORTANT_USAGE_TIPS.md#sphereclient-creation).
 
-4. After the `sphereClient` is set up, a `CartDiscountSyncOptions` should be be built as follows:
+4. After the `sphereClient` is set up, a `CartDiscountSyncOptions` should be built as follows:
 ````java
 // instantiating a CartDiscountSyncOptions
 final CartDiscountSyncOptions cartDiscountSyncOptions = CartDiscountSyncOptionsBuilder.of(sphereClient).build();

docs/usage/CATEGORY_SYNC.md

@@ -30,22 +30,16 @@ against a [CategoryDraft](https://docs.commercetools.com/http-api-projects-categ
 categories in the target CTP project. Also, the categories in the target project are expected to have the `key` fields set,
 otherwise they won't be matched.
 
-2. Every category may have a reference to a `parent category` and a reference to the `Type` of its custom fields. Categories 
-   and Types are matched by their `key`s. Therefore, in order for the sync to resolve the 
-    actual ids of those references, the `key` of the `Type`/parent `Category` has to be supplied in the following way:
-    - Provide the `key` value on the `id` field of the reference. This means that calling `getId()` on the
-    reference would return its `key`.  
-
-   **Note**: When syncing from a source commercetools project, you can use this util which this library provides: 
-    [`replaceCategoriesReferenceIdsWithKeys`](https://commercetools.github.io/commercetools-sync-java/v/1.9.1/com/commercetools/sync/categories/utils/CategoryReferenceReplacementUtils.html#replaceCategoriesReferenceIdsWithKeys-java.util.List-)
-    that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:
-    ````java
-    // Puts the keys in the reference id fields to prepare for reference resolution
-    final List<CategoryDraft> categoryDrafts = replaceCategoriesReferenceIdsWithKeys(categories);
-    ````
-     
-   Example of its usage can be found [here](https://github.com/commercetools/commercetools-sync-java/tree/master/src/integration-test/java/com/commercetools/sync/integration/ctpprojectsource/categories/CategorySyncIT.java#L130).
-
+2. Every category may have a reference to a `parent category` and a reference to the `Type` of its custom fields. 
+These references are matched by their `key`s. Therefore, in order for the sync to resolve the 
+actual ids of the references, their `key`s has to be supplied.
+ 
+   - When syncing from a source commercetools project, you can use [`mapToCategoryDrafts`](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/com/commercetools/sync/categories/utils/CategoryReferenceResolutionUtils.html#mapToCategoryDrafts-java.util.List-)
+     method that maps from a `Category` to `CategoryDraft` in order to make them ready for reference resolution by the sync:
+     ````java     
+     final List<CategoryDraft> categoryDrafts = CategoryReferenceResolutionUtils.mapToCategoryDrafts(categories);
+     ````
+  
 3. Create a `sphereClient` [as described here](IMPORTANT_USAGE_TIPS.md#sphereclient-creation).
 
 4. After the `sphereClient` is set up, a `CategorySyncOptions` should be built as follows: 

docs/usage/IMPORTANT_USAGE_TIPS.md

@@ -31,7 +31,7 @@ productSync.sync(batch1)
 By design, scaling the sync process should **not** be done by executing the batches themselves in parallel. However, it can be done either by:
 
  - Changing the number of [max parallel requests](https://github.com/commercetools/commercetools-sync-java/tree/master/src/main/java/com/commercetools/sync/commons/utils/ClientConfigurationUtils.java#L116) within the `sphereClient` configuration. It defines how many requests the client can execute in parallel.
- - or changing the draft [batch size](https://commercetools.github.io/commercetools-sync-java/v/1.9.1/com/commercetools/sync/commons/BaseSyncOptionsBuilder.html#batchSize-int-). It defines how many drafts can one batch contain.
+ - or changing the draft [batch size](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/com/commercetools/sync/commons/BaseSyncOptionsBuilder.html#batchSize-int-). It defines how many drafts can one batch contain.
 
 The current overridable default [configuration](https://github.com/commercetools/commercetools-sync-java/tree/master/src/main/java/com/commercetools/sync/commons/utils/ClientConfigurationUtils.java#L45) of the `sphereClient` 
 is the recommended good balance for stability and performance for the sync process.

docs/usage/INVENTORY_SYNC.md

@@ -30,21 +30,17 @@ against a [InventoryEntryDraft](https://docs.commercetools.com/http-api-projects
 
 2. Every inventory entry may have a reference to a supply `Channel` and a reference to the `Type` of its custom fields. These
    references are matched by their `key`s. Therefore, in order for the sync to resolve the actual ids of those references,
-   their `key`s has to be supplied in the following way:
-   - Provide the `key` value on the `id` field of the reference. This means that calling `getId()` on the
-   reference would return its `key`. 
-     
-        **Note**: When syncing from a source commercetools project, you can use this util which this library provides: 
-         [`replaceInventoriesReferenceIdsWithKeys`](https://commercetools.github.io/commercetools-sync-java/v/1.9.1/com/commercetools/sync/inventories/utils/InventoryReferenceReplacementUtils.html#replaceInventoriesReferenceIdsWithKeys-java.util.List-)
-         that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:
-         ````java
-         // Puts the keys in the reference id fields to prepare for reference resolution
-         final List<InventoryEntryDraft> inventoryEntryDrafts = replaceInventoriesReferenceIdsWithKeys(inventoryEntries);
-         ````
+   their `key`s has to be supplied.
+   
+   - When syncing from a source commercetools project, you can use [`mapToInventoryEntryDrafts`](https://commercetools.github.io/commercetools-sync-java/v/2.0.0/com/commercetools/sync/inventories/utils/InventoryReferenceResolutionUtils.html#mapToInventoryEntryDrafts-java.util.List-)
+     method that that maps from a `InventoryEntry` to `InventoryEntryDraft` in order to make them ready for reference resolution by the sync:
+     ````java
+     final List<InventoryEntryDraft> inventoryEntryDrafts = InventoryReferenceResolutionUtils.mapToInventoryEntryDrafts(inventoryEntries);
+     ````
 
 3. Create a `sphereClient` [as described here](IMPORTANT_USAGE_TIPS.md#sphereclient-creation).
 
-4. After the `sphereClient` is setup, a `InventorySyncOptions` should be be built as follows: 
+4. After the `sphereClient` is setup, a `InventorySyncOptions` should be built as follows: 
 ````java
 // instantiating a InventorySyncOptions
 final InventorySyncOptions inventorySyncOptions = InventorySyncOptionsBuilder.of(sphereClient).build();