/*
 *  Copyright 2016 Anyware Services
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package org.ametys.cms.search.solr;

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Collectors;

import org.apache.avalon.framework.activity.Initializable;
import org.apache.avalon.framework.component.Component;
import org.apache.avalon.framework.service.ServiceException;
import org.apache.avalon.framework.service.ServiceManager;
import org.apache.avalon.framework.service.Serviceable;
import org.apache.commons.collections.CollectionUtils;
import org.apache.commons.lang3.StringUtils;
import org.apache.solr.client.solrj.SolrClient;
import org.apache.solr.client.solrj.request.RequestWriter.ContentWriter;
import org.apache.solr.client.solrj.request.json.DomainMap;
import org.apache.solr.client.solrj.request.json.JsonQueryRequest;
import org.apache.solr.client.solrj.request.json.TermsFacetMap;
import org.apache.solr.client.solrj.response.FacetField;
import org.apache.solr.client.solrj.response.FacetField.Count;
import org.apache.solr.client.solrj.response.QueryResponse;
import org.apache.solr.client.solrj.response.json.BucketBasedJsonFacet;
import org.apache.solr.client.solrj.response.json.BucketJsonFacet;
import org.apache.solr.common.params.CommonParams;
import org.apache.solr.common.params.HighlightParams;
import org.slf4j.Logger;

import org.ametys.cms.search.SearchResults;
import org.ametys.cms.search.SortOrder;
import org.ametys.cms.search.query.JoinQuery;
import org.ametys.cms.search.query.MatchAllQuery;
import org.ametys.cms.search.query.OrQuery;
import org.ametys.cms.search.query.Query;
import org.ametys.cms.search.query.QuerySyntaxException;
import org.ametys.core.group.GroupIdentity;
import org.ametys.core.group.GroupManager;
import org.ametys.core.right.AllowedUsers;
import org.ametys.core.user.CurrentUserProvider;
import org.ametys.core.user.UserIdentity;
import org.ametys.plugins.repository.AmetysObject;
import org.ametys.plugins.repository.AmetysObjectIterable;
import org.ametys.plugins.repository.AmetysObjectResolver;
import org.ametys.runtime.plugin.component.AbstractLogEnabled;

/**
 * Component searching objects corresponding to a {@link Query}.
 */
public class SearcherFactory extends AbstractLogEnabled implements Component, Serviceable, Initializable
{
    
    /** The component role. */
    public static final String ROLE = SearcherFactory.class.getName();
    
    /** The default size for highlight snippet */
    public static final int DEFAULT_HIGHLIGHT_SNIPPET_SIZE = 400;
    
    /** The default count for highlight snippet */
    public static final int DEFAULT_HIGHLIGHT_SNIPPET_COUNT = 5;
    
    /** The {@link AmetysObjectResolver} */
    protected AmetysObjectResolver _resolver;
    
    /** The solr client provider */
    protected SolrClientProvider _solrClientProvider;
    
    /** The current user provider. */
    protected CurrentUserProvider _currentUserProvider;
    
    /** The group manager */
    protected GroupManager _groupManager;
    
    /** The solr client */
    protected SolrClient _solrClient;
    
    @Override
    public void service(ServiceManager serviceManager) throws ServiceException
    {
        _resolver = (AmetysObjectResolver) serviceManager.lookup(AmetysObjectResolver.ROLE);
        _solrClientProvider = (SolrClientProvider) serviceManager.lookup(SolrClientProvider.ROLE);
        _currentUserProvider = (CurrentUserProvider) serviceManager.lookup(CurrentUserProvider.ROLE);
        _groupManager = (GroupManager) serviceManager.lookup(GroupManager.ROLE);
    }
    
    @Override
    public void initialize() throws Exception
    {
        _solrClient = _solrClientProvider.getReadClient();
    }
    
    /**
     * Create a Searcher.
     * @return a Searcher object.
     */
    public Searcher create()
    {
        return new Searcher(getLogger());
    }
    
    /**
     * Class searching objects corresponding to a query, with optional sort, facets, and so on.
     */
    public class Searcher
    {
        private Logger _logger;
        
        private String _queryString;
        private Query _query;
        private List<String> _filterQueryStrings;
        private List<Query> _filterQueries;
        private List<SortDefinition> _sortClauses;
        private List<FacetDefinition> _facets;
        private Map<String, List<String>> _facetValues;
        private int _start;
        private int _maxResults;
        private Map<String, Object> _searchContext;
        private boolean _checkRights;
        private AllowedUsers _checkRightsComparingTo;
        private boolean _debug;
        private HighlightDefinition _highlightDefinition;

        /**
         * Build a Searcher with default values.
         * @param logger The logger.
         */
        protected Searcher(Logger logger)
        {
            _logger = logger;
            
            _filterQueryStrings = new ArrayList<>();
            _filterQueries = new ArrayList<>();
            _sortClauses = new ArrayList<>();
            _facets = new ArrayList<>();
            _facetValues = new HashMap<>();
            _start = 0;
            _maxResults = Integer.MAX_VALUE;
            _searchContext = new HashMap<>();
            _checkRights = true;
        }
        
        /**
         * Set the query (as a String).
         * @param query the query (as a String).
         * @return The Searcher object itself.
         */
        public Searcher withQueryString(String query)
        {
            if (this._query != null)
            {
                throw new IllegalArgumentException("Query and query string can't be used at the same time.");
            }
            this._queryString = query;
            return this;
        }
        
        /**
         * Set the query (as a {@link Query} object).
         * @param query the query (as a {@link Query} object).
         * @return The Searcher object itself.
         */
        public Searcher withQuery(Query query)
        {
            if (this._queryString != null)
            {
                throw new IllegalArgumentException("Query and query string can't be used at the same time.");
            }
            this._query = query;
            return this;
        }
        
        /**
         * Set the filter queries (as Strings).
         * @param queries the filter queries (as Strings).
         * @return The Searcher object itself. The Searcher object itself.
         */
        public Searcher withFilterQueryStrings(String... queries)
        {
            _filterQueryStrings = new ArrayList<>(queries.length);
            CollectionUtils.addAll(_filterQueryStrings, queries);
            return this;
        }
        
        /**
         * Set the filter queries (as Strings).
         * @param queries the filter queries (as Strings).
         * @return The Searcher object itself. The Searcher object itself.
         */
        public Searcher withFilterQueryStrings(Collection<String> queries)
        {
            _filterQueryStrings = new ArrayList<>(queries);
            return this;
        }
        
        /**
         * Add a filter query to the existing ones (as a String).
         * @param query the filter query to add (as a String).
         * @return The Searcher object itself. The Searcher object itself.
         */
        public Searcher addFilterQueryString(String query)
        {
            _filterQueryStrings.add(query);
            return this;
        }
        
        /**
         * Set the filter queries (as {@link Query} objects).
         * @param queries the filter queries (as {@link Query} objects).
         * @return The Searcher object itself. The Searcher object itself.
         */
        public Searcher withFilterQueries(Query... queries)
        {
            _filterQueries = new ArrayList<>(queries.length);
            CollectionUtils.addAll(_filterQueries, queries);
            return this;
        }
        
        /**
         * Set the filter queries (as {@link Query} objects).
         * @param queries the filter queries (as {@link Query} objects).
         * @return The Searcher object itself. The Searcher object itself.
         */
        public Searcher withFilterQueries(Collection<Query> queries)
        {
            _filterQueries = new ArrayList<>(queries);
            return this;
        }
        
        /**
         * Add a filter query to the existing ones (as a {@link Query} object).
         * @param query the filter query to add (as a {@link Query} object).
         * @return The Searcher object itself. The Searcher object itself.
         */
        public Searcher addFilterQuery(Query query)
        {
            _filterQueries.add(query);
            return this;
        }
        
        /**
         * Set the sort clauses.
         * @param sortClauses the sort clauses.
         * @return The Searcher object itself.
         */
        public Searcher withSort(SortDefinition... sortClauses)
        {
            _sortClauses = new ArrayList<>(sortClauses.length);
            CollectionUtils.addAll(_sortClauses, sortClauses);
            return this;
        }
        
        /**
         * Set the sort clauses.
         * @param sortClauses the sort clauses.
         * @return The Searcher object itself.
         */
        public Searcher withSort(List<SortDefinition> sortClauses)
        {
            _sortClauses = new ArrayList<>(sortClauses);
            return this;
        }
        
        /**
         * Add a sort clause to the existing ones.
         * @param sortClause The sort clause to add.
         * @return The Searcher object itself.
         */
        public Searcher addSort(SortDefinition sortClause)
        {
            _sortClauses.add(sortClause);
            return this;
        }
        
        /**
         * Set the faceted fields.
         * @param facets the faceted fields.
         * @return The Searcher object itself.
         */
        public Searcher withFacets(FacetDefinition... facets)
        {
            _facets = new ArrayList<>(facets.length);
            CollectionUtils.addAll(_facets, facets);
            return this;
        }
        
        /**
         * Set the faceted fields.
         * @param facets the faceted fields.
         * @return The Searcher object itself.
         */
        public Searcher withFacets(Collection<FacetDefinition> facets)
        {
            _facets = new ArrayList<>(facets);
            return this;
        }
        
        /**
         * Add a faceted field.
         * @param facet The faceted field to add.
         * @return The Searcher object itself.
         */
        public Searcher addFacet(FacetDefinition facet)
        {
            _facets.add(facet);
            return this;
        }
        
        /**
         * Set the facet values.
         * @param facetValues The facet values.
         * @return The Searcher object itself.
         */
        public Searcher withFacetValues(Map<String, List<String>> facetValues)
        {
            _facetValues = new HashMap<>(facetValues);
            return this;
        }
        
        /**
         * Set the search offset and limit.
         * @param start The start index (offset).
         * @param maxResults The maximum number of results.
         * @return The Searcher object itself.
         */
        public Searcher withLimits(int start, int maxResults)
        {
            this._start = start;
            this._maxResults = maxResults;
            return this;
        }
        
        /**
         * Set the search context.
         * @param searchContext The search context.
         * @return The Searcher object itself.
         */
        public Searcher withContext(Map<String, Object> searchContext)
        {
            _searchContext = new HashMap<>(searchContext);
            return this;
        }
        
        /**
         * Set the highlight.
         * @param query the highlighting query
         * @return the searcher object itself.
         */
        public Searcher withHighlightingQuery(Query query)
        {
            this._highlightDefinition = new HighlightDefinition(query, DEFAULT_HIGHLIGHT_SNIPPET_COUNT, DEFAULT_HIGHLIGHT_SNIPPET_SIZE);
            return this;
        }
        
        /**
         * Set the highlight.
         * @param highlightDefinition the record with the parameters
         * @return the searcher object itself.
         */
        public Searcher withHighlight(HighlightDefinition highlightDefinition)
        {
            this._highlightDefinition = highlightDefinition;
            return this;
        }
        
        /**
         * Add a value to the search context.
         * @param key The context key.
         * @param value The value.
         * @return The Searcher object itself.
         */
        public Searcher addContextElement(String key, Object value)
        {
            _searchContext.put(key, value);
            return this;
        }
        
        /**
         * Whether to check rights when searching, false otherwise.
         * @param checkRights <code>true</code> to check rights, <code>false</code> otherwise.
         * @return The Searcher object itself.
         */
        public Searcher setCheckRights(boolean checkRights)
        {
            _checkRights = checkRights;
            return this;
        }
        
        /**
         * Check rights when searching, <b>not</b> according to the current user,
         * but according to the given {@link AllowedUsers visibilty} to compare each
         * result with.
         * @param compareTo the {@link AllowedUsers visibilty} to compare each result with.
         * @return The Searcher object itself.
         */
        public Searcher checkRightsComparingTo(AllowedUsers compareTo)
        {
            _checkRights = false;
            _checkRightsComparingTo = compareTo;
            return this;
        }
        
        /**
         * Sets the debug on the Solr query
         * @return The Searcher object itself.
         */
        public Searcher setDebugOn()
        {
            _debug = true;
            return this;
        }
        
        /**
         * Execute the search with the current parameters.
         * @param <A> The type of search results
         * @return An iterable on the result ametys objects.
         * @throws Exception If an error occurs.
         */
        public <A extends AmetysObject> AmetysObjectIterable<A> search() throws Exception
        {
            SearchResults<A> searchResults = searchWithFacets();
            return searchResults.getObjects();
        }
        
        /**
         * Execute the search with the current parameters.
         * @param <A> The type of search results
         * @return An iterable on the search result objects.
         * @throws Exception If an error occurs.
         */
        public <A extends AmetysObject> SearchResults<A> searchWithFacets() throws Exception
        {
            QueryResponse response = _querySolrServer();
            return _buildResults(response, _facets);
        }
        
        /**
         * From the Solr server response, builds the {@link SearchResults} object.
         * @param <A> The type of search results
         * @param response The response from the Solr server
         * @param facets The facet fields to return
         * @return An iterable on the search result objects.
         * @throws Exception If an error occurs.
         */
        protected <A extends AmetysObject> SearchResults<A> _buildResults(QueryResponse response, List<FacetDefinition> facets) throws Exception
        {
            _handleDebug(response);
            Map<String, Map<String, Integer>> facetResults = getFacetResults(response, facets);
            return new SolrSearchResults<>(response, _resolver, facetResults);
        }
        
        private void _handleDebug(QueryResponse response)
        {
            if (_debug && _logger.isDebugEnabled())
            {
                Map<String, Object> debugMap = response.getDebugMap();
                _logger.debug("Debug response: \n{}", debugMap);
            }
        }
        
        private QueryResponse _querySolrServer() throws Exception
        {
            _logSearchQueries();
            
            Object query = getQuery();
            List<Object> filterQueries = getFilterQueries();
            
            AmetysQueryRequest solrQuery = getSolrQuery(query, filterQueries, _start, _maxResults, _searchContext, _checkRights, _checkRightsComparingTo);
            
            // Set the sort specification and facets in the solr query object.
            setSort(solrQuery, _sortClauses);
            setFacets(solrQuery, _facets, _facetValues);
            
            modifySolrQuery(solrQuery);
            
            QueryResponse response = solrQuery.process(_solrClient, _solrClientProvider.getCollectionName());
            
            if (_logger.isInfoEnabled())
            {
                _logger.info("Solr request executed in {} ms", response.getQTime());
            }
            
            return response;
        }
        
        private void _logSearchQueries()
        {
            if (!_logger.isDebugEnabled())
            {
                return;
            }
            
            if (_queryString == null && _query != null)
            {
                _logger.debug("Query before building: \n{}", _query.toString(0));
            }
            
            if (!_filterQueries.isEmpty())
            {
                _logger.debug("Filter Queries before building: \n{}", _filterQueries
                        .stream()
                        .map(fq -> fq.toString(0))
                        .collect(Collectors.joining("\n###\n")));
            }
        }
        
        /**
         * Get the query string from the parameters.
         * @return The query string.
         * @throws QuerySyntaxException If the query is invalid.
         */
        protected Object getQuery() throws QuerySyntaxException
        {
            Object query = "*:*";
            
            if (_queryString != null)
            {
                query = _queryString;
            }
            else if (_query != null)
            {
                query = _query.rewrite().orElse(new MatchAllQuery())
                              .buildAsJson().orElse(new MatchAllQuery().buildAsJson());
            }
            
            return query;
        }
        
        /**
         * Get the filter queries from the parameters.
         * @return The list of filter queries.
         * @throws QuerySyntaxException If one of the queries is invalid.
         */
        protected List<Object> getFilterQueries() throws QuerySyntaxException
        {
            List<Object> filterQueries = new ArrayList<>();
            
            filterQueries.addAll(_filterQueryStrings);
            
            for (Query fq : _filterQueries)
            {
                // discard useless empty or "*:*" filter queries
                Optional<Query> query = fq.rewrite();
                if (query.isPresent() && !(query.get() instanceof MatchAllQuery))
                {
                    Optional<Object> fqAsJson = query.get().buildAsJson();
                    if (fqAsJson.isPresent())
                    {
                        filterQueries.add(fqAsJson.get());
                    }
                }
            }
            
            return filterQueries;
        }
        
        /**
         * Get the solr query object.
         * @param query The solr query string.
         * @param filterQueries The filter queries (as Strings).
         * @param start The start index.
         * @param maxResults The maximum number of results.
         * @param searchContext The search context.
         * @param checkRights Whether to check rights when searching or not.
         * @param allowedUsersToCompare The {@link AllowedUsers} object to compare with for checking rights
         * @return The solr query object.
         * @throws Exception If an error occurs.
         */
        @SuppressWarnings("unchecked")
        protected AmetysQueryRequest getSolrQuery(Object query, Collection<Object> filterQueries, int start, int maxResults, Map<String, Object> searchContext, boolean checkRights, AllowedUsers allowedUsersToCompare) throws Exception
        {
            AmetysQueryRequest solrQuery = new AmetysQueryRequest(_logger);
            
            if (query instanceof String q)
            {
                solrQuery.setQuery(StringUtils.isNotBlank(q) ? q : "*:*");
            }
            else if (query instanceof Map)
            {
                solrQuery.setQuery((Map<String, Object>) query);
            }
            
            // Set the query string, pagination spec and fields to be returned.
            if (start > 0)
            {
                solrQuery.setOffset(start);
            }
            
            solrQuery.setLimit(maxResults);
            
            solrQuery.returnFields("id", "score");
            
            // Add filter queries.
            for (Object fq : filterQueries)
            {
                if (fq instanceof String)
                {
                    solrQuery.withFilter((String) fq);
                }
                else if (fq instanceof Map)
                {
                    solrQuery.withFilter((Map<String, Object>) fq);
                }
            }
            
            if (checkRights)
            {
                _checkRightsQuery(solrQuery);
            }
            else if (allowedUsersToCompare != null)
            {
                _checkAllowedUsers(solrQuery, allowedUsersToCompare);
            }
            if (_highlightDefinition != null && _highlightDefinition.query() != null)
            {
                // hl.q="query"&hl.fl=*&hl.requireMatchField=true
                solrQuery.withParam(HighlightParams.HIGHLIGHT, true);
                solrQuery.withParam(HighlightParams.Q, _highlightDefinition.query().build());
                // returns fields in query that match
                solrQuery.withParam(HighlightParams.FIELDS, "*");
                solrQuery.withParam(HighlightParams.FIELD_MATCH, true);
                if (_highlightDefinition.snippets() > 0)
                {
                    solrQuery.withParam(HighlightParams.SNIPPETS, _highlightDefinition.snippets());
                }
                if (_highlightDefinition.fragSize() > 0)
                {
                    solrQuery.withParam(HighlightParams.FRAGSIZE, _highlightDefinition.fragSize());
                }
            }
            if (_debug)
            {
                solrQuery.withParam(CommonParams.DEBUG, "true");
            }
            
            return solrQuery;
        }
        
        private void _checkRightsQuery(JsonQueryRequest solrQuery)
        {
            Map<String, Object> acl;
            
            UserIdentity user = _currentUserProvider.getUser();
            if (user == null)
            {
                acl = Map.of("anonymous", "");
            }
            else
            {
                acl = new HashMap<>();
                acl.put("populationId", user.getPopulationId());
                acl.put("login", user.getLogin());
                
                Set<GroupIdentity> groups = _groupManager.getUserGroups(user);
                if (!groups.isEmpty())
                {
                    List<String> groupIds = groups.stream()
                            .map(GroupIdentity::groupIdentityToString)
                            .toList();
                    
                    acl.put("groups", groupIds);
                }
            }
            
            // {!acl anonymous=} or {!acl populationId=users login=user1 groups="group1#groupDirectory,group2#groupDirectory"} to check acl
            solrQuery.withFilter(Map.of("acl", acl));
        }
        
        private void _checkAllowedUsers(JsonQueryRequest solrQuery, AllowedUsers allowedUsersToCompare)
        {
            Map<String, Object> acl;
            
            if (allowedUsersToCompare.isAnonymousAllowed())
            {
                acl = Map.of("anonymous", "true");
            }
            else
            {
                acl = new HashMap<>();
                
                if (allowedUsersToCompare.isAnyConnectedUserAllowed())
                {
                    acl.put("anyConnected", "true");
                }
                
                Set<String> allowedUsers = allowedUsersToCompare.getAllowedUsers().stream().map(UserIdentity::userIdentityToString).collect(Collectors.toSet());
                Set<String> deniedUsers = allowedUsersToCompare.getDeniedUsers().stream().map(UserIdentity::userIdentityToString).collect(Collectors.toSet());
                Set<String> allowedGroups = allowedUsersToCompare.getAllowedGroups().stream().map(GroupIdentity::groupIdentityToString).collect(Collectors.toSet());
                Set<String> deniedGroups = allowedUsersToCompare.getDeniedGroups().stream().map(GroupIdentity::groupIdentityToString).collect(Collectors.toSet());
                
                if (!allowedUsers.isEmpty())
                {
                    acl.put("allowedUsers", allowedUsers);
                }
                
                if (!deniedUsers.isEmpty())
                {
                    acl.put("deniedUsers", deniedUsers);
                }
                
                if (!allowedGroups.isEmpty())
                {
                    acl.put("allowedGroups", allowedGroups);
                }
                
                if (!deniedGroups.isEmpty())
                {
                    acl.put("deniedGroups", deniedGroups);
                }
            }
            
            solrQuery.withFilter(Map.of("aclCompare", acl));
        }
        
        /**
         * Set the sort definition in the solr query object.
         * @param solrQuery The solr query object.
         * @param sortCriteria The sort criteria.
         */
        protected void setSort(JsonQueryRequest solrQuery, List<SortDefinition> sortCriteria)
        {
            if (sortCriteria.isEmpty())
            {
                solrQuery.setSort("score desc");
            }
            
            String sort = sortCriteria.stream()
                                      .map(sortCriterion -> _getSortFinalFieldName(sortCriterion) + " " + (sortCriterion.order() == SortOrder.ASC ? "asc" : "desc"))
                                      .collect(Collectors.joining(","));
            
            if (StringUtils.isNotBlank(sort))
            {
                solrQuery.setSort(sort);
            }
        }
        
        private String _getSortFinalFieldName(SortDefinition sortCriterion)
        {
            return sortCriterion.joinedPaths().isEmpty()
                    ? sortCriterion.solrSortFieldName()
                    : "ametys(" + _getJoinedFunction(sortCriterion.joinedPaths(), sortCriterion.solrSortFieldName()) + ")";
        }
        
        /**
         * Set the facet definition in the solr query object and return a mapping from solr field name to criterion ID.
         * @param solrQuery the solr query object to fill.
         * @param facetDefinitions The facet definitions to use.
         * @param facetValues the facet values.
         * @throws QuerySyntaxException if there's a syntax error in queries
         */
        protected void setFacets(JsonQueryRequest solrQuery, Collection<FacetDefinition> facetDefinitions, Map<String, List<String>> facetValues) throws QuerySyntaxException
        {
            List<String> joinedFacets = new ArrayList<>();
            for (FacetDefinition facetDefinition : facetDefinitions)
            {
                String fieldName = facetDefinition.id();
                String facetFieldName = facetDefinition.solrFacetFieldName();
                
                if (StringUtils.isNotBlank(fieldName))
                {
                    List<String> joinedPaths = facetDefinition.joinedPaths();
                    if (joinedPaths.isEmpty())
                    {
                        _setNonJoinedFacet(solrQuery, fieldName, facetFieldName, facetValues);
                    }
                    else
                    {
                        String joinedFacet = _setJoinedFacet(solrQuery, fieldName, joinedPaths, facetFieldName, facetValues);
                        joinedFacets.add(joinedFacet);
                    }
                }
            }
            
            if (!joinedFacets.isEmpty())
            {
                solrQuery.withParam("facet", "true");
                solrQuery.withParam("facet.ametys", joinedFacets);
            }
        }
        
        private String _setJoinedFacet(JsonQueryRequest solrQuery, String fieldName, List<String> joinedPaths, String solrFieldName, Map<String, List<String>> facetValues) throws QuerySyntaxException
        {
            List<String> fieldFacetValues = facetValues.get(fieldName);
            if (fieldFacetValues != null && !fieldFacetValues.isEmpty())
            {
                List<Query> facetQueries = new ArrayList<>();
                for (String facetValue : fieldFacetValues)
                {
                    facetQueries.add(() -> solrFieldName + ":\"" + facetValue + '"');
                }
                
                JoinQuery joinQuery = new JoinQuery(new OrQuery(facetQueries), joinedPaths);
                
                solrQuery.withFilter(Map.of("#" + fieldName, joinQuery.buildAsJson().orElse(new MatchAllQuery().buildAsJson())));
            }
            
            return "{!ex=" + fieldName + " key=" + fieldName + "}" + _getJoinedFunction(joinedPaths, solrFieldName);
        }
        
        private String _getJoinedFunction(List<String> joinedPaths, String solrFieldName)
        {
            return StringUtils.join(joinedPaths, "->") + "," + solrFieldName;
        }
        
        private void _setNonJoinedFacet(JsonQueryRequest solrQuery, String fieldName, String solrFieldName, Map<String, List<String>> facetValues) throws QuerySyntaxException
        {
            List<String> fieldFacetValues = facetValues.get(fieldName);
            if (fieldFacetValues != null && !fieldFacetValues.isEmpty())
            {
                List<Query> facetQueries = new ArrayList<>();
                for (String facetValue : fieldFacetValues)
                {
                    facetQueries.add(() -> solrFieldName + ":\"" + facetValue + '"');
                }
                
                solrQuery.withFilter(Map.of("#" + fieldName, new OrQuery(facetQueries).buildAsJson().orElse(new MatchAllQuery().buildAsJson())));
            }
            
            TermsFacetMap facetMap = new TermsFacetMap(solrFieldName).setLimit(-1)
                                                                     .withDomain(new DomainMap().withTagsToExclude(fieldName));
            
            solrQuery.withFacet(fieldName, facetMap);
        }
        
        /**
         * Retrieve the facet results from the solr response.
         * @param response the solr response.
         * @param facetDefinitions The facet fields to return.
         * @return the facet results.
         */
        protected Map<String, Map<String, Integer>> getFacetResults(QueryResponse response, Collection<FacetDefinition> facetDefinitions)
        {
            Map<String, Map<String, Integer>> facetResults = new LinkedHashMap<>();
            
            for (FacetDefinition facetDefinition : facetDefinitions)
            {
                String fieldName = facetDefinition.id();

                if (facetDefinition.joinedPaths().isEmpty())
                {
                    BucketBasedJsonFacet facet = response.getJsonFacetingResponse().getBucketBasedFacets(fieldName);
                    
                    List<BucketJsonFacet> values = facet.getBuckets();
                    
                    Map<String, Integer> solrFacetValues = new HashMap<>();
                    facetResults.put(fieldName, solrFacetValues);
                    
                    for (BucketJsonFacet value : values)
                    {
                        solrFacetValues.put(value.getVal().toString(), (int) value.getCount());
                    }
                }
                else
                {
                    FacetField solrFacetField = response.getFacetField(fieldName);
                     
                    List<Count> values = solrFacetField.getValues();
                     
                    Map<String, Integer> solrFacetValues = new HashMap<>();
                    facetResults.put(fieldName, solrFacetValues);
                                     
                    for (Count count : values)
                    {
                        solrFacetValues.put(count.getName(), (int) count.getCount());
                    }
                }
            }
            
            return facetResults;
        }
        
        /**
         * Template method to do additional operations on the Solr query before passing it to the Solr client
         * @param query the Solr query
         */
        protected void modifySolrQuery(JsonQueryRequest query)
        {
            // do nothing by default
        }
    }
    
    static class AmetysQueryRequest extends JsonQueryRequest
    {
        private Logger _logger;
        
        public AmetysQueryRequest(Logger logger)
        {
            super();
            _logger = logger;
        }
        
        @Override
        public ContentWriter getContentWriter(String expectedType)
        {
            ContentWriter writer = super.getContentWriter(expectedType);
            
            if (!_logger.isInfoEnabled())
            {
                return writer;
            }
            
            return new ContentWriter()
            {
                public void write(OutputStream os) throws IOException
                {
                    ByteArrayOutputStream baos = new ByteArrayOutputStream();
                    writer.write(baos);
                    
                    _logger.info("Solr query:\n" + baos.toString(StandardCharsets.UTF_8));
                    
                    os.write(baos.toByteArray(), 0, baos.size());
                }
                
                public String getContentType()
                {
                    return writer.getContentType();
                }
            };
        }
    }
    
    /**
     * Record representing a sort criterion.
     * @param solrSortFieldName the name of the solr sort field
     * @param joinedPaths the joined paths
     * @param order The sort order
     */
    public record SortDefinition (String solrSortFieldName, List<String> joinedPaths, SortOrder order) {
        
        /**
         * Creates a {@link SortDefinition} record
         * @param facetFieldName the name of the solr sort field
         * @param sortOrder The sort order
         */
        public SortDefinition(String facetFieldName, SortOrder sortOrder)
        {
            this(facetFieldName, new ArrayList<>(), sortOrder);
        }
    }
    
    /**
     * Record representing a facet definition.
     * @param id the facet identifier
     * @param solrFacetFieldName the name of the solr facet field
     * @param joinedPaths the joined paths
     */
    public record FacetDefinition (String id, String solrFacetFieldName, List<String> joinedPaths) {
        
        /**
         * Creates a {@link FacetDefinition} record
         * @param facetId the facet identifier
         * @param facetFieldName the name of the solr facet field
         */
        public FacetDefinition(String facetId, String facetFieldName)
        {
            this(facetId, facetFieldName, new ArrayList<>());
        }
    }

    /**
     * Record representing the highlighting parameters.
     * @param query The highlighting query
     * @param snippets The maximum number of fragments to return
     * @param fragSize The size of fragments in characters
     */
    public record HighlightDefinition(Query query, int snippets, int fragSize) { }
}