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}