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