001package ca.uhn.fhir.model.primitive;
002
003import java.util.Calendar;
004
005/*
006 * #%L
007 * HAPI FHIR - Core Library
008 * %%
009 * Copyright (C) 2014 - 2021 Smile CDR, Inc.
010 * %%
011 * Licensed under the Apache License, Version 2.0 (the "License");
012 * you may not use this file except in compliance with the License.
013 * You may obtain a copy of the License at
014 *
015 *      http://www.apache.org/licenses/LICENSE-2.0
016 *
017 * Unless required by applicable law or agreed to in writing, software
018 * distributed under the License is distributed on an "AS IS" BASIS,
019 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020 * See the License for the specific language governing permissions and
021 * limitations under the License.
022 * #L%
023 */
024
025import java.util.Date;
026import java.util.GregorianCalendar;
027import java.util.TimeZone;
028
029import ca.uhn.fhir.model.api.TemporalPrecisionEnum;
030import ca.uhn.fhir.model.api.annotation.DatatypeDef;
031import ca.uhn.fhir.model.api.annotation.SimpleSetter;
032import ca.uhn.fhir.parser.DataFormatException;
033
034/**
035 * Represents a FHIR date datatype. Valid precisions values for this type are:
036 * <ul>
037 * <li>{@link TemporalPrecisionEnum#YEAR}
038 * <li>{@link TemporalPrecisionEnum#MONTH}
039 * <li>{@link TemporalPrecisionEnum#DAY}
040 * </ul>
041 * 
042 * <p>
043 * <b>Note on using Java Date objects:</b> This type stores the date as a Java Date. Note that
044 * the Java Date has more precision (millisecond precision), and does not store a timezone. As such,
045 * it could potentially cause issues. For example, if a Date contains the number of milliseconds at
046 * midnight in a timezone across the date line from your location, it might refer to a different date than
047 * intended.
048 * </p>
049 * <p>
050 * As such, it is recommended to use the <code>Calendar<code> or <code>int,int,int</code> constructors  
051 * </p>
052 */
053@DatatypeDef(name = "date")
054public class DateDt extends BaseDateTimeDt {
055
056        /**
057         * The default precision for this type
058         */
059        public static final TemporalPrecisionEnum DEFAULT_PRECISION = TemporalPrecisionEnum.DAY;
060
061        /**
062         * Constructor
063         */
064        public DateDt() {
065                super();
066        }
067
068        /**
069         * Constructor which accepts a date value and uses the {@link #DEFAULT_PRECISION} for this type.
070         */
071        public DateDt(Calendar theCalendar) {
072                super(theCalendar.getTime(), DEFAULT_PRECISION);
073                setTimeZone(theCalendar.getTimeZone());
074        }
075
076        /**
077         * Constructor which accepts a date value and uses the {@link #DEFAULT_PRECISION} for this type.
078         * <b>Please see the note on timezones</b> on the {@link DateDt class documentation} for considerations
079         * when using this constructor!
080         */
081        @SimpleSetter(suffix = "WithDayPrecision")
082        public DateDt(@SimpleSetter.Parameter(name = "theDate") Date theDate) {
083                super(theDate, DEFAULT_PRECISION);
084        }
085
086        /**
087         * Constructor which accepts a date value and a precision value. Valid precisions values for this type are:
088         * <ul>
089         * <li>{@link TemporalPrecisionEnum#YEAR}
090         * <li>{@link TemporalPrecisionEnum#MONTH}
091         * <li>{@link TemporalPrecisionEnum#DAY}
092         * </ul>
093         * <b>Please see the note on timezones</b> on the {@link DateDt class documentation} for considerations
094         * when using this constructor!
095         * 
096         * @throws DataFormatException
097         *             If the specified precision is not allowed for this type
098         */
099        @SimpleSetter
100        public DateDt(@SimpleSetter.Parameter(name = "theDate") Date theDate, @SimpleSetter.Parameter(name = "thePrecision") TemporalPrecisionEnum thePrecision) {
101                super(theDate, thePrecision);
102        }
103
104        /**
105         * Constructor which accepts a date value and uses the {@link #DEFAULT_PRECISION} for this type.
106         * 
107         * @param theYear The year, e.g. 2015
108         * @param theMonth The month, e.g. 0 for January
109         * @param theDay The day (1 indexed) e.g. 1 for the first day of the month
110         */
111        public DateDt(int theYear, int theMonth, int theDay) {
112                this(toCalendarZulu(theYear, theMonth, theDay));
113        }
114
115        /**
116         * Constructor which accepts a date as a string in FHIR format
117         * 
118         * @throws DataFormatException
119         *             If the precision in the date string is not allowed for this type
120         */
121        public DateDt(String theDate) {
122                super(theDate);
123        }
124
125        /**
126         * Returns the default precision for this datatype
127         * 
128         * @see #DEFAULT_PRECISION
129         */
130        @Override
131        protected TemporalPrecisionEnum getDefaultPrecisionForDatatype() {
132                return DEFAULT_PRECISION;
133        }
134
135        @Override
136        protected boolean isPrecisionAllowed(TemporalPrecisionEnum thePrecision) {
137                switch (thePrecision) {
138                case YEAR:
139                case MONTH:
140                case DAY:
141                        return true;
142                default:
143                        return false;
144                }
145        }
146
147        private static GregorianCalendar toCalendarZulu(int theYear, int theMonth, int theDay) {
148                GregorianCalendar retVal = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
149                retVal.set(Calendar.YEAR, theYear);
150                retVal.set(Calendar.MONTH, theMonth);
151                retVal.set(Calendar.DATE, theDay);
152                return retVal;
153        }
154
155}