diff --git a/portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/TransferCompatibilityProvider.java b/portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/TransferCompatibilityProvider.java index 549b82323..1ff7d479c 100644 --- a/portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/TransferCompatibilityProvider.java +++ b/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) { diff --git a/portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/converter/AnyToAnyImporter.java b/portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/converter/AnyToAnyImporter.java index 8e22ea831..72fb92dec 100644 --- a/portability-spi-transfer/src/main/java/org/datatransferproject/spi/transfer/provider/converter/AnyToAnyImporter.java +++ b/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 The container type supported by the available exporter. - * @param 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 Container type in which some extant exporter is + * providing data. eg: MediaContainerResource. + * @param 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 { + StandinImporterType extends ContainerResource, + ExportingType extends ContainerResource> implements Importer { - private final Importer importer; - private final Function converter; + private final Importer standinImporter; + private final Function 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 importer, Function converter) { - this.importer = importer; - this.converter = converter; + public AnyToAnyImporter( + Importer standinImporter, + Function 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)); } }