AmphibianService.java
/*
* Copyright 2019 Global Crop Diversity Trust
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.genesys.server.service;
import java.io.IOException;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import javax.servlet.ServletOutputStream;
import javax.validation.constraints.NotNull;
import org.genesys.amphibian.client.model.DatasetTable;
import org.genesys.amphibian.client.model.FieldFilter;
import org.genesys.amphibian.client.model.HeatMap;
import org.genesys.amphibian.client.model.LongToWide;
import org.genesys.amphibian.client.model.ObservationChart;
import org.genesys.amphibian.client.model.ObservationHistogram;
import org.genesys.amphibian.client.model.Preview;
import org.genesys.amphibian.client.model.PreviewDataFilter;
import org.genesys.amphibian.client.model.ValueMapping;
import org.genesys.filerepository.InvalidRepositoryFileDataException;
import org.genesys.filerepository.InvalidRepositoryPathException;
import org.genesys.filerepository.NoSuchRepositoryFileException;
import org.genesys.filerepository.model.RepositoryFile;
import org.genesys.server.exception.InvalidApiUsageException;
import org.genesys.server.model.dataset.Dataset;
import org.genesys.server.model.genesys.AccessionRef;
import org.genesys.server.model.traits.Descriptor;
import org.genesys.server.service.filter.AccessionFilter;
import org.genesys.server.exception.SearchException;
import org.genesys.server.service.impl.AmphibianServiceImpl;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.web.multipart.MultipartFile;
public interface AmphibianService {
public static class AmphibianNotAvailableException extends InvalidApiUsageException {
private static final long serialVersionUID = 1L;
public AmphibianNotAvailableException() {
super("Amphibian not available");
}
}
public static class NoAccessionsForFilterException extends Exception {
private static final long serialVersionUID = 1L;
public NoAccessionsForFilterException() {
}
}
public static class AmphibianException extends Exception {
private static final long serialVersionUID = 1L;
public AmphibianException() {
}
public AmphibianException(String message) {
super(message);
}
public AmphibianException(String message, Throwable cause) {
super(message, cause);
}
}
final class AccessionsDatasetsDataRequest {
@NotNull
public TraitFilters filters;
public List<String> select;
}
final class TraitFilters {
public AccessionFilter accession;
// UUID -> filter
public Map<String, FieldFilter> observations;
}
/**
* Make a preview of the uploaded spreadsheet file.
*
* @param uuid the uuid
* @param repositoryFile the repository file
* @return the preview
* @throws IOException
* @throws AmphibianException
*/
Preview makePreview(UUID uuid, RepositoryFile repositoryFile) throws IOException, AmphibianException;
/**
* Load preview.
*
* @param uuid the uuid
* @return the preview
* @throws AmphibianException
*/
Preview loadPreview(UUID uuid);
/**
* Remove preview from Amphibian
* @param preview the preview to remove
*/
void deletePreview(Preview preview);
/**
* Gets the preview data.
*
* @param uuid the uuid
* @param sheet the sheet
* @param startRow the start row
* @param count the number of records to return
* @param selectedColumns the selected columns
* @param previewFilter Preview filters
* @return the preview data
* @throws AmphibianException
*/
List<Object> getPreviewData(UUID uuid, int sheet, long startRow, int count, List<String> selectedColumns, PreviewDataFilter previewFilter) throws AmphibianException;
/**
* Gets the analyzed data of selected columns.
*
* @param uuid the uuid
* @param sheet the sheet
* @param startRow the row index where data starts, usually 1
* @param maxDistinct maximum number of distinct values to return
* @param selectedColumns the selected columns
* @return the analyzed data
* @throws AmphibianException
*/
List<?> getStatisticsData(UUID uuid, int sheet, long startRow, int maxDistinct, List<String> selectedColumns) throws AmphibianException;
/**
* Gets the list of repository files from user's amphibian folder.
*
* @return the list of files
* @throws InvalidRepositoryPathException
*/
List<RepositoryFile> myFiles() throws InvalidRepositoryPathException;
/**
* Uploads the dataset file.
*
* @param file the dataset file
* @return
* @throws IOException
* @throws InvalidRepositoryPathException
* @throws InvalidRepositoryFileDataException
* @throws AmphibianException
*/
Preview uploadFile(MultipartFile file) throws IOException, InvalidRepositoryPathException, InvalidRepositoryFileDataException, AmphibianException;
/**
* Updates the content of uploaded dataset file.
*
* @param uuid the uuid of uploaded file
* @param file new content
* @return
* @throws NoSuchRepositoryFileException
* @throws IOException
* @throws AmphibianException
*/
Preview updateFileContent(UUID uuid, MultipartFile file) throws NoSuchRepositoryFileException, IOException, AmphibianException;
/**
* Remove preview file and data
*
* @param uuid
* @throws IOException
* @throws NoSuchRepositoryFileException
* @throws AmphibianException
*/
void deleteFile(UUID uuid) throws IOException, NoSuchRepositoryFileException, AmphibianException;
/**
* Add {@code accessionRef} to rows in Preview as preview row's metadata
* @param uuid
* @param sheet
* @param accessionRefs
* @return Number of Preview rows updated
*/
long addAccessionRefs(UUID uuid, int sheet, List<PreviewAccessionRef> accessionRefs);
public static class PreviewAccessionRef extends AccessionRef<Void> {
private static final long serialVersionUID = -7757091637057598322L;
@NotNull
public Integer row; // Row in the Preview
@Override
public boolean canEqual(Object other) {
return other instanceof PreviewAccessionRef;
}
}
/**
* Test Preview data against Descriptor
* @param uuid
* @param sheet
* @param startAt
* @param field
* @param mapping
* @param descriptor
* @return
*/
Set<?> ingestDryRun(UUID uuid, int sheet, long startAt, String field, String arraySeparator, List<ValueMapping> mapping, Descriptor descriptor);
/**
* Add observations from Preview column to Dataset as Descriptor
* @param dataset Target {@code dataset}
* @param descriptor Descriptor
* @param preview Source {@code preview}
* @param sheet Sheet in source {@code preview}
* @param startRow Start importing data from this row
* @param field Field in {@code preview}
* @param mapping Value mapping
* @return Problems
*/
Set<?> ingestFromPreview(Dataset dataset, Descriptor descriptor, Preview preview, int sheet, long startRow, String field, String arraySeparator, List<ValueMapping> mapping);
/**
* Get Amphibian dataset information
* @param dataset source {@code dataset}
* @return metadata
*/
DatasetTable getAmphibianDataset(Dataset dataset);
/**
* Get Amphibian datasets information
* @param datasetUuids dataset uuids
* @return list of metadata
*/
List<DatasetTable> getAmphibianDatasetsList(List<UUID> datasetUuids);
/**
* Get trait observations from the dataset for the specified filters
*
* @param dataset
* @param page
* @param fields
* @param traitDataFilter
* @return observations
*/
Page<?> getObservations(Dataset dataset, Pageable page, List<UUID> fields, TraitFilters traitDataFilter);
/**
* Remove observations
* @param dataset
* @param descriptor
* @return updated metadata
*/
DatasetTable removeObservations(Dataset dataset, Descriptor descriptor);
/**
* Generate a new wide-data sheet from long-data sheet
* @param uuid the Preview
* @param longToWide configuration
* @return updated {@code Preview} with +1 sheet
*/
Preview longToWide(UUID uuid, LongToWide longToWide);
/**
* Get trait observations from all (Amphibian) datasets of the given accession
*
* @param accessionUuid the Accession uuid
* @return List of observations of first and third party datasets
* @throws SearchException
*/
AccessionObservations getAccessionObservations(UUID accessionUuid) throws SearchException;
class AccessionObservations {
public List<?> firstPartyData;
public List<?> thirdPartyData;
}
/**
* Get trait observations from provided datasets of the given accessions
*
* @return List of accessions datasets observations
*/
Page<?> getAccessionDatasetObservations(List<Dataset> datasets, List<UUID> descriptors, AccessionsDatasetsDataRequest request, Pageable page) throws Exception;
/**
* Get trait observation charts from provided datasets of the given accessions
*
* @return List of accessions dataset observation charts
*/
List<ObservationChart> getDatasetsCharts(List<Dataset> datasets, List<UUID> fields, TraitFilters filter);
/**
* Calculate a heat map of observations for two selected categorical descriptors for selected datasets
*
* @return Heat map
*/
HeatMap getDatasetsHeatMap(List<Dataset> datasets, UUID uuid, UUID uuid1, TraitFilters filter);
/**
* Get histograms of numerical observations from datasets
* @param datasets
* @param fields
* @param filter
* @param binsNumber
* @return Histograms for each given numerical field
*/
List<ObservationHistogram> getDatasetsHistograms(List<Dataset> datasets, List<UUID> fields, TraitFilters filter, int binsNumber);
/**
* Download observations from the dataset for the specified filters as xlsx
*
* @param dataset the Dataset
* @param filter the TraitDataFilter
* @param outputStream the ServletOutputStream
* @throws NoAccessionsForFilterException
*/
void downloadXlsxDatasetObservations(Dataset dataset, TraitFilters filter, ServletOutputStream outputStream) throws IOException, NoAccessionsForFilterException;
/**
* Remove Amphibian version of the dataset
* @param dataset
*/
void removeDataset(Dataset dataset);
}