001package ca.uhn.fhir.model.api.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.IElement;
029
030/**
031 * Field annotation for fields within resource and datatype definitions, indicating 
032 * a child of that type.
033 */
034@Retention(RetentionPolicy.RUNTIME)
035@Target(value= {ElementType.FIELD})
036public @interface Child {
037
038        /**
039         * Constant value to supply for {@link #order()} when the order is defined
040         * elsewhere
041         */
042        int ORDER_UNKNOWN = -1;
043        
044        /**
045         * Constant value to supply for {@link #max()} to indicate '*' (no maximum)
046         */
047        int MAX_UNLIMITED = -1;
048
049        /**
050         * Constant value to supply for {@link #order()} to indicate that this child should replace the
051         * entry in the superclass with the same name (and take its {@link Child#order() order} value 
052         * in the process). This is useful if you wish to redefine an existing field in a resource/type
053         * definition in order to constrain/extend it.
054         */
055        int REPLACE_PARENT = -2;
056
057        /**
058         * The name of this field, as it will appear in serialized versions of the message
059         */
060        String name();
061        
062        /**
063         * The order in which this field comes within its parent. The first field should have a 
064         * value of 0, the second a value of 1, etc.
065         */
066        int order() default ORDER_UNKNOWN;
067
068        /**
069         * The minimum number of repetitions allowed for this child
070         */
071        int min() default 0;
072
073        /**
074         * The maximum number of repetitions allowed for this child. Should be
075         * set to {@link #MAX_UNLIMITED} if there is no limit to the number of
076         * repetitions.
077         */
078        int max() default 1;
079
080        /**
081         * Lists the allowable types for this field, if the field supports multiple
082         * types (otherwise does not need to be populated).
083         * <p>
084         * For example, if this field supports either DateTimeDt or BooleanDt types,
085         * those two classes should be supplied here.
086         * </p>
087         */
088        Class<? extends IElement>[] type() default {};
089
090        // Not implemented
091//      /**
092//       * This value is used when extending a built-in model class and defining a
093//       * field to replace a field within the built-in class. For example, the {@link Patient} 
094//       * resource has a {@link Patient#getName() name} field, but if you wanted to extend Patient and
095//       * provide your own implementation of {@link HumanNameDt} (most likely your own subclass of 
096//       * HumanNameDt which adds extensions of your choosing) you could do that using a replacement field. 
097//       */
098//      String replaces() default "";
099
100        /**
101         * Is this element a modifier?
102         */
103        boolean modifier() default false;       
104
105        /**
106         * Should this element be included in the summary view
107         */
108        boolean summary() default false;
109        
110}