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
449 * @param minute value constraints are summarized in
450 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
451 * @param second value constraints are summarized in
452 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
453 * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this
454 * optional field is not set.
455 *
456 * @throws IllegalArgumentException if any parameter is
457 * outside value constraints for the field as specified in
458 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
459 */
460 public void setTime(int hour, int minute, int second, int millisecond) {
461
462 setHour(hour);
463 setMinute(minute);
464 setSecond(second);
465 setMillisecond(millisecond);
466 }
467
468 /**
469 * Return high order component for XML Schema 1.0 dateTime datatype field for
470 * {@code year}.
471 * {@code null} if this optional part of the year field is not defined.
472 *
473 * <p>Value constraints for this value are summarized in
474 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
475 * @return eon of this {@code XMLGregorianCalendar}. The value
476 * returned is an integer multiple of 10^9.
477 *
478 * @see #getYear()
479 * @see #getEonAndYear()
480 */
481 public abstract BigInteger getEon();
482
483 /**
484 * Return low order component for XML Schema 1.0 dateTime datatype field for
485 * {@code year} or {@link DatatypeConstants#FIELD_UNDEFINED}.
486 *
487 * <p>Value constraints for this value are summarized in
488 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
489 *
490 * @return year of this {@code XMLGregorianCalendar}.
491 *
492 * @see #getEon()
493 * @see #getEonAndYear()
494 */
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()
582 * @see #setTime(int, int, int)
583 */
584 public abstract int getSecond();
585
586 /**
587 * Return millisecond precision of {@link #getFractionalSecond()}.
588 *
589 * <p>This method represents a convenience accessor to infinite
590 * precision fractional second value returned by
591 * {@link #getFractionalSecond()}. The returned value is the rounded
592 * down to milliseconds value of
593 * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
594 * returns {@code null}, this method must return
595 * {@link DatatypeConstants#FIELD_UNDEFINED}.
596 *
597 * <p>Value constraints for this value are summarized in
598 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
599 *
600 * @return Millisecond of this {@code XMLGregorianCalendar}.
601 *
602 * @see #getFractionalSecond()
603 * @see #setTime(int, int, int)
604 */
605 public int getMillisecond() {
606
607 BigDecimal fractionalSeconds = getFractionalSecond();
608
609 // is field undefined?
610 if (fractionalSeconds == null) {
611 return DatatypeConstants.FIELD_UNDEFINED;
612 }
613
614 return getFractionalSecond().movePointRight(3).intValue();
615 }
616
617 /**
618 * Return fractional seconds.
619 *
620 * <p>{@code null} is returned when this optional field is not defined.
621 *
622 * <p>Value constraints are detailed in
623 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
624 *
625 * <p>This optional field can only have a defined value when the
626 * xs:dateTime second field, represented by {@link #getSecond()},
627 * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.
628 *
629 * @return fractional seconds of this {@code XMLGregorianCalendar}.
630 *
631 * @see #getSecond()
632 * @see #setTime(int, int, int, BigDecimal)
633 */
634 public abstract BigDecimal getFractionalSecond();
635
636 // comparisons
637 /**
638 * Compare two instances of W3C XML Schema 1.0 date/time datatypes
639 * according to partial order relation defined in
640 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
641 * <i>Order relation on dateTime</i></a>.
642 *
643 * <p>{@code xsd:dateTime} datatype field mapping to accessors of
644 * this class are defined in
645 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
646 *
647 * @param xmlGregorianCalendar Instance of {@code XMLGregorianCalendar} to compare
648 *
649 * @return The relationship between {@code this} {@code XMLGregorianCalendar} and
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()
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>
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
449 * @param minute value constraints are summarized in
450 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
451 * @param second value constraints are summarized in
452 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
453 * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this
454 * optional field is not set.
455 *
456 * @throws IllegalArgumentException if any parameter is
457 * outside value constraints for the field as specified in
458 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
459 */
460 public void setTime(int hour, int minute, int second, int millisecond) {
461
462 setHour(hour);
463 setMinute(minute);
464 setSecond(second);
465 setMillisecond(millisecond);
466 }
467
468 /**
469 * Returns the high order component for XML Schema 1.0 dateTime datatype field for
470 * {@code year}.
471 * {@code null} if this optional part of the year field is not defined.
472 *
473 * <p>Value constraints for this value are summarized in
474 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
475 * @return The eon of this {@code XMLGregorianCalendar}. The value
476 * returned is an integer multiple of 10^9.
477 *
478 * @see #getYear()
479 * @see #getEonAndYear()
480 */
481 public abstract BigInteger getEon();
482
483 /**
484 * Returns the low order component for XML Schema 1.0 dateTime datatype field for
485 * {@code year} or {@link DatatypeConstants#FIELD_UNDEFINED}.
486 *
487 * <p>Value constraints for this value are summarized in
488 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.
489 *
490 * @return The year of this {@code XMLGregorianCalendar}.
491 *
492 * @see #getEon()
493 * @see #getEonAndYear()
494 */
495 public abstract int getYear();
496
497 /**
498 * Returns the 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 The month of this {@code XMLGregorianCalendar}, from 1 to 12.
521 *
522 */
523 public abstract int getMonth();
524
525 /**
526 * Returns the day of 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 The day of month of this {@code XMLGregorianCalendar}, from 1 to 31.
532 *
533 * @see #setDay(int)
534 */
535 public abstract int getDay();
536
537 /**
538 * Returns the 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 The Timezone offset in minutes of this {@code XMLGregorianCalendar}.
545 *
546 * @see #setTimezone(int)
547 */
548 public abstract int getTimezone();
549
550 /**
551 * Returns the hour of day or
552 * {@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 The hour of day of this {@code XMLGregorianCalendar}, from 0 to 23.
558 *
559 * @see #setTime(int, int, int)
560 */
561 public abstract int getHour();
562
563 /**
564 * Returns the minute of hour or
565 * {@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 The minute of hour of this {@code XMLGregorianCalendar}, from 0 to 59.
571 *
572 * @see #setTime(int, int, int)
573 */
574 public abstract int getMinute();
575
576 /**
577 * Returns the second of minute or
578 * {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
579 * When this field is not defined, the optional xs:dateTime
580 * fractional seconds field, represented by
581 * {@link #getFractionalSecond()} and {@link #getMillisecond()},
582 * must not be defined.
583 *
584 * <p>Value constraints for this value are summarized in
585 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
586 *
587 * @return The second of minute of this {@code XMLGregorianCalendar}, from 0 to 59.
588 *
589 * @see #getFractionalSecond()
590 * @see #getMillisecond()
591 * @see #setTime(int, int, int)
592 */
593 public abstract int getSecond();
594
595 /**
596 * Returns the millisecond precision of {@link #getFractionalSecond()}.
597 *
598 * <p>This method represents a convenience accessor to infinite
599 * precision fractional second value returned by
600 * {@link #getFractionalSecond()}. The returned value is the rounded
601 * down to milliseconds value of
602 * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
603 * returns {@code null}, this method must return
604 * {@link DatatypeConstants#FIELD_UNDEFINED}.
605 *
606 * <p>Value constraints for this value are summarized in
607 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
608 *
609 * @return The millisecond precision of this {@code XMLGregorianCalendar}.
610 *
611 * @see #getFractionalSecond()
612 * @see #setTime(int, int, int)
613 */
614 public int getMillisecond() {
615
616 BigDecimal fractionalSeconds = getFractionalSecond();
617
618 // is field undefined?
619 if (fractionalSeconds == null) {
620 return DatatypeConstants.FIELD_UNDEFINED;
621 }
622
623 return getFractionalSecond().movePointRight(3).intValue();
624 }
625
626 /**
627 * Returns fractional seconds.
628 *
629 * <p>{@code null} is returned when this optional field is not defined.
630 *
631 * <p>Value constraints are detailed in
632 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
633 *
634 * <p>This optional field can only have a defined value when the
635 * xs:dateTime second field, represented by {@link #getSecond()},
636 * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.
637 *
638 * @return Fractional seconds of this {@code XMLGregorianCalendar}.
639 *
640 * @see #getSecond()
641 * @see #setTime(int, int, int, BigDecimal)
642 */
643 public abstract BigDecimal getFractionalSecond();
644
645 // comparisons
646 /**
647 * Compare two instances of W3C XML Schema 1.0 date/time datatypes
648 * according to partial order relation defined in
649 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
650 * <i>Order relation on dateTime</i></a>.
651 *
652 * <p>{@code xsd:dateTime} datatype field mapping to accessors of
653 * this class are defined in
654 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
655 *
656 * @param xmlGregorianCalendar Instance of {@code XMLGregorianCalendar} to compare
657 *
658 * @return The relationship between {@code this} {@code XMLGregorianCalendar} and
673 * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).
674 *
675 * @return {@code this} {@code XMLGregorianCalendar} normalized to UTC.
676 */
677 public abstract XMLGregorianCalendar normalize();
678
679 /**
680 * Compares this calendar to the specified object. The result is
681 * {@code true} if and only if the argument is not null and is an
682 * {@code XMLGregorianCalendar} object that represents the same
683 * instant in time as this object.
684 *
685 * @param obj to compare.
686 *
687 * @return {@code true} when {@code obj} is an instance of
688 * {@code XMLGregorianCalendar} and
689 * {@link #compare(XMLGregorianCalendar obj)}
690 * returns {@link DatatypeConstants#EQUAL},
691 * otherwise {@code false}.
692 */
693 @Override
694 public boolean equals(Object obj) {
695
696 if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
697 return false;
698 }
699 return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
700 }
701
702 /**
703 * Returns a hash code consistent with the definition of the equals method.
704 *
705 * @return hash code of this object.
706 */
707 @Override
708 public int hashCode() {
709
710 // Following two dates compare to EQUALS since in different timezones.
711 // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
712 //
713 // Must ensure both instances generate same hashcode by normalizing
714 // this to UTC timezone.
715 int timezone = getTimezone();
716 if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
717 timezone = 0;
718 }
719 XMLGregorianCalendar gc = this;
720 if (timezone != 0) {
721 gc = this.normalize();
722 }
723 return gc.getYear()
724 + gc.getMonth()
725 + gc.getDay()
726 + gc.getHour()
727 + gc.getMinute()
852 * {@link DatatypeConstants#GYEARMONTH},
853 * {@link DatatypeConstants#GMONTHDAY},
854 * {@link DatatypeConstants#GYEAR},
855 * {@link DatatypeConstants#GMONTH} or
856 * {@link DatatypeConstants#GDAY}.
857 */
858 public abstract QName getXMLSchemaType();
859
860 /**
861 * Returns a {@code String} representation of this {@code XMLGregorianCalendar} {@code Object}.
862 *
863 * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.
864 *
865 * @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}.
866 *
867 * @throws IllegalStateException if the combination of set fields
868 * does not match one of the eight defined XML Schema builtin date/time datatypes.
869 *
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 An instance of {@link java.util.GregorianCalendar}.
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>
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 /**
1068 * Creates and returns a copy of this object.
1069 *
1070 * @return copy of this {@code Object}
1071 */
1072 @Override
1073 public abstract Object clone();
1074 }
1075
|