DescriptorListApiService.java

/*
 * Copyright 2024 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.api.v2.facade;

import com.fasterxml.jackson.annotation.JsonUnwrapped;
import org.genesys.server.api.FilteredPage;
import org.genesys.server.api.v2.model.impl.DescriptorDTO;
import org.genesys.server.api.v2.model.impl.DescriptorListDTO;
import org.genesys.server.api.v2.model.impl.DescriptorListInfo;
import org.genesys.server.api.v2.model.impl.DescriptorListLangDTO;
import org.genesys.server.api.v2.model.impl.TranslatedDescriptorDTO;
import org.genesys.server.api.v2.model.impl.TranslatedDescriptorListDTO;
import org.genesys.server.exception.SearchException;
import org.genesys.server.model.filters.DescriptorListFilter;
import org.genesys.server.model.traits.DescriptorList;
import org.genesys.server.model.traits.DescriptorListLang;
import org.genesys.server.service.ElasticsearchService;
import org.genesys.server.service.TranslatorService;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.io.IOException;
import java.io.OutputStream;
import java.util.List;
import java.util.Map;
import java.util.UUID;

public interface DescriptorListApiService extends APIFilteredTranslatedServiceFacade
	<DescriptorListDTO, TranslatedDescriptorListDTO, DescriptorListLangDTO, DescriptorList, DescriptorListLang, DescriptorListFilter> {

	/**
	 * Count descriptor lists.
	 *
	 * @param filter the filter
	 * @return the long
	 */
	long countDescriptorLists(DescriptorListFilter filter) throws SearchException;

	/**
	 * Remove descriptor of descriptorList.
	 *
	 * @param descriptorList descriptorList
	 * @param descriptors the descriptors
	 * @return updated descriptorList
	 */
	DescriptorListDTO removeDescriptors(DescriptorListDTO descriptorList, DescriptorDTO... descriptors);

	/**
	 * Add new descriptor to descriptorList.
	 *
	 * @param descriptorList descriptorList
	 * @param descriptors the descriptors
	 * @return updated descriptorList
	 */
	DescriptorListDTO addDescriptors(DescriptorListDTO descriptorList, DescriptorDTO... descriptors);

	/**
	 * Find descriptorList by UUID.
	 *
	 * @param uuid UUID of descriptorList
	 * @return found descriptorList
	 */
	DescriptorListDTO loadDescriptorList(UUID uuid);

	/**
	 * Find translated descriptorList by UUID.
	 *
	 * @param uuid UUID of descriptorList
	 * @return found descriptorList
	 */
	TranslatedDescriptorListDTO loadTranslatedDescriptorList(UUID uuid);

	/**
	 * Find descriptors of a descriptor List by uuid
	 *
	 * @param uuid UUID of descriptorList
	 * @return list of descriptors
	 */
	List<TranslatedDescriptorDTO> loadDescriptors(UUID uuid);

	/**
	 * Find descriptorList by UUID and version.
	 *
	 * @param uuid UUID of descriptorList
	 * @param version record version
	 * @return found descriptorList
	 */
	DescriptorListDTO loadDescriptorList(UUID uuid, int version);

	/**
	 * Reload descriptor list from database by identifiers and version.
	 *
	 * @param input query by example
	 * @return loaded descriptor list
	 */
	DescriptorListDTO loadDescriptorList(DescriptorListDTO input);

	/**
	 * Get terms by filter.
	 *
	 * @param filter the descriptor list filter
	 * @return the term result
	 * @throws SearchException the search exception
	 * @throws IOException the IO exception
	 */
	Map<String, ElasticsearchService.TermResult> getSuggestions(DescriptorListFilter filter) throws SearchException, IOException;

	/**
	 * List Descriptor Lists for current user.
	 *
	 * @param descriptorListFilter the descriptor list filter
	 * @param page page
	 * @return page with DescriptorListDTO
	 */
	Page<DescriptorListDTO> listDescriptorListsForCurrentUser(DescriptorListFilter descriptorListFilter, Pageable page) throws SearchException;

	/**
	 * Puts the descriptorList into the Review state to be reviewed by admin. Admin
	 * and the user with MANAGE permission - only.
	 *
	 * @param descriptorList the descriptorList
	 * @return descriptorList in REVIEWING state
	 */
	DescriptorListDTO reviewDescriptorList(DescriptorListDTO descriptorList);

	/**
	 * Unpublishes published descriptorList. Admin and the user with MANAGE
	 * permission - only.
	 *
	 * @param descriptorList the descriptorList
	 * @return unpublished descriptorList
	 */
	DescriptorListDTO rejectDescriptorList(DescriptorListDTO descriptorList);

	/**
	 * Validates and publishes an unpublished descriptorList. Admin - only
	 *
	 * @param descriptorList the descriptorList
	 * @return published descriptorList
	 */
	DescriptorListDTO approveDescriptorList(DescriptorListDTO descriptorList);

	/**
	 * Completely update the descriptor list (including order).
	 *
	 * @param descriptorList the descriptor list
	 * @param descriptors the descriptors
	 * @return the descriptor list
	 */
	DescriptorListDTO setDescriptors(DescriptorListDTO descriptorList, DescriptorDTO[] descriptors);

	/**
	 * Autocomplete descriptor lists.
	 *
	 * @param text the text
	 * @return list of matched descriptor lists
	 */
	List<DescriptorListInfo> autocompleteDescriptorLists(String text);

	/**
	 * Write descriptorList as Excel to output stream.
	 *
	 * @param uuid the UUID of the descriptorList 
	 * @param outputStream the output stream
	 * @throws IOException
	 */
	void exportDescriptorList(UUID uuid, OutputStream outputStream) throws IOException;

	class DescriptorListOverview {
		public String filterCode;
		public DescriptorListFilter filter;
		public long descriptorListCount;
		public Map<String, ElasticsearchService.TermResult> overview;
		public Map<String, ElasticsearchService.TermResult> suggestions;

		public static DescriptorListOverview from(String filterCode, DescriptorListFilter filter, Map<String, ElasticsearchService.TermResult> overview, long descriptorListCount, Map<String, ElasticsearchService.TermResult> suggestions) {
			DescriptorListOverview res = new DescriptorListOverview();
			res.filterCode = filterCode;
			res.filter = filter;
			res.overview = overview;
			res.descriptorListCount = descriptorListCount;
			res.suggestions = suggestions;

			return res;
		}
	}

	class DescriptorListSuggestionPage extends FilteredPage<TranslatedDescriptorListDTO, DescriptorListFilter> {
		public Map<String, ElasticsearchService.TermResult> suggestions;

		public DescriptorListSuggestionPage(DescriptorListFilter filter, Page<TranslatedDescriptorListDTO> data) {
			super(filter, data);
		}
		public DescriptorListSuggestionPage(String filterCode, DescriptorListFilter filter, Page<TranslatedDescriptorListDTO> data) {
			super(filterCode, filter, data);
		}

		public static DescriptorListSuggestionPage from(FilteredPage<TranslatedDescriptorListDTO, DescriptorListFilter> page, Map<String, ElasticsearchService.TermResult> suggestions) {
			DescriptorListSuggestionPage res = new DescriptorListSuggestionPage(page.filterCode, page.filter, page.page);
			res.suggestions = suggestions;
			return res;
		}
	}

	DescriptorListLangDTO machineTranslate(UUID uuid, String targetLang) throws TranslatorService.TranslatorException;
}