001/*
002 * #%L
003 * HAPI FHIR - Core Library
004 * %%
005 * Copyright (C) 2014 - 2023 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.annotation;
021
022import java.lang.annotation.ElementType;
023
024import java.lang.annotation.Retention;
025import java.lang.annotation.RetentionPolicy;
026import java.lang.annotation.Target;
027
028import org.hl7.fhir.instance.model.api.IBaseResource;
029
030import ca.uhn.fhir.model.api.IQueryParameterType;
031import ca.uhn.fhir.rest.param.CompositeParam;
032import ca.uhn.fhir.rest.param.ReferenceParam;
033
034/**
035 * Parameter annotation which specifies a search parameter for a {@link Search} method.
036 */
037@Retention(RetentionPolicy.RUNTIME)
038@Target(value=ElementType.PARAMETER)
039public @interface OptionalParam {
040
041        public static final String ALLOW_CHAIN_ANY = "*";
042
043        public static final String ALLOW_CHAIN_NOTCHAINED = "";
044
045        /**
046         * For reference parameters ({@link ReferenceParam}) this value may be
047         * used to indicate which chain values (if any) are <b>not</b> valid
048         * for the given parameter. Values here will supercede any values specified
049         * in {@link #chainWhitelist()}
050         * <p>
051         * If the parameter annotated with this annotation is not a {@link ReferenceParam},
052         * this value must not be populated.
053         * </p>
054         */
055        String[] chainBlacklist() default {};
056
057        /**
058         * For reference parameters ({@link ReferenceParam}) this value may be
059         * used to indicate which chain values (if any) are valid for the given
060         * parameter. If the list contains the value {@link #ALLOW_CHAIN_ANY}, all values are valid. (this is the default)
061         * If the list contains the value {@link #ALLOW_CHAIN_NOTCHAINED}
062         * then the reference param only supports the empty chain (i.e. the resource
063         * ID).
064         * <p>
065         * Valid values for this parameter include:
066         * </p>
067         * <ul>
068         * <li><code>chainWhitelist={ OptionalParam.ALLOW_CHAIN_NOTCHAINED }</code> - Only allow resource reference (no chaining allowed for this parameter)</li>
069         * <li><code>chainWhitelist={ OptionalParam.ALLOW_CHAIN_ANY }</code> - Allow any chaining at all (including a non chained value, <b>this is the default</b>)</li>
070         * <li><code>chainWhitelist={ "foo", "bar" }</code> - Allow property.foo and property.bar</li>
071         * </ul>
072         * <p>
073         * Any values specified in
074         * {@link #chainBlacklist()} will supercede (have priority over) values
075         * here.
076         * </p>
077         * <p>
078         * If the parameter annotated with this annotation is not a {@link ReferenceParam},
079         * this value must not be populated.
080         * </p>
081         */
082        String[] chainWhitelist() default { ALLOW_CHAIN_ANY };
083
084        /**
085         * For composite parameters ({@link CompositeParam}) this value may be
086         * used to indicate the parameter type(s) which may be referenced by this param.
087         * <p>
088         * If the parameter annotated with this annotation is not a {@link CompositeParam},
089         * this value must not be populated.
090         * </p>
091         */
092        Class<? extends IQueryParameterType>[] compositeTypes() default {};
093
094        /**
095         * This is the name for the parameter. Generally this should be a
096         * simple string (e.g. "name", or "identifier") which will be the name
097         * of the URL parameter used to populate this method parameter.
098         * <p>
099         * Most resource model classes have constants which may be used to
100         * supply values for this field, e.g. <code>Patient.SP_NAME</code> or
101         * <code>Observation.SP_DATE</code>
102         * </p>
103         * <p>
104         * If you wish to specify a parameter for a resource reference which
105         * only accepts a specific chained value, it is also valid to supply
106         * a chained name here, such as "patient.name". It is recommended to
107         * supply this using constants where possible, e.g.
108         * <code>Observation.SP_SUBJECT + '.' + Patient.SP_IDENTIFIER</code>
109         * </p>
110         */
111        String name();
112
113        /**
114         * For resource reference parameters ({@link ReferenceParam}) this value may be
115         * used to indicate the resource type(s) which may be referenced by this param.
116         * <p>
117         * If the parameter annotated with this annotation is not a {@link ReferenceParam},
118         * this value must not be populated.
119         * </p>
120         */
121        Class<? extends IBaseResource>[] targetTypes() default {};
122}