001package ca.uhn.fhir.rest.annotation;
002
003/*
004 * #%L
005 * HAPI FHIR - Core Library
006 * %%
007 * Copyright (C) 2014 - 2018 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 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         * On a client, this value should 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 value has no effect when used on server implementations.
062         * </p>
063         */
064        Class<? extends IBaseResource> type() default IBaseResource.class;
065
066        /**
067         * If a given operation method is <b><a href="http://en.wikipedia.org/wiki/Idempotence">idempotent</a></b>
068         * (meaning roughly that it does not modify any data or state on the server)
069         * then this flag should be set to <code>true</code> (default is <code>false</code>).
070         * <p>
071         * One the server, setting this to <code>true</code> means that the
072         * server will allow the operation to be invoked using an <code>HTTP GET</code>
073         * (on top of the standard <code>HTTP POST</code>)
074         * </p>
075         */
076        boolean idempotent() default false;
077
078        /**
079         * This parameter may be used to specify the parts which will be found in the
080         * response to this operation.
081         */
082        OperationParam[] returnParameters() default {};
083
084        /**
085         * If this operation returns a bundle, this parameter can be used to specify the
086         * bundle type to set in the bundle.
087         */
088        BundleTypeEnum bundleType() default BundleTypeEnum.COLLECTION;
089
090}