CropApiService.java

/*
 * Copyright 2026 Global Crop Diversity Trust
 * Licensed under the Apache License, Version 2.0
 * See LICENSE file in project root folder or http://www.apache.org/licenses/LICENSE-2.0
 */

package org.gringlobal.api.v2.facade;

import java.util.List;

import org.gringlobal.api.model.CropAttachDTO;
import org.gringlobal.api.model.CropDTO;
import org.gringlobal.api.model.TaxonomyCropMapDTO;
import org.gringlobal.api.model.TaxonomySpeciesDTO;
import org.gringlobal.model.Crop;
import org.gringlobal.model.TaxonomySpecies;
import org.gringlobal.service.filter.CropFilter;
import org.gringlobal.service.filter.TaxonomySpeciesFilter;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import com.fasterxml.jackson.annotation.JsonUnwrapped;

public interface CropApiService extends APIFilteredServiceFacade<CropDTO, Crop, CropFilter>{

	/**
	 * Gets the crop.
	 *
	 * @param cropName the crop name
	 * @return the crop
	 */
	CropDTO getCrop(String cropName);

	/**
	 * Ensure crop taxonomy link.
	 *
	 * @param crop the crop
	 * @param taxonomySpecies the taxonomy species
	 * @return the taxonomy crop map
	 */
	TaxonomyCropMapDTO ensureCropTaxonomyLink(CropDTO crop, TaxonomySpeciesDTO taxonomySpecies);

	/**
	 * Gets the crop details.
	 *
	 * @param cropId the crop id
	 * @return the crop details
	 */
	CropDetails getCropDetails(long cropId);

	/**
	 * Adding taxonomy species to the crop.
	 *
	 * @param cropId the crop id
	 * @param species the list of taxonomy species
	 * @param note the note
	 * @return added records
	 */
	List<TaxonomyCropMapDTO> addSpecies(Long cropId, List<TaxonomySpeciesDTO> species, String note);

	/**
	 * Removing taxonomy species for the crop.
	 *
	 * @param cropId the crop id
	 * @param species the list of taxonomy species
	 * @return removed records
	 */
	List<TaxonomyCropMapDTO> removeSpecies(Long cropId, List<TaxonomySpeciesDTO> species);

	class CropDetails {
		@JsonUnwrapped
		public CropDTO crop;

		public List<CropAttachDTO> attachments;
	}


	/**
	 * List {@link TaxonomySpecies} associated with the crop.
	 *
	 * @param cropId the crop id
	 * @param filter the filter
	 * @param pageable the pageable
	 * @return the page
	 */
	Page<TaxonomySpeciesDTO> listSpecies(long cropId, TaxonomySpeciesFilter filter, Pageable pageable);

	/**
	 * Auto-complete crops.
	 *
	 * @param term the search term
	 * @return matching crops list
	 */
	List<CropDTO> autocompleteCrops(String term);

	/**
	 * List of all crops
	 *
	 * @param pageable the pageable
	 * @return crops list
	 */
	Page<CropDTO> listCrops(Pageable pageable);
}