001/*
002 *  Copyright 2010 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.plugins.externaldata.data;
017
018import java.util.Collection;
019import java.util.Map;
020
021import org.ametys.core.datasource.DataSourceClientInteraction.DataSourceType;
022import org.ametys.plugins.externaldata.data.Query.ResultType;
023
024/**
025 * The DataSource Factory is responsible for building DataSource and Query objects.
026 * It handles one or several DataSource/Query types.
027 * @param <Q> The query
028 * @param <R> The query result
029 */
030public interface DataSourceFactory<Q extends Query, R extends QueryResult>
031{
032    
033    /**
034     * Get the types that the factory can build.
035     * @return the handled types as a Collection.
036     */
037    Collection<DataSourceType> getHandledTypes();
038    
039    /**
040     * The configuration parameters needed to build a Query of the specified type.
041     * @param type the type of the Query.
042     * @return the configuration parameters as a Collection.
043     */
044    Collection<String> getQueryConfigurationParameters(String type);
045    
046    /**
047     * Build a query with the specified information.
048     * @param id the Query ID.
049     * @param type the Query type.
050     * @param name the Query name.
051     * @param description the Query description.
052     * @param resultType the Query result type (single/multiple).
053     * @param dataSourceId the id of data source
054     * @param additionalConfiguration additional query configuration parameter values as a Map&lt;parameterName, parameterValue&gt;.
055     * @return the query.
056     * @throws DataInclusionException if an error occurs trying to create the Query.
057     */
058    Q buildQuery(String id, String type, String name, String description, ResultType resultType, String dataSourceId, Map<String, String> additionalConfiguration) throws DataInclusionException;
059    
060    /**
061     * Execute the query with the specified parameter values.
062     * @param query The query
063     * @param parameterValues the parameter values as a Map (name -&gt; value).
064     * @return the query result.
065     * @throws DataInclusionException if an error occurs while executing the query
066     */
067    R execute(Q query, Map<String, String> parameterValues) throws DataInclusionException;
068    
069    /**
070     * Execute the query with the specified parameter values.
071     * @param query The query
072     * @param parameterValues the parameter values as a Map (name -&gt; value).
073     * @param offset The start index of search
074     * @param limit The max number of result to return
075     * @return the query result.
076     * @throws DataInclusionException if an error occurs while executing the query
077     */
078    R execute(Q query, Map<String, String> parameterValues, int offset, int limit) throws DataInclusionException;
079}