/*
 * This file is a part of EpnTAPClient.
 * This program aims to provide EPN-TAP support for software clients, like CASSIS spectrum analyzer.
 * See draft specifications: https://voparis-confluence.obspm.fr/pages/viewpage.action?pageId=559861
 * Copyright (C) 2016 Institut de Recherche en Astrophysique et Planétologie.
 *
 * This program is free software: you can
 * redistribute it and/or modify it under the terms of the GNU 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 General Public License along with this program. If not, see
 * <http://www.gnu.org/licenses/>.
 */

package eu.omp.irap.vespa.epntapclient;

import java.util.List;

import eu.omp.irap.vespa.epntapclient.granule.Granule;
import eu.omp.irap.vespa.epntapclient.voresource.VOResourceException;
import eu.omp.irap.vespa.epntapclient.voresource.model.Resource;
import eu.omp.irap.vespa.epntapclient.votable.model.VOTABLE;
import eu.omp.irap.vespa.votable.controller.CantGetVOTableException;

/**
 * @author N. Jourdane
 */
public interface EpnTapInterface {

	// *** Resource ***

	/** returns the VOResource element of the service identified by the ivoID. */
	public Resource getEPNVOresource(String ivoid) throws VOResourceException;

	// *** Resources ***

	/** returns a set of VOResource elements (one per EPN-TAP service) */
	public List<Resource> getEPNVOResources() throws VOResourceException;

	/**
	 * Returns a set of VOREsource elements (one per EPN-TAP service corresponding to the keywords).
	 * The way keywords are defined is still to be defined.
	 */
	public List<Resource> getEPNVOResources(List<String> keywords)
			throws VOResourceException;

	// *** Service ***

	/**
	 * returns a VOTable containing the attributes of the corresponding service (from a predefined
	 * list)
	 *
	 * @throws VOResourceException
	 * @throws CantGetVOTableException
	 * @throws IllegalAccessException
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public VOTABLE getEPNService(String ivoID) throws CantGetVOTableException;

	/**
	 * returns a VOTable containing the attributes of the corresponding service (from the list of
	 * attributes)
	 *
	 * @throws VOResourceException
	 * @throws CantGetVOTableException
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public VOTABLE getEPNService(String ivoID, List<String> attributes)
			throws CantGetVOTableException;

	// *** Services ***

	/**
	 * returns a VOTable containing the list of EPN-TAP services and their attributes (from a
	 * predefined list)
	 *
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public VOTABLE getEPNServices() throws CantGetVOTableException;

	/**
	 * returns a VOTable containing the list of EPN-TAP services and their attributes (from the list
	 * of attributes)
	 *
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public VOTABLE getEPNServices(List<String> attributes) throws CantGetVOTableException;

	/**
	 * returns a VOTable containing the list of EPN-TAP services corresponding to the keywords and
	 * their attributes (from the list of attributes)
	 *
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public VOTABLE getEPNServices(List<String> keywords, List<String> attributes)
			throws CantGetVOTableException;

	// *** Getters ***

	/**
	 * returns the name of the EPNCore Table related to a service.
	 *
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public String getEPNCoreTableName(String ivoid) throws CantGetVOTableException;

	/**
	 * returns the Access URL of an EPN-TAP Service.
	 *
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public String getTAPURL(String ivoid) throws CantGetVOTableException;

	// *** Queries ***

	/**
	 * returns the list of granules which are compliant with the ADQL Query, in VOTable format .
	 * TAPURL is build from elements taken in VOResource. "ADQLQuery" is created by the Client. It
	 * is a full query containing the name of the EPNCore table, taken in VOResource.
	 *
	 * @throws CantGetXMLException
	 * @throws CantDisplayVOTableException
	 */
	public List<Granule> sendADQLQuery(String tapURL, String adqlQuery)
			throws CantGetVOTableException;

	/**
	 * returns the list of granules which are compliant with the Query, in VOTable format. "Query"
	 * is not an ADQL query. It is taken from a list of predefined queries. This list must be
	 * created.
	 */
	public List<Granule> sendQuery(String tapURL, String schemaName, Query query)
			throws CantGetVOTableException;
}