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 java.util.Objects;
029
030import static org.apache.commons.lang3.StringUtils.isBlank;
031import static org.apache.commons.lang3.StringUtils.isNotBlank;
032
033/**
034 * Base class for RESTful operation parameter types
035 */
036public abstract class BaseParam implements IQueryParameterType {
037
038        private Boolean myMissing;
039
040        abstract String doGetQueryParameterQualifier();
041
042        abstract String doGetValueAsQueryToken();
043
044        abstract void doSetValueAsQueryToken(
045                        FhirContext theContext, String theParamName, String theQualifier, String theValue);
046
047        /**
048         * 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
049         */
050        @Override
051        public Boolean getMissing() {
052                return myMissing;
053        }
054
055        /**
056         * If set to non-null value, indicates that this parameter has been populated
057         * with a "[name]:missing=true" or "[name]:missing=false" value instead of a
058         * normal value
059         *
060         * @return Returns a reference to <code>this</code> for easier method chaining
061         */
062        @Override
063        public BaseParam setMissing(Boolean theMissing) {
064                myMissing = theMissing;
065                return this;
066        }
067
068        @Override
069        public final String getQueryParameterQualifier() {
070                if (myMissing != null) {
071                        return Constants.PARAMQUALIFIER_MISSING;
072                }
073                return doGetQueryParameterQualifier();
074        }
075
076        @Override
077        public final String getValueAsQueryToken() {
078                if (myMissing != null) {
079                        return myMissing ? Constants.PARAMQUALIFIER_MISSING_TRUE : Constants.PARAMQUALIFIER_MISSING_FALSE;
080                }
081                return doGetValueAsQueryToken();
082        }
083
084        /**
085         * Does this parameter type support chained parameters (only reference should return <code>true</code> for this)
086         */
087        protected boolean isSupportsChain() {
088                return false;
089        }
090
091        @Override
092        public final void setValueAsQueryToken(
093                        FhirContext theContext, String theParamName, String theQualifier, String theValue) {
094                if (Constants.PARAMQUALIFIER_MISSING.equals(theQualifier)) {
095                        myMissing = "true".equals(theValue);
096                        doSetValueAsQueryToken(theContext, theParamName, null, null);
097                } else {
098                        if (isNotBlank(theQualifier) && theQualifier.charAt(0) == '.') {
099                                if (!isSupportsChain()) {
100                                        String msg = theContext
101                                                        .getLocalizer()
102                                                        .getMessage(
103                                                                        BaseParam.class, "chainNotSupported", theParamName + theQualifier, theQualifier);
104                                        throw new InvalidRequestException(Msg.code(1935) + msg);
105                                }
106                        }
107
108                        myMissing = null;
109                        doSetValueAsQueryToken(theContext, theParamName, theQualifier, theValue);
110                }
111        }
112
113        /**
114         * Returns {@literal true} if this parameter has a {@literal null} or empty {@link #getValueAsQueryToken()}
115         * value, and doesn't have a {@link #getMissing()} value.
116         *
117         * @since 8.4.0
118         */
119        public boolean isEmpty() {
120                return isBlank(getValueAsQueryToken()) && getMissing() == null;
121        }
122
123        @Override
124        public boolean equals(Object theO) {
125                if (!(theO instanceof BaseParam baseParam)) {
126                        return false;
127                }
128                return Objects.equals(this.getValueAsQueryToken(), baseParam.getValueAsQueryToken())
129                                && Objects.equals(myMissing, baseParam.myMissing);
130        }
131
132        @Override
133        public int hashCode() {
134                return Objects.hash(getValueAsQueryToken(), myMissing);
135        }
136}