001package ca.uhn.fhir.model.primitive;
002
003/*
004 * #%L
005 * HAPI FHIR - Core Library
006 * %%
007 * Copyright (C) 2014 - 2020 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.api.BasePrimitive;
024import ca.uhn.fhir.model.api.TemporalPrecisionEnum;
025import ca.uhn.fhir.parser.DataFormatException;
026import org.apache.commons.lang3.StringUtils;
027import org.apache.commons.lang3.Validate;
028import org.apache.commons.lang3.time.DateUtils;
029import org.apache.commons.lang3.time.FastDateFormat;
030
031import java.util.Calendar;
032import java.util.Date;
033import java.util.GregorianCalendar;
034import java.util.TimeZone;
035
036import static org.apache.commons.lang3.StringUtils.isBlank;
037
038public abstract class BaseDateTimeDt extends BasePrimitive<Date> {
039        static final long NANOS_PER_MILLIS = 1000000L;
040        static final long NANOS_PER_SECOND = 1000000000L;
041
042        private static final FastDateFormat ourHumanDateFormat = FastDateFormat.getDateInstance(FastDateFormat.MEDIUM);
043        private static final FastDateFormat ourHumanDateTimeFormat = FastDateFormat.getDateTimeInstance(FastDateFormat.MEDIUM, FastDateFormat.MEDIUM);
044        private static final FastDateFormat ourXmlDateTimeFormat = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
045        public static final String NOW_DATE_CONSTANT = "%now";
046        public static final String TODAY_DATE_CONSTANT = "%today";
047        private String myFractionalSeconds;
048        private TemporalPrecisionEnum myPrecision = null;
049        private TimeZone myTimeZone;
050        private boolean myTimeZoneZulu = false;
051
052        /**
053         * Constructor
054         */
055        public BaseDateTimeDt() {
056                // nothing
057        }
058
059        /**
060         * Constructor
061         * 
062         * @throws DataFormatException
063         *            If the specified precision is not allowed for this type
064         */
065        public BaseDateTimeDt(Date theDate, TemporalPrecisionEnum thePrecision) {
066                setValue(theDate, thePrecision);
067                if (isPrecisionAllowed(thePrecision) == false) {
068                        throw new DataFormatException("Invalid date/time string (datatype " + getClass().getSimpleName() + " does not support " + thePrecision + " precision): " + theDate);
069                }
070        }
071
072        /**
073         * Constructor
074         */
075        public BaseDateTimeDt(Date theDate, TemporalPrecisionEnum thePrecision, TimeZone theTimeZone) {
076                this(theDate, thePrecision);
077                setTimeZone(theTimeZone);
078        }
079
080        /**
081         * Constructor
082         * 
083         * @throws DataFormatException
084         *            If the specified precision is not allowed for this type
085         */
086        public BaseDateTimeDt(String theString) {
087                setValueAsString(theString);
088                validatePrecisionAndThrowDataFormatException(theString, getPrecision());
089        }
090
091        private void clearTimeZone() {
092                myTimeZone = null;
093                myTimeZoneZulu = false;
094        }
095
096        @Override
097        protected String encode(Date theValue) {
098                if (theValue == null) {
099                        return null;
100                }
101                GregorianCalendar cal;
102                if (myTimeZoneZulu) {
103                        cal = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
104                } else if (myTimeZone != null) {
105                        cal = new GregorianCalendar(myTimeZone);
106                } else {
107                        cal = new GregorianCalendar();
108                }
109                cal.setTime(theValue);
110
111                StringBuilder b = new StringBuilder();
112                leftPadWithZeros(cal.get(Calendar.YEAR), 4, b);
113                if (myPrecision.ordinal() > TemporalPrecisionEnum.YEAR.ordinal()) {
114                        b.append('-');
115                        leftPadWithZeros(cal.get(Calendar.MONTH) + 1, 2, b);
116                        if (myPrecision.ordinal() > TemporalPrecisionEnum.MONTH.ordinal()) {
117                                b.append('-');
118                                leftPadWithZeros(cal.get(Calendar.DATE), 2, b);
119                                if (myPrecision.ordinal() > TemporalPrecisionEnum.DAY.ordinal()) {
120                                        b.append('T');
121                                        leftPadWithZeros(cal.get(Calendar.HOUR_OF_DAY), 2, b);
122                                        b.append(':');
123                                        leftPadWithZeros(cal.get(Calendar.MINUTE), 2, b);
124                                        if (myPrecision.ordinal() > TemporalPrecisionEnum.MINUTE.ordinal()) {
125                                                b.append(':');
126                                                leftPadWithZeros(cal.get(Calendar.SECOND), 2, b);
127                                                if (myPrecision.ordinal() > TemporalPrecisionEnum.SECOND.ordinal()) {
128                                                        b.append('.');
129                                                        b.append(myFractionalSeconds);
130                                                        for (int i = myFractionalSeconds.length(); i < 3; i++) {
131                                                                b.append('0');
132                                                        }
133                                                }
134                                        }
135
136                                        if (myTimeZoneZulu) {
137                                                b.append('Z');
138                                        } else if (myTimeZone != null) {
139                                                int offset = myTimeZone.getOffset(theValue.getTime());
140                                                if (offset >= 0) {
141                                                        b.append('+');
142                                                } else {
143                                                        b.append('-');
144                                                        offset = Math.abs(offset);
145                                                }
146
147                                                int hoursOffset = (int) (offset / DateUtils.MILLIS_PER_HOUR);
148                                                leftPadWithZeros(hoursOffset, 2, b);
149                                                b.append(':');
150                                                int minutesOffset = (int) (offset % DateUtils.MILLIS_PER_HOUR);
151                                                minutesOffset = (int) (minutesOffset / DateUtils.MILLIS_PER_MINUTE);
152                                                leftPadWithZeros(minutesOffset, 2, b);
153                                        }
154                                }
155                        }
156                }
157                return b.toString();
158        }
159
160        /**
161         * Returns the month with 1-index, e.g. 1=the first day of the month
162         */
163        public Integer getDay() {
164                return getFieldValue(Calendar.DAY_OF_MONTH);
165        }
166
167        /**
168         * Returns the default precision for the given datatype
169         */
170        protected abstract TemporalPrecisionEnum getDefaultPrecisionForDatatype();
171
172        private Integer getFieldValue(int theField) {
173                if (getValue() == null) {
174                        return null;
175                }
176                Calendar cal = getValueAsCalendar();
177                return cal.get(theField);
178        }
179
180        /**
181         * Returns the hour of the day in a 24h clock, e.g. 13=1pm
182         */
183        public Integer getHour() {
184                return getFieldValue(Calendar.HOUR_OF_DAY);
185        }
186
187        /**
188         * Returns the milliseconds within the current second.
189         * <p>
190         * Note that this method returns the
191         * same value as {@link #getNanos()} but with less precision.
192         * </p>
193         */
194        public Integer getMillis() {
195                return getFieldValue(Calendar.MILLISECOND);
196        }
197
198        /**
199         * Returns the minute of the hour in the range 0-59
200         */
201        public Integer getMinute() {
202                return getFieldValue(Calendar.MINUTE);
203        }
204
205        /**
206         * Returns the month with 0-index, e.g. 0=January
207         */
208        public Integer getMonth() {
209                return getFieldValue(Calendar.MONTH);
210        }
211
212        /**
213         * Returns the nanoseconds within the current second
214         * <p>
215         * Note that this method returns the
216         * same value as {@link #getMillis()} but with more precision.
217         * </p>
218         */
219        public Long getNanos() {
220                if (isBlank(myFractionalSeconds)) {
221                        return null;
222                }
223                String retVal = StringUtils.rightPad(myFractionalSeconds, 9, '0');
224                retVal = retVal.substring(0, 9);
225                return Long.parseLong(retVal);
226        }
227
228        private int getOffsetIndex(String theValueString) {
229                int plusIndex = theValueString.indexOf('+', 16);
230                int minusIndex = theValueString.indexOf('-', 16);
231                int zIndex = theValueString.indexOf('Z', 16);
232                int retVal = Math.max(Math.max(plusIndex, minusIndex), zIndex);
233                if (retVal == -1) {
234                        return -1;
235                }
236                if ((retVal - 2) != (plusIndex + minusIndex + zIndex)) {
237                        throwBadDateFormat(theValueString);
238                }
239                return retVal;
240        }
241
242        /**
243         * Gets the precision for this datatype (using the default for the given type if not set)
244         * 
245         * @see #setPrecision(TemporalPrecisionEnum)
246         */
247        public TemporalPrecisionEnum getPrecision() {
248                if (myPrecision == null) {
249                        return getDefaultPrecisionForDatatype();
250                }
251                return myPrecision;
252        }
253
254        /**
255         * Returns the second of the minute in the range 0-59
256         */
257        public Integer getSecond() {
258                return getFieldValue(Calendar.SECOND);
259        }
260
261        /**
262         * Returns the TimeZone associated with this dateTime's value. May return <code>null</code> if no timezone was
263         * supplied.
264         */
265        public TimeZone getTimeZone() {
266                if (myTimeZoneZulu) {
267                        return TimeZone.getTimeZone("GMT");
268                }
269                return myTimeZone;
270        }
271
272        /**
273         * Returns the value of this object as a {@link GregorianCalendar}
274         */
275        public GregorianCalendar getValueAsCalendar() {
276                if (getValue() == null) {
277                        return null;
278                }
279                GregorianCalendar cal;
280                if (getTimeZone() != null) {
281                        cal = new GregorianCalendar(getTimeZone());
282                } else {
283                        cal = new GregorianCalendar();
284                }
285                cal.setTime(getValue());
286                return cal;
287        }
288
289        /**
290         * Returns the year, e.g. 2015
291         */
292        public Integer getYear() {
293                return getFieldValue(Calendar.YEAR);
294        }
295
296        /**
297         * To be implemented by subclasses to indicate whether the given precision is allowed by this type
298         */
299        protected abstract boolean isPrecisionAllowed(TemporalPrecisionEnum thePrecision);
300
301        /**
302         * Returns true if the timezone is set to GMT-0:00 (Z)
303         */
304        public boolean isTimeZoneZulu() {
305                return myTimeZoneZulu;
306        }
307
308        /**
309         * Returns <code>true</code> if this object represents a date that is today's date
310         * 
311         * @throws NullPointerException
312         *            if {@link #getValue()} returns <code>null</code>
313         */
314        public boolean isToday() {
315                Validate.notNull(getValue(), getClass().getSimpleName() + " contains null value");
316                return DateUtils.isSameDay(new Date(), getValue());
317        }
318
319        private void leftPadWithZeros(int theInteger, int theLength, StringBuilder theTarget) {
320                String string = Integer.toString(theInteger);
321                for (int i = string.length(); i < theLength; i++) {
322                        theTarget.append('0');
323                }
324                theTarget.append(string);
325        }
326
327        @Override
328        protected Date parse(String theValue) throws DataFormatException {
329                Calendar cal = new GregorianCalendar(0, 0, 0);
330                cal.setTimeZone(TimeZone.getDefault());
331                String value = theValue;
332                boolean fractionalSecondsSet = false;
333
334                if (value.length() > 0 && (value.charAt(0) == ' ' || value.charAt(value.length() - 1) == ' ')) {
335                        value = value.trim();
336                }
337
338                int length = value.length();
339                if (length == 0) {
340                        return null;
341                }
342
343                if (length < 4) {
344                        throwBadDateFormat(value);
345                }
346
347                TemporalPrecisionEnum precision = null;
348                cal.set(Calendar.YEAR, parseInt(value, value.substring(0, 4), 0, 9999));
349                precision = TemporalPrecisionEnum.YEAR;
350                if (length > 4) {
351                        validateCharAtIndexIs(value, 4, '-');
352                        validateLengthIsAtLeast(value, 7);
353                        int monthVal = parseInt(value, value.substring(5, 7), 1, 12) - 1;
354                        cal.set(Calendar.MONTH, monthVal);
355                        precision = TemporalPrecisionEnum.MONTH;
356                        if (length > 7) {
357                                validateCharAtIndexIs(value, 7, '-');
358                                validateLengthIsAtLeast(value, 10);
359                                cal.set(Calendar.DATE, 1); // for some reason getActualMaximum works incorrectly if date isn't set
360                                int actualMaximum = cal.getActualMaximum(Calendar.DAY_OF_MONTH);
361                                cal.set(Calendar.DAY_OF_MONTH, parseInt(value, value.substring(8, 10), 1, actualMaximum));
362                                precision = TemporalPrecisionEnum.DAY;
363                                if (length > 10) {
364                                        validateLengthIsAtLeast(value, 16);
365                                        validateCharAtIndexIs(value, 10, 'T'); // yyyy-mm-ddThh:mm:ss
366                                        int offsetIdx = getOffsetIndex(value);
367                                        String time;
368                                        if (offsetIdx == -1) {
369                                                //throwBadDateFormat(theValue);
370                                                // No offset - should this be an error?
371                                                time = value.substring(11);
372                                        } else {
373                                                time = value.substring(11, offsetIdx);
374                                                String offsetString = value.substring(offsetIdx);
375                                                setTimeZone(value, offsetString);
376                                                cal.setTimeZone(getTimeZone());
377                                        }
378                                        int timeLength = time.length();
379
380                                        validateCharAtIndexIs(value, 13, ':');
381                                        cal.set(Calendar.HOUR_OF_DAY, parseInt(value, value.substring(11, 13), 0, 23));
382                                        cal.set(Calendar.MINUTE, parseInt(value, value.substring(14, 16), 0, 59));
383                                        precision = TemporalPrecisionEnum.MINUTE;
384                                        if (timeLength > 5) {
385                                                validateLengthIsAtLeast(value, 19);
386                                                validateCharAtIndexIs(value, 16, ':'); // yyyy-mm-ddThh:mm:ss
387                                                cal.set(Calendar.SECOND, parseInt(value, value.substring(17, 19), 0, 59));
388                                                precision = TemporalPrecisionEnum.SECOND;
389                                                if (timeLength > 8) {
390                                                        validateCharAtIndexIs(value, 19, '.'); // yyyy-mm-ddThh:mm:ss.SSSS
391                                                        validateLengthIsAtLeast(value, 20);
392                                                        int endIndex = getOffsetIndex(value);
393                                                        if (endIndex == -1) {
394                                                                endIndex = value.length();
395                                                        }
396                                                        int millis;
397                                                        String millisString;
398                                                        if (endIndex > 23) {
399                                                                myFractionalSeconds = value.substring(20, endIndex);
400                                                                fractionalSecondsSet = true;
401                                                                endIndex = 23;
402                                                                millisString = value.substring(20, endIndex);
403                                                                millis = parseInt(value, millisString, 0, 999);
404                                                        } else {
405                                                                millisString = value.substring(20, endIndex);
406                                                                millis = parseInt(value, millisString, 0, 999);
407                                                                myFractionalSeconds = millisString;
408                                                                fractionalSecondsSet = true;
409                                                        }
410                                                        if (millisString.length() == 1) {
411                                                                millis = millis * 100;
412                                                        } else if (millisString.length() == 2) {
413                                                                millis = millis * 10;
414                                                        }
415                                                        cal.set(Calendar.MILLISECOND, millis);
416                                                        precision = TemporalPrecisionEnum.MILLI;
417                                                }
418                                        }
419                                }
420                        } else {
421                                cal.set(Calendar.DATE, 1);
422                        }
423                } else {
424                        cal.set(Calendar.DATE, 1);
425                }
426
427                if (fractionalSecondsSet == false) {
428                        myFractionalSeconds = "";
429                }
430
431                if (precision == TemporalPrecisionEnum.MINUTE) {
432                        validatePrecisionAndThrowDataFormatException(value, precision);
433                }
434                
435                setPrecision(precision);
436                return cal.getTime();
437
438        }
439
440        private int parseInt(String theValue, String theSubstring, int theLowerBound, int theUpperBound) {
441                int retVal = 0;
442                try {
443                        retVal = Integer.parseInt(theSubstring);
444                } catch (NumberFormatException e) {
445                        throwBadDateFormat(theValue);
446                }
447
448                if (retVal < theLowerBound || retVal > theUpperBound) {
449                        throwBadDateFormat(theValue);
450                }
451
452                return retVal;
453        }
454
455        /**
456         * Sets the month with 1-index, e.g. 1=the first day of the month
457         */
458        public BaseDateTimeDt setDay(int theDay) {
459                setFieldValue(Calendar.DAY_OF_MONTH, theDay, null, 0, 31);
460                return this;
461        }
462
463        private void setFieldValue(int theField, int theValue, String theFractionalSeconds, int theMinimum, int theMaximum) {
464                validateValueInRange(theValue, theMinimum, theMaximum);
465                Calendar cal;
466                if (getValue() == null) {
467                        cal = new GregorianCalendar(0, 0, 0);
468                } else {
469                        cal = getValueAsCalendar();
470                }
471                if (theField != -1) {
472                        cal.set(theField, theValue);
473                }
474                if (theFractionalSeconds != null) {
475                        myFractionalSeconds = theFractionalSeconds;
476                } else if (theField == Calendar.MILLISECOND) {
477                        myFractionalSeconds = StringUtils.leftPad(Integer.toString(theValue), 3, '0');
478                }
479                super.setValue(cal.getTime());
480        }
481
482        /**
483         * Sets the hour of the day in a 24h clock, e.g. 13=1pm
484         */
485        public BaseDateTimeDt setHour(int theHour) {
486                setFieldValue(Calendar.HOUR_OF_DAY, theHour, null, 0, 23);
487                return this;
488        }
489
490        /**
491         * Sets the milliseconds within the current second.
492         * <p>
493         * Note that this method sets the
494         * same value as {@link #setNanos(long)} but with less precision.
495         * </p>
496         */
497        public BaseDateTimeDt setMillis(int theMillis) {
498                setFieldValue(Calendar.MILLISECOND, theMillis, null, 0, 999);
499                return this;
500        }
501
502        /**
503         * Sets the minute of the hour in the range 0-59
504         */
505        public BaseDateTimeDt setMinute(int theMinute) {
506                setFieldValue(Calendar.MINUTE, theMinute, null, 0, 59);
507                return this;
508        }
509
510        /**
511         * Sets the month with 0-index, e.g. 0=January
512         */
513        public BaseDateTimeDt setMonth(int theMonth) {
514                setFieldValue(Calendar.MONTH, theMonth, null, 0, 11);
515                return this;
516        }
517
518        /**
519         * Sets the nanoseconds within the current second
520         * <p>
521         * Note that this method sets the
522         * same value as {@link #setMillis(int)} but with more precision.
523         * </p>
524         */
525        public BaseDateTimeDt setNanos(long theNanos) {
526                validateValueInRange(theNanos, 0, NANOS_PER_SECOND-1);
527                String fractionalSeconds = StringUtils.leftPad(Long.toString(theNanos), 9, '0');
528
529                // Strip trailing 0s
530                for (int i = fractionalSeconds.length(); i > 0; i--) {
531                        if (fractionalSeconds.charAt(i-1) != '0') {
532                                fractionalSeconds = fractionalSeconds.substring(0, i);
533                                break;
534                        }
535                }
536                int millis = (int)(theNanos / NANOS_PER_MILLIS);
537                setFieldValue(Calendar.MILLISECOND, millis, fractionalSeconds, 0, 999);
538                return this;
539        }
540
541        /**
542         * Sets the precision for this datatype
543         * 
544         * @throws DataFormatException
545         */
546        public BaseDateTimeDt setPrecision(TemporalPrecisionEnum thePrecision) throws DataFormatException {
547                if (thePrecision == null) {
548                        throw new NullPointerException("Precision may not be null");
549                }
550                myPrecision = thePrecision;
551                updateStringValue();
552                return this;
553        }
554
555        /**
556         * Sets the second of the minute in the range 0-59
557         */
558        public BaseDateTimeDt setSecond(int theSecond) {
559                setFieldValue(Calendar.SECOND, theSecond, null, 0, 59);
560                return this;
561        }
562
563        private BaseDateTimeDt setTimeZone(String theWholeValue, String theValue) {
564
565                if (isBlank(theValue)) {
566                        throwBadDateFormat(theWholeValue);
567                } else if (theValue.charAt(0) == 'Z') {
568                        clearTimeZone();
569                        setTimeZoneZulu(true);
570                } else if (theValue.length() != 6) {
571                        throwBadDateFormat(theWholeValue, "Timezone offset must be in the form \"Z\", \"-HH:mm\", or \"+HH:mm\"");
572                } else if (theValue.charAt(3) != ':' || !(theValue.charAt(0) == '+' || theValue.charAt(0) == '-')) {
573                        throwBadDateFormat(theWholeValue, "Timezone offset must be in the form \"Z\", \"-HH:mm\", or \"+HH:mm\"");
574                } else {
575                        parseInt(theWholeValue, theValue.substring(1, 3), 0, 23);
576                        parseInt(theWholeValue, theValue.substring(4, 6), 0, 59);
577                        clearTimeZone();
578                        setTimeZone(TimeZone.getTimeZone("GMT" + theValue));
579                }
580
581                return this;
582        }
583
584        public BaseDateTimeDt setTimeZone(TimeZone theTimeZone) {
585                myTimeZone = theTimeZone;
586                updateStringValue();
587                return this;
588        }
589
590        public BaseDateTimeDt setTimeZoneZulu(boolean theTimeZoneZulu) {
591                myTimeZoneZulu = theTimeZoneZulu;
592                updateStringValue();
593                return this;
594        }
595
596        /**
597         * Sets the value for this type using the given Java Date object as the time, and using the default precision for
598         * this datatype (unless the precision is already set), as well as the local timezone as determined by the local operating
599         * system. Both of these properties may be modified in subsequent calls if neccesary.
600         */
601        @Override
602        public BaseDateTimeDt setValue(Date theValue) {
603                setValue(theValue, getPrecision());
604                return this;
605        }
606
607        /**
608         * Sets the value for this type using the given Java Date object as the time, and using the specified precision, as
609         * well as the local timezone as determined by the local operating system. Both of
610         * these properties may be modified in subsequent calls if neccesary.
611         * 
612         * @param theValue
613         *           The date value
614         * @param thePrecision
615         *           The precision
616         * @throws DataFormatException
617         */
618        public void setValue(Date theValue, TemporalPrecisionEnum thePrecision) throws DataFormatException {
619                if (getTimeZone() == null) {
620                        setTimeZone(TimeZone.getDefault());
621                }
622                myPrecision = thePrecision;
623                myFractionalSeconds = "";
624                if (theValue != null) {
625                        long millis = theValue.getTime() % 1000;
626                        if (millis < 0) {
627                                // This is for times before 1970 (see bug #444)
628                                millis = 1000 + millis;
629                        }
630                        String fractionalSeconds = Integer.toString((int) millis);
631                        myFractionalSeconds = StringUtils.leftPad(fractionalSeconds, 3, '0');
632                }
633                super.setValue(theValue);
634        }
635
636        @Override
637        public void setValueAsString(String theValue) throws DataFormatException {
638                clearTimeZone();
639
640                if (NOW_DATE_CONSTANT.equalsIgnoreCase(theValue)) {
641                        super.setValueAsString(ourXmlDateTimeFormat.format(new Date()));
642                } else if (TODAY_DATE_CONSTANT.equalsIgnoreCase(theValue)) {
643                        super.setValueAsString(ourXmlDateTimeFormat.format(new Date()));
644                        setPrecision(TemporalPrecisionEnum.DAY);
645                } else {
646                        super.setValueAsString(theValue);
647                }
648        }
649
650        /**
651         * Sets the year, e.g. 2015
652         */
653        public BaseDateTimeDt setYear(int theYear) {
654                setFieldValue(Calendar.YEAR, theYear, null, 0, 9999);
655                return this;
656        }
657
658        private void throwBadDateFormat(String theValue) {
659                throw new DataFormatException("Invalid date/time format: \"" + theValue + "\"");
660        }
661
662        private void throwBadDateFormat(String theValue, String theMesssage) {
663                throw new DataFormatException("Invalid date/time format: \"" + theValue + "\": " + theMesssage);
664        }
665
666        /**
667         * Returns a human readable version of this date/time using the system local format.
668         * <p>
669         * <b>Note on time zones:</b> This method renders the value using the time zone that is contained within the value.
670         * For example, if this date object contains the value "2012-01-05T12:00:00-08:00",
671         * the human display will be rendered as "12:00:00" even if the application is being executed on a system in a
672         * different time zone. If this behaviour is not what you want, use
673         * {@link #toHumanDisplayLocalTimezone()} instead.
674         * </p>
675         */
676        public String toHumanDisplay() {
677                TimeZone tz = getTimeZone();
678                Calendar value = tz != null ? Calendar.getInstance(tz) : Calendar.getInstance();
679                value.setTime(getValue());
680
681                switch (getPrecision()) {
682                case YEAR:
683                case MONTH:
684                case DAY:
685                        return ourHumanDateFormat.format(value);
686                case MILLI:
687                case SECOND:
688                default:
689                        return ourHumanDateTimeFormat.format(value);
690                }
691        }
692
693        /**
694         * Returns a human readable version of this date/time using the system local format, converted to the local timezone
695         * if neccesary.
696         * 
697         * @see #toHumanDisplay() for a method which does not convert the time to the local timezone before rendering it.
698         */
699        public String toHumanDisplayLocalTimezone() {
700                switch (getPrecision()) {
701                case YEAR:
702                case MONTH:
703                case DAY:
704                        return ourHumanDateFormat.format(getValue());
705                case MILLI:
706                case SECOND:
707                default:
708                        return ourHumanDateTimeFormat.format(getValue());
709                }
710        }
711
712        private void validateCharAtIndexIs(String theValue, int theIndex, char theChar) {
713                if (theValue.charAt(theIndex) != theChar) {
714                        throwBadDateFormat(theValue, "Expected character '" + theChar + "' at index " + theIndex + " but found " + theValue.charAt(theIndex));
715                }
716        }
717
718        private void validateLengthIsAtLeast(String theValue, int theLength) {
719                if (theValue.length() < theLength) {
720                        throwBadDateFormat(theValue);
721                }
722        }
723
724        private void validateValueInRange(long theValue, long theMinimum, long theMaximum) {
725                if (theValue < theMinimum || theValue > theMaximum) {
726                        throw new IllegalArgumentException("Value " + theValue + " is not between allowable range: " + theMinimum + " - " + theMaximum);
727                }
728        }
729
730        private void validatePrecisionAndThrowDataFormatException(String theValue, TemporalPrecisionEnum thePrecision) {
731                if (isPrecisionAllowed(thePrecision) == false) {
732                        throw new DataFormatException("Invalid date/time string (datatype " + getClass().getSimpleName() + " does not support " + thePrecision + " precision): " + theValue);
733                }
734        }
735
736}