
001package ca.uhn.fhir.rest.annotation; 002 003/* 004 * #%L 005 * HAPI FHIR - Core Library 006 * %% 007 * Copyright (C) 2014 - 2023 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 ca.uhn.fhir.model.valueset.BundleTypeEnum; 024import org.hl7.fhir.instance.model.api.IBaseResource; 025 026import java.lang.annotation.ElementType; 027import java.lang.annotation.Retention; 028import java.lang.annotation.RetentionPolicy; 029import java.lang.annotation.Target; 030 031/** 032 * RESTful method annotation used for a method which provides FHIR "operations". 033 */ 034@Retention(RetentionPolicy.RUNTIME) 035@Target(value = ElementType.METHOD) 036public @interface Operation { 037 038 /** 039 * This constant is a special return value for {@link #name()}. If this name is 040 * used, the given operation method will match all operation calls. This is 041 * generally not desirable, but can be useful if you have a server that should 042 * dynamically match any FHIR operations that are requested. 043 */ 044 String NAME_MATCH_ALL = "*"; 045 046 /** 047 * The name of the operation, e.g. "<code>$everything</code>" 048 * 049 * <p> 050 * This may be specified with or without a leading 051 * '$'. (If the leading '$' is omitted, it will be added internally by the API). 052 * </p> 053 */ 054 String name(); 055 056 /** 057 * This value may be populated with the resource type that the operation applies to. If set to 058 * {@link IBaseResource} (which is the default) than the operation applies to the server and not to a specific 059 * resource type. 060 * <p> 061 * This attribute should not be used a resource provider implementing 062 * <code>IResourceProvider</code> since the type can be inferred from the 063 * resource provider type. 064 * </p> 065 * @see #typeName() may also be used to specify a value as a String 066 */ 067 Class<? extends IBaseResource> type() default IBaseResource.class; 068 069 /** 070 * This value may be populated with the resource type that the operation applies to. If set to 071 * {@link IBaseResource} (which is the default) than the operation applies to the server and not to a specific 072 * resource type. 073 * <p> 074 * This attribute should not be used a resource provider implementing 075 * <code>IResourceProvider</code> since the type can be inferred from the 076 * resource provider type. 077 * </p> 078 * @see #type() may also be used to specify a value for this setting as a class type 079 */ 080 String typeName() default ""; 081 082 /** 083 * If a given operation method is <b><a href="http://en.wikipedia.org/wiki/Idempotence">idempotent</a></b> 084 * (meaning roughly that it does not modify any data or state on the server) 085 * then this flag should be set to <code>true</code> (default is <code>false</code>). 086 * <p> 087 * One the server, setting this to <code>true</code> means that the 088 * server will allow the operation to be invoked using an <code>HTTP GET</code> 089 * (on top of the standard <code>HTTP POST</code>) 090 * </p> 091 */ 092 boolean idempotent() default false; 093 094 /** 095 * To support cancelling of a job, 096 * this flag should be set to <code>true</code> (default is <code>false</code>). 097 * <p> 098 * The server, when setting this to <code>true</code>, 099 * will allow the operation to be invoked using an <code>HTTP DELETE</code> 100 * (on top of the standard <code>HTTP POST</code>) 101 * </p> 102 */ 103 boolean deleteEnabled() default false; 104 105 /** 106 * This parameter may be used to specify the parts which will be found in the 107 * response to this operation. 108 */ 109 OperationParam[] returnParameters() default {}; 110 111 /** 112 * If this operation returns a bundle, this parameter can be used to specify the 113 * bundle type to set in the bundle. 114 */ 115 BundleTypeEnum bundleType() default BundleTypeEnum.COLLECTION; 116 117 /** 118 * If this is set to <code>true</code> (default is <code>false</code> and this is almost 119 * always the right choice), the framework will not attempt to generate a response to 120 * this method. 121 * <p> 122 * This is useful if you want to include an {@link javax.servlet.http.HttpServletResponse} 123 * in your method parameters and create a response yourself directly from your 124 * <code>@Operation</code> method. 125 * </p> 126 * <p> 127 * Note that this will mean that interceptor methods will not get fired for the 128 * response, so there are security implications to using this flag. 129 * </p> 130 */ 131 boolean manualResponse() default false; 132 133 /** 134 * If this is set to <code>true</code> (default is <code>false</code> and this is almost 135 * always the right choice), the framework will not attempt to parse the request body, 136 * but will instead delegate it to the <code>@Operation</code> method. 137 * <p> 138 * This is useful if you want to include an {@link javax.servlet.http.HttpServletRequest} 139 * in your method parameters and parse the request yourself. 140 * </p> 141 */ 142 boolean manualRequest() default false; 143 144 /** 145 * If this is set to <code>true</code>, this method will be a <b>global operation</b> 146 * meaning that it applies to all resource types. Operations with this flag set should be 147 * placed in Plain Providers (i.e. they don't need to be placed in a resource-type-specific 148 * <code>IResourceProvider</code> instance) and should have a parameter annotated with 149 * {@link IdParam}. 150 */ 151 boolean global() default false; 152 153 /** 154 * The canonical URL of the operation, e.g. "http://hl7.org/fhir/us/davinci-hrex/OperationDefinition/member-match|1.0.0" 155 * 156 * <p> 157 * This may be specified with or without a version. e.g. @Operation(name = "$everything", canonicalUrl = "http://hl7.org/fhir/OperationDefinition/Patient-everything") 158 * or @Operation(name = "$member-match", canonicalUrl = "http://hl7.org/fhir/us/davinci-hrex/OperationDefinition/member-match|1.0.0") 159 * </p> 160 */ 161 String canonicalUrl() default ""; 162 163}