001/*-
002 * #%L
003 * HAPI FHIR - Core Library
004 * %%
005 * Copyright (C) 2014 - 2025 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.rest.param;
021
022import ca.uhn.fhir.context.FhirContext;
023import ca.uhn.fhir.i18n.Msg;
024import ca.uhn.fhir.model.api.IQueryParameterType;
025import ca.uhn.fhir.rest.api.Constants;
026import ca.uhn.fhir.rest.server.exceptions.InvalidRequestException;
027
028import static org.apache.commons.lang3.StringUtils.isBlank;
029import static org.apache.commons.lang3.StringUtils.isNotBlank;
030
031/**
032 * Base class for RESTful operation parameter types
033 */
034public abstract class BaseParam implements IQueryParameterType {
035
036        private Boolean myMissing;
037
038        abstract String doGetQueryParameterQualifier();
039
040        abstract String doGetValueAsQueryToken();
041
042        abstract void doSetValueAsQueryToken(
043                        FhirContext theContext, String theParamName, String theQualifier, String theValue);
044
045        /**
046         * If set to non-null value, indicates that this parameter has been populated with a "[name]:missing=true" or "[name]:missing=false" vale instead of a normal value
047         */
048        @Override
049        public Boolean getMissing() {
050                return myMissing;
051        }
052
053        @Override
054        public final String getQueryParameterQualifier() {
055                if (myMissing != null) {
056                        return Constants.PARAMQUALIFIER_MISSING;
057                }
058                return doGetQueryParameterQualifier();
059        }
060
061        @Override
062        public final String getValueAsQueryToken() {
063                if (myMissing != null) {
064                        return myMissing ? Constants.PARAMQUALIFIER_MISSING_TRUE : Constants.PARAMQUALIFIER_MISSING_FALSE;
065                }
066                return doGetValueAsQueryToken();
067        }
068
069        /**
070         * Does this parameter type support chained parameters (only reference should return <code>true</code> for this)
071         */
072        protected boolean isSupportsChain() {
073                return false;
074        }
075
076        /**
077         * If set to non-null value, indicates that this parameter has been populated
078         * with a "[name]:missing=true" or "[name]:missing=false" value instead of a
079         * normal value
080         *
081         * @return Returns a reference to <code>this</code> for easier method chaining
082         */
083        @Override
084        public BaseParam setMissing(Boolean theMissing) {
085                myMissing = theMissing;
086                return this;
087        }
088
089        @Override
090        public final void setValueAsQueryToken(
091                        FhirContext theContext, String theParamName, String theQualifier, String theValue) {
092                if (Constants.PARAMQUALIFIER_MISSING.equals(theQualifier)) {
093                        myMissing = "true".equals(theValue);
094                        doSetValueAsQueryToken(theContext, theParamName, null, null);
095                } else {
096                        if (isNotBlank(theQualifier) && theQualifier.charAt(0) == '.') {
097                                if (!isSupportsChain()) {
098                                        String msg = theContext
099                                                        .getLocalizer()
100                                                        .getMessage(
101                                                                        BaseParam.class, "chainNotSupported", theParamName + theQualifier, theQualifier);
102                                        throw new InvalidRequestException(Msg.code(1935) + msg);
103                                }
104                        }
105
106                        myMissing = null;
107                        doSetValueAsQueryToken(theContext, theParamName, theQualifier, theValue);
108                }
109        }
110
111        /**
112         * Returns {@literal true} if this parameter has a {@literal null} or empty {@link #getValueAsQueryToken()}
113         * value, and doesn't have a {@link #getMissing()} value.
114         *
115         * @since 8.4.0
116         */
117        public boolean isEmpty() {
118                return isBlank(getValueAsQueryToken()) && getMissing() == null;
119        }
120}