CropApiService.java

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

import com.fasterxml.jackson.annotation.JsonUnwrapped;
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 java.util.List;

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);
}