1 /*
2 * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
495 public abstract int getYear();
496
497 /**
498 * Return XML Schema 1.0 dateTime datatype field for
499 * {@code year}.
500 *
501 * <p>Value constraints for this value are summarized in
502 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
503 *
504 * @return sum of {@code eon} and {@code BigInteger.valueOf(year)}
505 * when both fields are defined. When only {@code year} is defined,
506 * return it. When both {@code eon} and {@code year} are not
507 * defined, return {@code null}.
508 *
509 * @see #getEon()
510 * @see #getYear()
511 */
512 public abstract BigInteger getEonAndYear();
513
514 /**
515 * Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.
516 *
517 * <p>Value constraints for this value are summarized in
518 * <a href="#datetimefield-month">month field of date/time field mapping table</a>.
519 *
520 * @return year of this {@code XMLGregorianCalendar}.
521 *
522 */
523 public abstract int getMonth();
524
525 /**
526 * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.
527 *
528 * <p>Value constraints for this value are summarized in
529 * <a href="#datetimefield-day">day field of date/time field mapping table</a>.
530 *
531 * @see #setDay(int)
532 */
533 public abstract int getDay();
534
535 /**
536 * Return timezone offset in minutes or
537 * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
538 *
539 * <p>Value constraints for this value are summarized in
540 * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.
541 *
542 * @see #setTimezone(int)
543 */
544 public abstract int getTimezone();
545
546 /**
547 * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}.
548 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
549 *
550 * <p>Value constraints for this value are summarized in
551 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
552 * @see #setTime(int, int, int)
553 */
554 public abstract int getHour();
555
556 /**
557 * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
558 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
559 *
560 * <p>Value constraints for this value are summarized in
561 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
562 * @see #setTime(int, int, int)
563 */
564 public abstract int getMinute();
565
566 /**
567 * Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.
568 *
569 * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
570 * When this field is not defined, the optional xs:dateTime
571 * fractional seconds field, represented by
572 * {@link #getFractionalSecond()} and {@link #getMillisecond()},
573 * must not be defined.
574 *
575 * <p>Value constraints for this value are summarized in
576 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
577 *
578 * @return Second of this {@code XMLGregorianCalendar}.
579 *
580 * @see #getFractionalSecond()
581 * @see #getMillisecond()
664 * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).
665 *
666 * @return {@code this} {@code XMLGregorianCalendar} normalized to UTC.
667 */
668 public abstract XMLGregorianCalendar normalize();
669
670 /**
671 * Compares this calendar to the specified object. The result is
672 * {@code true} if and only if the argument is not null and is an
673 * {@code XMLGregorianCalendar} object that represents the same
674 * instant in time as this object.
675 *
676 * @param obj to compare.
677 *
678 * @return {@code true} when {@code obj} is an instance of
679 * {@code XMLGregorianCalendar} and
680 * {@link #compare(XMLGregorianCalendar obj)}
681 * returns {@link DatatypeConstants#EQUAL},
682 * otherwise {@code false}.
683 */
684 public boolean equals(Object obj) {
685
686 if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
687 return false;
688 }
689 return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
690 }
691
692 /**
693 * Returns a hash code consistent with the definition of the equals method.
694 *
695 * @return hash code of this object.
696 */
697 public int hashCode() {
698
699 // Following two dates compare to EQUALS since in different timezones.
700 // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
701 //
702 // Must ensure both instances generate same hashcode by normalizing
703 // this to UTC timezone.
704 int timezone = getTimezone();
705 if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
706 timezone = 0;
707 }
708 XMLGregorianCalendar gc = this;
709 if (timezone != 0) {
710 gc = this.normalize();
711 }
712 return gc.getYear()
713 + gc.getMonth()
714 + gc.getDay()
715 + gc.getHour()
716 + gc.getMinute()
838 * {@link DatatypeConstants#DATETIME},
839 * {@link DatatypeConstants#TIME},
840 * {@link DatatypeConstants#DATE},
841 * {@link DatatypeConstants#GYEARMONTH},
842 * {@link DatatypeConstants#GMONTHDAY},
843 * {@link DatatypeConstants#GYEAR},
844 * {@link DatatypeConstants#GMONTH} or
845 * {@link DatatypeConstants#GDAY}.
846 */
847 public abstract QName getXMLSchemaType();
848
849 /**
850 * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}.
851 *
852 * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.
853 *
854 * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}.
855 *
856 * @throws IllegalStateException if the combination of set fields
857 * does not match one of the eight defined XML Schema builtin date/time datatypes.
858 *
859 * @see #toXMLFormat()
860 */
861 public String toString() {
862
863 return toXMLFormat();
864 }
865
866 /**
867 * Validate instance by {@code getXMLSchemaType()} constraints.
868 * @return true if data values are valid.
869 */
870 public abstract boolean isValid();
871
872 /**
873 * Add {@code duration} to this instance.
874 *
875 * <p>The computation is specified in
876 * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E,
877 * <i>Adding durations to dateTimes</i></a>.
878 * <a href="#datetimefieldmapping">date/time field mapping table</a>
879 * defines the mapping from XML Schema 1.0 {@code dateTime} fields
880 * to this class' representation of those fields.
953 * </table>
954 * <i>*</i> designates possible loss of precision during the conversion due
955 * to source datatype having higher precision than target datatype.
956 *
957 * <p>To ensure consistency in conversion implementations, the new
958 * {@code GregorianCalendar} should be instantiated in following
959 * manner.
960 * <ul>
961 * <li>Using {@code timeZone} value as defined above, create a new
962 * {@code java.util.GregorianCalendar(timeZone,Locale.getDefault())}.
963 * </li>
964 * <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li>
965 * <li>Obtain a pure Gregorian Calendar by invoking
966 * {@code GregorianCalendar.setGregorianChange(
967 * new Date(Long.MIN_VALUE))}.</li>
968 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
969 * MINUTE, SECOND and MILLISECOND are set using the method
970 * {@code Calendar.set(int,int)}</li>
971 * </ul>
972 *
973 * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
974 */
975 public abstract GregorianCalendar toGregorianCalendar();
976
977 /**
978 * Convert this {@code XMLGregorianCalendar} along with provided parameters
979 * to a {@link GregorianCalendar} instance.
980 *
981 * <p> Since XML Schema 1.0 date/time datetypes has no concept of
982 * timezone ids or daylight savings timezone ids, this conversion operation
983 * allows the user to explicitly specify one with
984 * {@code timezone} parameter.
985 *
986 * <p>To compute the return value's {@code TimeZone} field,
987 * <ul>
988 * <li>when parameter {@code timeZone} is non-null,
989 * it is the timezone field.</li>
990 * <li>else when {@code this.getTimezone() != FIELD_UNDEFINED},
991 * create a {@code java.util.TimeZone} with a custom timezone id
992 * using the {@code this.getTimezone()}.</li>
1032
1033 /**
1034 * Returns a {@code java.util.TimeZone} for this class.
1035 *
1036 * <p>If timezone field is defined for this instance,
1037 * returns TimeZone initialized with custom timezone id
1038 * of zoneoffset. If timezone field is undefined,
1039 * try the defaultZoneoffset that was passed in.
1040 * If defaultZoneoffset is FIELD_UNDEFINED, return
1041 * default timezone for this host.
1042 * (Same default as java.util.GregorianCalendar).
1043 *
1044 * @param defaultZoneoffset default zoneoffset if this zoneoffset is
1045 * {@link DatatypeConstants#FIELD_UNDEFINED}.
1046 *
1047 * @return TimeZone for this.
1048 */
1049 public abstract TimeZone getTimeZone(int defaultZoneoffset);
1050
1051
1052
1053 /**
1054 * Creates and returns a copy of this object.
1055 *
1056 * @return copy of this {@code Object}
1057 */
1058 public abstract Object clone();
1059 }
|
1 /*
2 * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
495 public abstract int getYear();
496
497 /**
498 * Return XML Schema 1.0 dateTime datatype field for
499 * {@code year}.
500 *
501 * <p>Value constraints for this value are summarized in
502 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
503 *
504 * @return sum of {@code eon} and {@code BigInteger.valueOf(year)}
505 * when both fields are defined. When only {@code year} is defined,
506 * return it. When both {@code eon} and {@code year} are not
507 * defined, return {@code null}.
508 *
509 * @see #getEon()
510 * @see #getYear()
511 */
512 public abstract BigInteger getEonAndYear();
513
514 /**
515 * Returns the month of this calendar or {@link DatatypeConstants#FIELD_UNDEFINED}.
516 *
517 * <p>Value constraints for this value are summarized in
518 * <a href="#datetimefield-month">month field of date/time field mapping table</a>.
519 *
520 * @return Returns the month of this {@code XMLGregorianCalendar}.
521 *
522 */
523 public abstract int getMonth();
524
525 /**
526 * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.
527 *
528 * <p>Value constraints for this value are summarized in
529 * <a href="#datetimefield-day">day field of date/time field mapping table</a>.
530 *
531 * @return Day in month of this {@code XMLGregorianCalendar}.
532 *
533 * @see #setDay(int)
534 */
535 public abstract int getDay();
536
537 /**
538 * Return timezone offset in minutes or
539 * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
540 *
541 * <p>Value constraints for this value are summarized in
542 * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.
543 *
544 * @return Timezone offset in minutes of this {@code XMLGregorianCalendar}.
545 *
546 * @see #setTimezone(int)
547 */
548 public abstract int getTimezone();
549
550 /**
551 * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}.
552 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
553 *
554 * <p>Value constraints for this value are summarized in
555 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
556 *
557 * @return Hours of this {@code XMLGregorianCalendar}.
558 *
559 * @see #setTime(int, int, int)
560 */
561 public abstract int getHour();
562
563 /**
564 * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
565 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
566 *
567 * <p>Value constraints for this value are summarized in
568 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
569 *
570 * @return Minutes of this {@code XMLGregorianCalendar}.
571 *
572 * @see #setTime(int, int, int)
573 */
574 public abstract int getMinute();
575
576 /**
577 * Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.
578 *
579 * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
580 * When this field is not defined, the optional xs:dateTime
581 * fractional seconds field, represented by
582 * {@link #getFractionalSecond()} and {@link #getMillisecond()},
583 * must not be defined.
584 *
585 * <p>Value constraints for this value are summarized in
586 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
587 *
588 * @return Second of this {@code XMLGregorianCalendar}.
589 *
590 * @see #getFractionalSecond()
591 * @see #getMillisecond()
674 * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).
675 *
676 * @return {@code this} {@code XMLGregorianCalendar} normalized to UTC.
677 */
678 public abstract XMLGregorianCalendar normalize();
679
680 /**
681 * Compares this calendar to the specified object. The result is
682 * {@code true} if and only if the argument is not null and is an
683 * {@code XMLGregorianCalendar} object that represents the same
684 * instant in time as this object.
685 *
686 * @param obj to compare.
687 *
688 * @return {@code true} when {@code obj} is an instance of
689 * {@code XMLGregorianCalendar} and
690 * {@link #compare(XMLGregorianCalendar obj)}
691 * returns {@link DatatypeConstants#EQUAL},
692 * otherwise {@code false}.
693 */
694 @Override
695 public boolean equals(Object obj) {
696
697 if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
698 return false;
699 }
700 return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
701 }
702
703 /**
704 * Returns a hash code consistent with the definition of the equals method.
705 *
706 * @return hash code of this object.
707 */
708 @Override
709 public int hashCode() {
710
711 // Following two dates compare to EQUALS since in different timezones.
712 // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
713 //
714 // Must ensure both instances generate same hashcode by normalizing
715 // this to UTC timezone.
716 int timezone = getTimezone();
717 if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
718 timezone = 0;
719 }
720 XMLGregorianCalendar gc = this;
721 if (timezone != 0) {
722 gc = this.normalize();
723 }
724 return gc.getYear()
725 + gc.getMonth()
726 + gc.getDay()
727 + gc.getHour()
728 + gc.getMinute()
850 * {@link DatatypeConstants#DATETIME},
851 * {@link DatatypeConstants#TIME},
852 * {@link DatatypeConstants#DATE},
853 * {@link DatatypeConstants#GYEARMONTH},
854 * {@link DatatypeConstants#GMONTHDAY},
855 * {@link DatatypeConstants#GYEAR},
856 * {@link DatatypeConstants#GMONTH} or
857 * {@link DatatypeConstants#GDAY}.
858 */
859 public abstract QName getXMLSchemaType();
860
861 /**
862 * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}.
863 *
864 * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.
865 *
866 * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}.
867 *
868 * @throws IllegalStateException if the combination of set fields
869 * does not match one of the eight defined XML Schema builtin date/time datatypes.
870 * @see #toXMLFormat()
871 */
872 @Override
873 public String toString() {
874
875 return toXMLFormat();
876 }
877
878 /**
879 * Validate instance by {@code getXMLSchemaType()} constraints.
880 * @return true if data values are valid.
881 */
882 public abstract boolean isValid();
883
884 /**
885 * Add {@code duration} to this instance.
886 *
887 * <p>The computation is specified in
888 * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E,
889 * <i>Adding durations to dateTimes</i></a>.
890 * <a href="#datetimefieldmapping">date/time field mapping table</a>
891 * defines the mapping from XML Schema 1.0 {@code dateTime} fields
892 * to this class' representation of those fields.
965 * </table>
966 * <i>*</i> designates possible loss of precision during the conversion due
967 * to source datatype having higher precision than target datatype.
968 *
969 * <p>To ensure consistency in conversion implementations, the new
970 * {@code GregorianCalendar} should be instantiated in following
971 * manner.
972 * <ul>
973 * <li>Using {@code timeZone} value as defined above, create a new
974 * {@code java.util.GregorianCalendar(timeZone,Locale.getDefault())}.
975 * </li>
976 * <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li>
977 * <li>Obtain a pure Gregorian Calendar by invoking
978 * {@code GregorianCalendar.setGregorianChange(
979 * new Date(Long.MIN_VALUE))}.</li>
980 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
981 * MINUTE, SECOND and MILLISECOND are set using the method
982 * {@code Calendar.set(int,int)}</li>
983 * </ul>
984 *
985 * @return a {@code java.util.GregorianCalendar} conversion of this instance.
986 *
987 * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
988 */
989 public abstract GregorianCalendar toGregorianCalendar();
990
991 /**
992 * Convert this {@code XMLGregorianCalendar} along with provided parameters
993 * to a {@link GregorianCalendar} instance.
994 *
995 * <p> Since XML Schema 1.0 date/time datetypes has no concept of
996 * timezone ids or daylight savings timezone ids, this conversion operation
997 * allows the user to explicitly specify one with
998 * {@code timezone} parameter.
999 *
1000 * <p>To compute the return value's {@code TimeZone} field,
1001 * <ul>
1002 * <li>when parameter {@code timeZone} is non-null,
1003 * it is the timezone field.</li>
1004 * <li>else when {@code this.getTimezone() != FIELD_UNDEFINED},
1005 * create a {@code java.util.TimeZone} with a custom timezone id
1006 * using the {@code this.getTimezone()}.</li>
1046
1047 /**
1048 * Returns a {@code java.util.TimeZone} for this class.
1049 *
1050 * <p>If timezone field is defined for this instance,
1051 * returns TimeZone initialized with custom timezone id
1052 * of zoneoffset. If timezone field is undefined,
1053 * try the defaultZoneoffset that was passed in.
1054 * If defaultZoneoffset is FIELD_UNDEFINED, return
1055 * default timezone for this host.
1056 * (Same default as java.util.GregorianCalendar).
1057 *
1058 * @param defaultZoneoffset default zoneoffset if this zoneoffset is
1059 * {@link DatatypeConstants#FIELD_UNDEFINED}.
1060 *
1061 * @return TimeZone for this.
1062 */
1063 public abstract TimeZone getTimeZone(int defaultZoneoffset);
1064
1065
1066 /**
1067 * Creates and returns a copy of this object.
1068 *
1069 * @return copy of this {@code Object}
1070 */
1071 @Override
1072 public abstract Object clone();
1073 }
|