001package ca.uhn.fhir.rest.server.util;
002
003/*
004 * #%L
005 * HAPI FHIR - Server Framework
006 * %%
007 * Copyright (C) 2014 - 2022 Smile CDR, Inc.
008 * %%
009 * Licensed under the Apache License, Version 2.0 (the "License");
010 * you may not use this file except in compliance with the License.
011 * You may obtain a copy of the License at
012 *
013 *      http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing, software
016 * distributed under the License is distributed on an "AS IS" BASIS,
017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018 * See the License for the specific language governing permissions and
019 * limitations under the License.
020 * #L%
021 */
022
023import ca.uhn.fhir.context.RuntimeSearchParam;
024import ca.uhn.fhir.context.phonetic.IPhoneticEncoder;
025import ca.uhn.fhir.i18n.Msg;
026import ca.uhn.fhir.rest.api.Constants;
027import ca.uhn.fhir.rest.server.exceptions.InvalidRequestException;
028import org.hl7.fhir.instance.model.api.IAnyResource;
029
030import javax.annotation.Nullable;
031import java.util.Collection;
032import java.util.Collections;
033import java.util.List;
034import java.util.Set;
035import java.util.TreeSet;
036
037// TODO: JA remove default methods
038public interface ISearchParamRegistry {
039
040        /**
041         * @return Returns {@literal null} if no match
042         */
043        RuntimeSearchParam getActiveSearchParam(String theResourceName, String theParamName);
044
045
046        /**
047         * @return Returns all active search params for the given resource
048         */
049        ResourceSearchParams getActiveSearchParams(String theResourceName);
050
051        /**
052         * Request that the cache be refreshed now, in the current thread
053         */
054        default void forceRefresh() {
055        }
056
057        /**
058         * Request that the cache be refreshed at the next convenient time (in a different thread)
059         */
060        default void requestRefresh() {
061        }
062
063        /**
064         * When indexing a HumanName, if a StringEncoder is set in the context, then the "phonetic" search parameter will normalize
065         * the String using this encoder.
066         *
067         * @since 5.1.0
068         */
069        default void setPhoneticEncoder(IPhoneticEncoder thePhoneticEncoder) {
070        }
071
072        default List<RuntimeSearchParam> getActiveComboSearchParams(String theResourceName) {
073                return Collections.emptyList();
074        }
075
076        default List<RuntimeSearchParam> getActiveComboSearchParams(String theResourceName, Set<String> theParamNames) {
077                return Collections.emptyList();
078        }
079
080        /**
081         * Returns a collection containing all of the valid active search parameters. This method is intended for
082         * creating error messages for users as opposed to actual search processing. It will include meta parameters
083         * such as <code>_id</code> and <code>_lastUpdated</code>.
084         */
085        default Collection<String> getValidSearchParameterNamesIncludingMeta(String theResourceName) {
086                TreeSet<String> retval;
087                ResourceSearchParams activeSearchParams = getActiveSearchParams(theResourceName);
088                if (activeSearchParams == null) {
089                        retval = new TreeSet<>();
090                } else {
091                        retval = new TreeSet<>(activeSearchParams.getSearchParamNames());
092                }
093                retval.add(IAnyResource.SP_RES_ID);
094                retval.add(Constants.PARAM_LASTUPDATED);
095                return retval;
096        }
097
098        /**
099         * Fetch a SearchParameter by URL
100         *
101         * @return Returns <code>null</code> if it can't be found
102         */
103        @Nullable
104        RuntimeSearchParam getActiveSearchParamByUrl(String theUrl);
105
106        /**
107         * Find a search param for a resource. First, check the resource itself, then check the top-level `Resource` resource.
108         *
109         * @param theResourceType the resource type.
110         * @param theParamName the search parameter name.
111         *
112         * @return the {@link RuntimeSearchParam} that is found.
113         */
114        default RuntimeSearchParam getRuntimeSearchParam(String theResourceType, String theParamName) {
115                RuntimeSearchParam availableSearchParamDef = getActiveSearchParam(theResourceType, theParamName);
116                if (availableSearchParamDef == null) {
117                        availableSearchParamDef = getActiveSearchParam("Resource", theParamName);
118                }
119                if (availableSearchParamDef == null) {
120                        throw new InvalidRequestException(Msg.code(1209) + "Unknown parameter name: " + theResourceType + ':' + theParamName);
121                }
122                return availableSearchParamDef;
123        }
124}