001/*
002 *  Copyright 2018 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.web.frontoffice.search.metamodel;
017
018import java.util.Collection;
019import java.util.Collections;
020import java.util.Map;
021import java.util.Optional;
022
023import org.apache.avalon.framework.configuration.Configuration;
024
025import org.ametys.cms.search.advanced.AbstractTreeNode;
026import org.ametys.cms.search.query.Query;
027import org.ametys.runtime.i18n.I18nizableText;
028import org.ametys.web.frontoffice.search.instance.model.FOSearchCriterion;
029
030/**
031 * Brings a set of criteria, facets, sorts on a type of objects.
032 */
033public interface Searchable
034{
035    /**
036     * Gets the label of the searchable
037     * @return the label of the searchable
038     */
039    I18nizableText getLabel();
040    
041    /**
042     *  Retrieves the relations the type must have with some {@link Returnable}s.
043     * <br> It does not have to be exhaustive (for instance if {@link Returnable#relationsWith()} declares the relation, it is useless to declare it twice)
044     * @return some relations the type must have with some {@link Returnable}s
045     */
046    default Collection<Returnable> relationsWith()
047    {
048        return Collections.emptyList();
049    }
050    
051    /**
052     * Retrieves the additional parameters to add to the search service
053     * <br>The ids of the parameters must be unique across all {@link Returnable}s and {@link Searchable}s
054     * @return some additional parameters to add to the search service
055     */
056    default Collection<Configuration> additionalServiceParameters()
057    {
058        return Collections.emptyList();
059    }
060    
061    /**
062     * Gets the criteria
063     * @param additionalParameterValues The additional parameter values
064     * @return the criteria
065     */
066    Collection<SearchCriterionDefinition> getCriteria(AdditionalParameterValueMap additionalParameterValues);
067    
068    /**
069     * The position of the criteria provided by this {@link Searchable} among criteria provided by other {@link Searchable}s.
070     * <br>All criteria provided by the same {@link Searchable} are always packed together, this integer just affects the relative position compared to other {@link Searchable} criteria.
071     * <br>The lowest the integer, the higher it will appear in the UI.
072     * @return The position of the criteria of this {@link Searchable}
073     */
074    default int criteriaPosition()
075    {
076        return 100;
077    }
078    
079    /**
080     * Returns the query which joins the given one (on a criterion) with the given result types
081     * @param queryOnCriterion The query on the criterion to join from
082     * @param criterion the criterion
083     * @param returnables The returnables to join to
084     * @param additionalParameters The additional parameters
085     * @return the joined query
086     */
087    Optional<Query> joinQuery(Query queryOnCriterion, SearchCriterionDefinition criterion, Collection<Returnable> returnables, AdditionalParameterValueMap additionalParameters);
088    
089    /**
090     * Builds the query of the criterion tree
091     * @param criterionTree The criterion tree of the service instance
092     * @param userCriteria The user input criteria
093     * @param returnables The returnables of the service instance
094     * @param searchables The searchables of the service instance
095     * @param additionalParameters The values of additional parameters of the service instance
096     * @param currentLang The current lang
097     * @param contextualParameters the search contextual parameters. 
098     * @return The query of the criterion tree
099     */
100    public Query buildQuery(
101            AbstractTreeNode<FOSearchCriterion> criterionTree, 
102            Map<String, Object> userCriteria, 
103            Collection<Returnable> returnables, 
104            Collection<Searchable> searchables, 
105            AdditionalParameterValueMap additionalParameters, 
106            String currentLang, 
107            Map<String, Object> contextualParameters);
108}