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.Map;
019import java.util.Optional;
020
021import org.ametys.cms.search.model.CriterionDefinition;
022import org.ametys.cms.search.query.Query;
023import org.ametys.runtime.i18n.I18nizableText;
024import org.ametys.runtime.model.Enumerator;
025import org.ametys.runtime.model.type.DataContext;
026
027/**
028 * A potential criterion definition proposed to the creator of an instance of search service.
029 * @param <T> Type of the criterion value
030 */
031public interface SearchServiceCriterionDefinition<T> extends CriterionDefinition<T> 
032{
033    /**
034     * Gets the prefix label, sometimes useful (such as for displaying all criterion definitions) for grouping information.
035     * @return The prefix label (can be null)
036     */
037    default I18nizableText getContextPrefixLabel()
038    {
039        return null;
040    }
041    
042    /**
043     * Gets the ({@link Searchable}) the criterion belongs to.
044     * 
045     * <br><b>Important</b>: if the criterion definition is brought by a specific Searchable, then this searchable must be returned in a non-empty {@link Optional}.
046     * If the criterion definition is brought by {@link SearchServiceCommonImpls}, then an {@link Optional#empty()} must be returned.
047     * 
048     * @return the ({@link Searchable}) the criterion belongs to.
049     */
050    Optional<Searchable> getSearchable();
051    
052    /**
053     * Sets the ({@link Searchable}) the criterion belongs to.
054     * @param searchable the {@link Searchable} to set
055     */
056    void setSearchable(Searchable searchable);
057    
058    /**
059     * Determines if this criterion definition is enumerated
060     * @return <code>true</code> if this criterion definition is enumerated, <code>false</code> otherwise
061     */
062    boolean isEnumerated();
063    
064    /**
065     * Gets the {@link RestrictedEnumerator} used by the final user to fill the criterion.
066     * Values of this {@link Enumerator} can be restricted according to entered values during service configuration
067     * @param contextualParameters The contextual parameters
068     * @return the enumerated entries
069     */
070    RestrictedEnumerator<T> getRestrictedEnumerator(Map<String, Object> contextualParameters);
071    
072    /**
073     * Converts the given value for {@link RestrictedEnumerator} 
074     * @param value the value to convert
075     * @param contextualParameters The contextual parameters
076     * @return the converted value
077     */
078    @SuppressWarnings("unchecked")
079    default T convertRestrictedValue(Object value, Map<String, Object> contextualParameters)
080    {
081        return (T) getType().fromJSONForClient(value, DataContext.newInstance());
082    }
083    
084    /**
085     * Gets the query for testing the value is empty
086     * @param language The current search language.
087     * @param contextualParameters the search contextual parameters.
088     * @return the query for testing the value is empty
089     */
090    Query getEmptyValueQuery(String language, Map<String, Object> contextualParameters);
091    
092    /**
093     * Retrieves the facet value to use for SAX events
094     * @param value the facet value
095     * @param contextualParameters the contextual parameters
096     * @return the facet value to use for SAX events
097     */
098    default String facetValueToSAX(String value, Map<String, Object> contextualParameters)
099    {
100        return value;
101    }
102}