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