001/*
002 * #%L
003 * HAPI FHIR JPA Server
004 * %%
005 * Copyright (C) 2014 - 2024 Smile CDR, Inc.
006 * %%
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 * You may obtain a copy of the License at
010 *
011 *      http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 * #L%
019 */
020package ca.uhn.fhir.jpa.dao;
021
022import ca.uhn.fhir.jpa.model.entity.ResourceTable;
023import ca.uhn.fhir.jpa.model.search.ExtendedHSearchIndexData;
024import ca.uhn.fhir.jpa.search.autocomplete.ValueSetAutocompleteOptions;
025import ca.uhn.fhir.jpa.search.builder.ISearchQueryExecutor;
026import ca.uhn.fhir.jpa.searchparam.SearchParameterMap;
027import ca.uhn.fhir.jpa.searchparam.extractor.ResourceIndexedSearchParams;
028import ca.uhn.fhir.rest.api.server.RequestDetails;
029import ca.uhn.fhir.rest.api.server.storage.IResourcePersistentId;
030import org.hl7.fhir.instance.model.api.IBaseResource;
031
032import java.util.Collection;
033import java.util.List;
034
035public interface IFulltextSearchSvc {
036
037        /**
038         * Search the Lucene/Elastic index for pids using params supported in theParams,
039         * consuming entries from theParams when used to query.
040         *
041         * @param theResourceName   the resource name to restrict the query.
042         * @param theParams         the full query - modified to return only params unused by the index.
043         * @param theRequestDetails The request details
044         * @return the pid list for the matchign resources.
045         */
046        <T extends IResourcePersistentId> List<T> search(
047                        String theResourceName, SearchParameterMap theParams, RequestDetails theRequestDetails);
048
049        /**
050         * Query the index for a plain list (non-scrollable) iterator of results.
051         *
052         * @param theResourceName      e.g. Patient
053         * @param theParams            The search query
054         * @param theMaxResultsToFetch maximum results to fetch
055         * @param theRequestDetails The request details
056         * @return Iterator of result PIDs
057         */
058        ISearchQueryExecutor searchNotScrolled(
059                        String theResourceName,
060                        SearchParameterMap theParams,
061                        Integer theMaxResultsToFetch,
062                        RequestDetails theRequestDetails);
063
064        /**
065         * Autocomplete search for NIH $expand contextDirection=existing
066         * @param theOptions operation options
067         * @return a ValueSet with the search hits as the expansion.
068         */
069        IBaseResource tokenAutocompleteValueSetSearch(ValueSetAutocompleteOptions theOptions);
070
071        <T extends IResourcePersistentId> List<T> everything(
072                        String theResourceName,
073                        SearchParameterMap theParams,
074                        T theReferencingPid,
075                        RequestDetails theRequestDetails);
076
077        boolean isDisabled();
078
079        ExtendedHSearchIndexData extractLuceneIndexData(
080                        IBaseResource theResource, ResourceIndexedSearchParams theNewParams);
081
082        boolean supportsSomeOf(SearchParameterMap myParams);
083
084        /**
085         * Re-publish the resource to the full-text index.
086         *
087         * During update, hibernate search only republishes the entity if it has changed.
088         * During $reindex, we want to force the re-index.
089         *
090         * @param theEntity the fully populated ResourceTable entity
091         */
092        void reindex(ResourceTable theEntity);
093
094        List<IResourcePersistentId> lastN(SearchParameterMap theParams, Integer theMaximumResults);
095
096        /**
097         * Returns inlined resource stored along with index mappings for matched identifiers
098         *
099         * @param thePids raw pids - we dont support versioned references
100         * @return Resources list or empty if nothing found
101         */
102        List<IBaseResource> getResources(Collection<Long> thePids);
103
104        /**
105         * Returns accurate hit count
106         */
107        long count(String theResourceName, SearchParameterMap theParams);
108
109        List<IBaseResource> searchForResources(
110                        String theResourceType, SearchParameterMap theParams, RequestDetails theRequestDetails);
111
112        boolean supportsAllOf(SearchParameterMap theParams);
113
114        /**
115         * Given a resource type that is indexed by hibernate search, and a list of objects reprenting the IDs you wish to delete,
116         * this method will delete the resources from the Hibernate Search index. This is useful for situations where a deletion occurred
117         * outside a Hibernate ORM session, leaving dangling documents in the index.
118         *
119         * @param theClazz The class, which must be annotated with {@link  org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed}
120         * @param theGivenIds The list of IDs for the given document type. Note that while this is a List<Object>, the type must match the type of the `@Id` field on the given class.
121         */
122        void deleteIndexedDocumentsByTypeAndId(Class theClazz, List<Object> theGivenIds);
123}