001package ca.uhn.fhir.rest.annotation;
002
003/*
004 * #%L
005 * HAPI FHIR - Core Library
006 * %%
007 * Copyright (C) 2014 - 2021 Smile CDR, Inc.
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.ElementType;
024import java.lang.annotation.Retention;
025import java.lang.annotation.RetentionPolicy;
026import java.lang.annotation.Target;
027
028import ca.uhn.fhir.model.api.Include;
029
030/**
031 * Method parameter which is used to indicate a parameter that will
032 * be populated with the "_include" (or "_revinclude") values for a search param.
033 * The parameter annotated with this annotation is used for either "_include"
034 * or "_revinclude", depending on whether {@link #reverse()} has been
035 * set to <code>true</code> (default is <code>false</code>).
036 * 
037 * <p>
038 * Only up to two parameters may be annotated with this annotation (one each
039 * for <code>reverse=false</code> and <code>reverse=true</code>. That
040 * parameter should be one of the following:
041 * </p> 
042 * <ul>
043 * <li><code>Collection&lt;Include&gt;</code></li> 
044 * <li><code>List&lt;Include&gt;</code></li> 
045 * <li><code>Set&lt;Include&gt;</code></li> 
046 * </ul>
047 * 
048 * @see Include
049 */
050@Retention(RetentionPolicy.RUNTIME)
051@Target(value= {ElementType.PARAMETER})
052public @interface IncludeParam {
053
054        /**
055         * Optional value, if provided the server will only allow the values
056         * within the given set. If an _include parameter is passed to the server
057         * which does not match any allowed values the server will return an error.
058         * <p>
059         * Values for this parameter take the form that the FHIR specification
060         * defines for <code>_include</code> values, namely <code>[Resource Name].[path]</code>.
061         * For example: <code>"Patient.link.other"</code>
062         * or <code>"Encounter.partOf"</code> 
063         * </p>
064         * <p>
065         * You may also pass in a value of "*" which indicates means that the
066         * client may request <code>_include=*</code>. This is a request to 
067         * include all referenced resources as well as any resources referenced
068         * by those resources, etc.
069         * </p>
070         * <p>
071         * Leave this parameter empty if you do not want the server to declare or
072         * restrict which includes are allowable. In this case, the client may add
073         * any _include value they want, and that value will be accepted by the server
074         * and passed to the handling method. Note that this means that the server 
075         * will not declare which _include values it supports in its conformance
076         * statement.
077         * </p> 
078         */
079        String[] allow() default {};
080        
081        /**
082         * If set to <code>true</code> (default is <code>false</code>), the values
083         * for this parameter correspond to the <code>_revinclude<code> parameter
084         * instead of the <code>_include<code> parameter.
085         */
086        boolean reverse() default false;
087        
088}