package org.emau.icmvc.ganimed.ttp.cm2;

/*-
 * ###license-information-start###
 * gICS - a Generic Informed Consent Service
 * __
 * Copyright (C) 2014 - 2023 Trusted Third Party of the University Medicine Greifswald -
 * 							kontakt-ths@uni-greifswald.de
 * 
 * 							concept and implementation
 * 							l.geidel, c.hampf
 * 							web client
 * 							a.blumentritt, m.bialke, f.m.moser
 * 							fhir-api
 * 							m.bialke
 * 							docker
 * 							r. schuldt
 * 
 * 							The gICS was developed by the University Medicine Greifswald and published
 * 							in 2014 as part of the research project "MOSAIC" (funded by the DFG HO 1937/2-1).
 * 
 * 							Selected functionalities of gICS were developed as
 * 							part of the following research projects:
 * 							- MAGIC (funded by the DFG HO 1937/5-1)
 * 							- MIRACUM (funded by the German Federal Ministry of Education and Research 01ZZ1801M)
 * 							- NUM-CODEX (funded by the German Federal Ministry of Education and Research 01KX2021)
 * 
 * 							please cite our publications
 * 							https://doi.org/10.1186/s12911-022-02081-4
 * 							https://doi.org/10.1186/s12967-020-02457-y
 * 							http://dx.doi.org/10.3414/ME14-01-0133
 * 							http://dx.doi.org/10.1186/s12967-015-0545-6
 * 							http://dx.doi.org/10.3205/17gmds146
 * __
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 * ###license-information-end###
 */

import java.util.Set;

import javax.jws.WebParam;
import javax.jws.WebService;
import javax.xml.bind.annotation.XmlElement;

import org.emau.icmvc.ganimed.ttp.cm2.dto.ConsentDTO;
import org.emau.icmvc.ganimed.ttp.cm2.dto.ConsentKeyDTO;
import org.emau.icmvc.ganimed.ttp.cm2.dto.ConsentScanDTO;
import org.emau.icmvc.ganimed.ttp.cm2.dto.ConsentTemplateKeyDTO;
import org.emau.icmvc.ganimed.ttp.cm2.dto.QCDTO;
import org.emau.icmvc.ganimed.ttp.cm2.dto.SignerIdDTO;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.DuplicateEntryException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.InternalException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.InvalidFreeTextException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.InvalidParameterException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.InvalidVersionException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.MandatoryFieldsException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.MissingRequiredObjectException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.RequirementsNotFullfilledException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.UnknownConsentException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.UnknownConsentTemplateException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.UnknownDomainException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.UnknownModuleException;
import org.emau.icmvc.ganimed.ttp.cm2.exceptions.UnknownSignerIdTypeException;

/**
 * An interface for sibling gics-service methods which additionally send notifications via the
 * <a href="https://git.icm.med.uni-greifswald.de/ths/ths-notification">THS Notification Service</a>.
 *
 * @author moser
 */
@WebService
public interface GICSServiceWithNotification
{
	/**
	 * Updates the QC for the given consent and sends a notification.
	 *
	 * @param notificationClientID the notification client ID (null or empty to skip sending a notification)
	 * @param consentKeyDTO the consent to update the QC for
	 * @param qc the new QC
	 * @throws InvalidParameterException
	 * @throws InvalidVersionException
	 * @throws UnknownConsentException
	 * @throws UnknownSignerIdTypeException
	 * @throws UnknownConsentTemplateException
	 * @throws UnknownDomainException
	 * @throws InvalidParameterException
	 * @see GICSService#setQCForConsent(ConsentKeyDTO, QCDTO)
	 */
	void setQCForConsent(
			@XmlElement(required = false) @WebParam(name = "notificationClientID") String notificationClientID,
			@XmlElement(required = true) @WebParam(name = "consentKey") ConsentKeyDTO consentKeyDTO,
			@XmlElement(required = true) @WebParam(name = "qc") QCDTO qc)
			throws InvalidParameterException, InvalidVersionException, UnknownConsentException,
			UnknownSignerIdTypeException, UnknownConsentTemplateException, UnknownDomainException;

	/**
	 * Stores the given consent and sends a notification.
	 * The policies within the modulDTOs are ignored and therefore doesn't need to be set.
	 *
	 * @param notificationClientID the notification client ID (null or empty to skip sending a notification)
	 * @param consentDTO the consent to add
	 * @throws UnknownDomainException
	 * @throws UnknownModuleException
	 * @throws UnknownConsentTemplateException
	 * @throws InvalidVersionException
	 * @throws MissingRequiredObjectException when there's no given value for a mandatory free text field
	 * @throws InvalidFreeTextException
	 * @throws MandatoryFieldsException see {@link MandatoryFieldsException}
	 * @throws UnknownSignerIdTypeException
	 * @throws DuplicateEntryException
	 * @throws RequirementsNotFullfilledException
	 * @throws InvalidParameterException
	 * @see GICSService#addConsent(ConsentDTO)
	 */
	void addConsent(
			@XmlElement(required = false) @WebParam(name = "notificationClientID") String notificationClientID,
			@XmlElement(required = true) @WebParam(name = "consent") ConsentDTO consentDTO)
			throws UnknownDomainException, UnknownModuleException, UnknownConsentTemplateException, InvalidVersionException,
			MissingRequiredObjectException, InvalidFreeTextException, MandatoryFieldsException, UnknownSignerIdTypeException,
			DuplicateEntryException, RequirementsNotFullfilledException, InvalidParameterException;

	/**
	 * Stores a "refused" consent.
	 * The consent is not declined, the participant didn't want to fill a consent.<br>
	 * The date of the refused consent is set to the current date.
	 *
	 * @param notificationClientID the notification client ID (null or empty to skip sending a notification)
	 * @param ctKeyDTO the consent template key
	 * @param signerIdDTOs the signer ID
	 * @throws InvalidVersionException
	 * @throws UnknownSignerIdTypeException
	 * @throws UnknownConsentTemplateException
	 * @throws UnknownDomainException
	 * @throws InternalException
	 * @throws InvalidParameterException
	 * @see GICSService#refuseConsent(ConsentTemplateKeyDTO, Set)
	 */
	void refuseConsent(
			@XmlElement(required = false) @WebParam(name = "notificationClientID") String notificationClientID,
			@XmlElement(required = true) @WebParam(name = "consentTemplateKey") ConsentTemplateKeyDTO ctKeyDTO,
			@XmlElement(required = true) @WebParam(name = "signerIds") Set<SignerIdDTO> signerIdDTOs)
			throws InvalidVersionException, UnknownSignerIdTypeException, UnknownConsentTemplateException,
			UnknownDomainException, InternalException, InvalidParameterException;
	/**
	 * Updates the given consent.
	 *
	 * @param notificationClientID the notification client ID (null or empty to skip sending a notification)
	 * @param consentKeyDTO the consent key
	 * @param externProperties extern properties
	 * @param comment a comment
	 * @param scan a scan
	 * @throws InvalidVersionException
	 * @throws UnknownDomainException
	 * @throws UnknownConsentTemplateException
	 * @throws UnknownSignerIdTypeException
	 * @throws UnknownConsentException
	 * @throws InvalidParameterException
	 * @see GICSService#updateConsentInUse(ConsentKeyDTO, String, String, ConsentScanDTO)
	 */
	void updateConsentInUse(
			@XmlElement(required = false) @WebParam(name = "notificationClientID") String notificationClientID,
			@XmlElement(required = true) @WebParam(name = "consentKey") ConsentKeyDTO consentKeyDTO,
			@XmlElement(required = true) @WebParam(name = "externProperties") String externProperties,
			@XmlElement(required = true) @WebParam(name = "comment") String comment,
			@XmlElement(required = true) @WebParam(name = "scan") ConsentScanDTO scan)
			throws InvalidVersionException, UnknownDomainException, UnknownConsentTemplateException,
			UnknownSignerIdTypeException, UnknownConsentException, InvalidParameterException;
}
