refactor: codehealth rename types to reflect axis of transformation (#1451)

this is entirely a change for code clarity, because if you read (before
this patch) the `AnyToAnyImporter#import` generic-params you'll see `To`
being passed in as the source of data (what should be a conceptual
"From").

The cause of that confusion is that there's multiple different
orthogonal transformations happening with/around the
`TransferCompatibilityProvider` and its supporting `AnyToAnyImporter`
class and DTP generally:

1. DTP moves data from a Exporter producing models to an Importer
consuming models
1. we have static functions that convert model A to model B (eg: from
Photos model to a Media model via
[`MediaContainerResource::photoToMedia`][pToMedia])
- this is parallel to the `From` and `To` generic params of
[`java.util.function.Function<From, To>`][Function].
1. `TransferCompatibilityProvider` converts *an importer* (via
`AnyToAnyImporter` and a model-transformer like above) from an importer
of one model type to an importer of another model type.

I'm now using the language of "stand-in importer" to indicate which
importer was selected as the input (think the `g` in `f(g(x)`) to
indicate the key moving piece in that last kind of transformation listed
above.

[Function]:
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/function/Function.html
[pToMedia]:
https://github.com/dtinit/data-transfer-project/blob/bca0c7926fb871c7fdd7e206908a87874ec624f2/portability-types-common/src/main/java/org/datatransferproject/types/common/models/media/MediaContainerResource.java#L45

Author: jzacsh

portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/TransferCompatibilityProvider.java

@@ -41,7 +41,7 @@ public Exporter getCompatibleExporter(TransferExtension extension, DataVertical
         break;
     }
     if (exporter == null) {
-      return extension.getExporter(jobType); // preserve original exception
+      return extension.getExporter(jobType); // re-execute just for the potential exception
     }
     return exporter;
   }
@@ -64,25 +64,25 @@ public Importer getCompatibleImporter(TransferExtension extension, DataVertical
         break;
     }
     if (importer == null) {
-      return extension.getImporter(jobType);
+      return extension.getImporter(jobType); // re-execute just for the potential exception
     }
     return importer;
   }
 
   private Importer<?, ?> getVideosImporter(TransferExtension extension) {
-    Importer media = getImporterOrNull(extension, MEDIA);
-    if (media == null) {
+    Importer mediaImporter = getImporterOrNull(extension, MEDIA);
+    if (mediaImporter == null) {
       return null;
     }
-    return new AnyToAnyImporter<>(media, MediaContainerResource::videoToMedia);
+    return new AnyToAnyImporter<>(mediaImporter, MediaContainerResource::videoToMedia);
   }
 
   private Importer<?, ?> getPhotosImporter(TransferExtension extension) {
-    Importer media = getImporterOrNull(extension, MEDIA);
-    if (media == null) {
+    Importer mediaImporter = getImporterOrNull(extension, MEDIA);
+    if (mediaImporter == null) {
       return null;
     }
-    return new AnyToAnyImporter<>(media, MediaContainerResource::photoToMedia);
+    return new AnyToAnyImporter<>(mediaImporter, MediaContainerResource::photoToMedia);
   }
 
   private Importer<?, ?> getMediaImporter(TransferExtension extension) {

portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/converter/AnyToAnyImporter.java

@@ -11,29 +11,61 @@
 /**
  * Allows flexible bridging between adapters of different types with compatible functionality.
  *
- * @param <From> The container type supported by the available exporter.
- * @param <To>   The container type that's desired.
+ * ## Usage
+ *
+ * DTP transfers data by passing models from an Exporter (producing bytes)
+ * to an {@link Importer} (consuming bytes). Models have a 1:1 correspondance to
+ * {@link org.datatransferproject.types.common.models.DataVertical} (so a PHOTO
+ * vertical is universally assumed in the DTP codebase to be used for
+ * PhotosContainerResource transfers).
+ *
+ * ### Example Usage
+ *
+ * Given:
+ *
+ * - a DataVertical.PHOTO transfer
+ * - a matching Exporter: an adapter producing {@link PhotosContainerResource} data
+ * - a stand-in Importer: a good-enough adapter; something intended for a
+ *   semi-compatible but not identical data type (eg: {@link MediaContainerResource}).
+ * - a conversion function to go from said PHOTOS objects to DataVertical.MEDIA
+ *   objects (eg: {@link MediaContainerResource} data).
+ *
+ * Then: one can create a synthetic Importer with this class by constructing with said conversion function.
+ *
+ * @param <StandinImporterType> Container type in which some extant exporter is
+ *     providing data. eg: MediaContainerResource.
+ * @param <ExportingType> The original container type which is being exported
+ *     (that we will convert before arriving at our stand-in importer); eg:
+ *     PhotosContainerResource.
  */
 public class AnyToAnyImporter<
     AD extends AuthData,
-    From extends ContainerResource,
-    To extends ContainerResource> implements Importer<AD, To> {
+    StandinImporterType extends ContainerResource,
+    ExportingType extends ContainerResource> implements Importer<AD, ExportingType> {
 
-  private final Importer<AD, From> importer;
-  private final Function<To, From> converter;
+  private final Importer<AD, StandinImporterType> standinImporter;
+  private final Function<ExportingType, StandinImporterType> modelConverter;
 
   /**
-   * @param importer  existing importer
-   * @param converter function converting between the existing and desired containers.
+   * @param standinImporter  existing importer
+   * @param modelConverter function converting between some existing
+   *    exporters' type to our stand-in importers' container types.
    */
-  public AnyToAnyImporter(Importer<AD, From> importer, Function<To, From> converter) {
-    this.importer = importer;
-    this.converter = converter;
+  public AnyToAnyImporter(
+      Importer<AD, StandinImporterType> standinImporter,
+      Function<ExportingType, StandinImporterType> modelConverter
+    ) {
+    this.standinImporter = standinImporter;
+    this.modelConverter = modelConverter;
   }
 
   @Override
-  public ImportResult importItem(UUID jobId, IdempotentImportExecutor idempotentExecutor,
-      AD authData, To data) throws Exception {
-    return importer.importItem(jobId, idempotentExecutor, authData, converter.apply(data));
+  public ImportResult importItem(
+      UUID jobId,
+      IdempotentImportExecutor idempotentExecutor,
+      AD authData,
+      ExportingType data
+  ) throws Exception {
+    return standinImporter.importItem(jobId, idempotentExecutor, authData, modelConverter.apply(data));
   }
 }