001/*
002 *  Copyright 2024 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.cms.search.model;
017
018import java.util.List;
019import java.util.Map;
020
021import org.ametys.cms.data.type.indexing.IndexableElementType;
022import org.ametys.cms.search.query.Query;
023import org.ametys.cms.search.query.Query.Operator;
024import org.ametys.runtime.model.ElementDefinition;
025
026/**
027 * Represents the definition of a criterion definition
028 * @param <T> Type of the criterion value
029 */
030public interface CriterionDefinition<T> extends ElementDefinition<T>
031{
032    /**
033     * Gets the {@link Query} associated to the given value
034     * @param value The user-submitted value (or the default value if not set) for this criterion.
035     * @param operator In advanced search mode, the operator chosen by the user. <code>null</code> to use the criterion-defined operator (simple search mode).
036     * @param language The current search language.
037     * @param contextualParameters the search contextual parameters.
038     * @return the {@link Query} associated to the given value
039     */
040    public default Query getQuery(Object value, Operator operator, String language, Map<String, Object> contextualParameters)
041    {
042        return getQuery(value, operator, Map.of(), language, contextualParameters);
043    }
044    
045    /**
046     * Get the {@link Query} associated to the given value.
047     * @param value The user-submitted value (or the default value if not set) for this criterion.
048     * @param allValues All the user-submitted values.
049     * @param language The current search language.
050     * @param contextualParameters the search contextual parameters.
051     * @return {@link Query} associated to the given value.
052    */
053    public default Query getQuery(Object value, Map<String, Object> allValues, String language, Map<String, Object> contextualParameters)
054    {
055        return getQuery(value, null, allValues, language, contextualParameters);
056    }
057    
058    /**
059     * Get the {@link Query} associated to the given value.
060     * @param value The user-submitted value (or the default value if not set) for this criterion.
061     * @param operator In advanced search mode, the operator chosen by the user. <code>null</code> to use the criterion-defined operator (simple search mode).
062     * @param allValues All the user-submitted values.
063     * @param language The current search language.
064     * @param contextualParameters the search contextual parameters.
065     * @return {@link Query} associated to the given value.
066     */
067    public Query getQuery(Object value, Operator operator, Map<String, Object> allValues, String language, Map<String, Object> contextualParameters);
068    
069    /**
070     * Converts the given value to have the right typed for value to give to the {@link #getQuery(Object, Map, String, Map)} method
071     * @param value the value to convert
072     * @param contextualParameters the search contextual parameters.
073     * @return the value, converted to a well typed value
074     */
075    public Object convertQueryValue(Object value, Map<String, Object> contextualParameters);
076    
077    /**
078     * Retrieves the name of the criterion's solr facet field
079     * @param contextualParameters the search contextual parameters.
080     * @return the name of the criterion's solr facet field. Can be <code>null</code> if the criterion is not facetable
081     */
082    public String getSolrFacetFieldName(Map<String, Object> contextualParameters);
083    
084    /**
085     * Retrieves the joined paths of the criterion
086     * @param contextualParameters the search contextual parameters.
087     * @return the joined paths, or an empty list if the criterion is not joined
088     */
089    public List<String> getJoinedPaths(Map<String, Object> contextualParameters);
090    
091    @Override
092    public IndexableElementType<T> getType();
093}