src/xmlpublic/org/apache/xmlbeans/GDateSpecification.java - xmlbeans - Git at Google

 /*   Copyright 2004 The Apache Software Foundation
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
  *   you may not use this file except in compliance with the License.
  *   You may obtain a copy of the License at
  *
  *       http://www.apache.org/licenses/LICENSE-2.0
  *
  *   Unless required by applicable law or agreed to in writing, software
  *   distributed under the License is distributed on an "AS IS" BASIS,
  *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *   See the License for the specific language governing permissions and
  *  limitations under the License.
  */

 package org.apache.xmlbeans;

 import java.math.BigDecimal;
 import java.util.Date;

 /**
  * Represents an XML Schema-compatible Gregorian date.
  * <p>
  * Both the immutable GDate and the mutable GDateBuilder are
  * GDateSpecifications.  Use this interface where you want to
  * allow callers to pass any implementation of a GDate.
  *
  * @see GDate
  * @see XmlCalendar
  */
 public interface GDateSpecification
 {
     /**
      * Returns a combination of flags indicating the information
      * contained by this GDate.  The five flags are
      * {@link #HAS_TIMEZONE}, {@link #HAS_YEAR}, {@link #HAS_MONTH},
      * {@link #HAS_DAY}, and {@link #HAS_TIME}.
      */
     int getFlags();

     /** Timezone is specified. See {@link #getFlags}. */
     public final int HAS_TIMEZONE = 1;
     /** Year is specified. See {@link #getFlags}. */
     public final int HAS_YEAR = 2;
     /** Month of year is specified. See {@link #getFlags}. */
     public final int HAS_MONTH = 4;
     /** Day of month is specified. See {@link #getFlags}. */
     public final int HAS_DAY = 8;
     /** Time of day is specified. See {@link #getFlags}. */
     public final int HAS_TIME = 16;

     /**
      * True if this GDate specification is immutable. GDate returns true,
      * and GDateBuilder returns false.
      */
     boolean isImmutable();

     /**
      * True if this GDate corresponds to a valid gregorian date value
      * in XML schema.
      */
     boolean isValid();

     /**
      * True if this date/time specification specifies a timezone.
      */
     boolean hasTimeZone();

     /**
      * True if this date/time specification specifies a year.
      */
     boolean hasYear();

     /**
      * True if this date/time specification specifies a month-of-year.
      */
     boolean hasMonth();

     /**
      * True if this date/time specification specifies a day-of-month.
      */
     boolean hasDay();

     /**
      * True if this date/time specification specifies a time-of-day.
      */
     boolean hasTime();

     /**
      * True if this date/time specification specifies a full date (year, month, day)
      */
     boolean hasDate();

     /**
      * Gets the year. Should be a four-digit year specification.
      */
     int getYear();

     /**
      * Gets the month-of-year. January is 1.
      */
     int getMonth();

     /**
      * Gets the day-of-month. The first day of each month is 1.
      */
     int getDay();

     /**
      * Gets the hour-of-day. Midnight is 0, and 11PM is 23.
      */
     int getHour();

     /**
      * Gets the minute-of-hour. Range from 0 to 59.
      */
     int getMinute();

     /**
      * Gets the second-of-minute. Range from 0 to 59.
      */
     int getSecond();

     /**
      * Gets the time zone sign. For time zones east of GMT,
      * this is positive; for time zones west, this is negative.
      */
     int getTimeZoneSign();

     /**
      * Gets the time zone hour.
      * This is always positive: for the sign, look at
      * getTimeZoneSign().
      */
     int getTimeZoneHour();

     /**
      * Gets the time zone minutes.
      * This is always positive: for the sign, look at
      * getTimeZoneSign().
      */
     int getTimeZoneMinute();

     /**
      * Gets the fraction-of-second. Range from 0 (inclusive) to 1 (exclusive).
      */
     BigDecimal getFraction();

     /**
      * Gets the rounded millisecond value. Range from 0 to 999
      */
     int getMillisecond();

     /**
      * Returns the Julian date corresponding to this Gregorian date.
      * The Julian date (JD) is a continuous count of days from
      * 1 January 4713 BC.
      */
     int getJulianDate();

     /**
      * Retrieves the value of the current time as an {@link XmlCalendar}.
      * <p>
      * {@link XmlCalendar} is a subclass of {@link java.util.GregorianCalendar}
      * which is slightly customized to match XML schema date rules.
      * <p>
      * The returned {@link XmlCalendar} has only those time and date fields
      * set that are reflected in the GDate object.  Because of the way the
      * {@link java.util.Calendar} contract works, any information in the isSet() vanishes
      * as soon as you view any unset field using get() methods.
      * This means that if it is important to understand which date fields
      * are set, you must call isSet() first before get().
      */
     XmlCalendar getCalendar();

     /**
      * Retrieves the value of the current time as a java.util.Date
      * instance.
      */
     Date getDate();

     /**
      * Comparison to another GDate.
      * <ul>
      * <li>Returns -1 if this < date. (less-than)
      * <li>Returns 0 if this == date. (equal)
      * <li>Returns 1 if this > date. (greater-than)
      * <li>Returns 2 if this <> date. (incomparable)
      * </ul>
      * Two instances are incomparable if they have different amounts
      * of information.
      *
      * @param gdatespec the date to compare against.
      */
     int compareToGDate(GDateSpecification gdatespec);

     /**
      * Returns the builtin type code for the shape of the information
      * contained in this instance, or 0 if the
      * instance doesn't contain information corresponding to a
      * Schema type.
      * <p>
      * Value will be equal to
      * {@link SchemaType#BTC_NOT_BUILTIN},
      * {@link SchemaType#BTC_G_YEAR},
      * {@link SchemaType#BTC_G_YEAR_MONTH},
      * {@link SchemaType#BTC_G_MONTH},
      * {@link SchemaType#BTC_G_MONTH_DAY},
      * {@link SchemaType#BTC_G_DAY},
      * {@link SchemaType#BTC_DATE},
      * {@link SchemaType#BTC_DATE_TIME}, or
      * {@link SchemaType#BTC_TIME}.
      */
     int getBuiltinTypeCode();

     /**
      * The canonical string representation. Specific moments or
      * times-of-day in a specified timezone are normalized to
      * UTC time to produce a canonical string form for them.
      * Other recurring time specifications keep their timezone
      * information.
      */
     String canonicalString();

     /**
      * The natural string representation. This represents the information
      * that is available, including timezone. For types that correspond
      * to defined schema types (schemaBuiltinTypeCode() > 0),
      * this provides the natural lexical representation.
      *
      * When both time and timezone are specified, this string is not
      * the canonical representation unless the timezone is UTC (Z)
      * (since the same moment in time can be expressed in different
      * timezones). To get a canonical string, use the canonicalString()
      * method.
      */
     String toString();

 }
	/* Copyright 2004 The Apache Software Foundation
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package org.apache.xmlbeans;

	import java.math.BigDecimal;
	import java.util.Date;

	/**
	* Represents an XML Schema-compatible Gregorian date.
	* <p>
	* Both the immutable GDate and the mutable GDateBuilder are
	* GDateSpecifications. Use this interface where you want to
	* allow callers to pass any implementation of a GDate.
	*
	* @see GDate
	* @see XmlCalendar
	*/
	public interface GDateSpecification
	{
	/**
	* Returns a combination of flags indicating the information
	* contained by this GDate. The five flags are
	* {@link #HAS_TIMEZONE}, {@link #HAS_YEAR}, {@link #HAS_MONTH},
	* {@link #HAS_DAY}, and {@link #HAS_TIME}.
	*/
	int getFlags();

	/** Timezone is specified. See {@link #getFlags}. */
	public final int HAS_TIMEZONE = 1;
	/** Year is specified. See {@link #getFlags}. */
	public final int HAS_YEAR = 2;
	/** Month of year is specified. See {@link #getFlags}. */
	public final int HAS_MONTH = 4;
	/** Day of month is specified. See {@link #getFlags}. */
	public final int HAS_DAY = 8;
	/** Time of day is specified. See {@link #getFlags}. */
	public final int HAS_TIME = 16;

	/**
	* True if this GDate specification is immutable. GDate returns true,
	* and GDateBuilder returns false.
	*/
	boolean isImmutable();

	/**
	* True if this GDate corresponds to a valid gregorian date value
	* in XML schema.
	*/
	boolean isValid();

	/**
	* True if this date/time specification specifies a timezone.
	*/
	boolean hasTimeZone();

	/**
	* True if this date/time specification specifies a year.
	*/
	boolean hasYear();

	/**
	* True if this date/time specification specifies a month-of-year.
	*/
	boolean hasMonth();

	/**
	* True if this date/time specification specifies a day-of-month.
	*/
	boolean hasDay();

	/**
	* True if this date/time specification specifies a time-of-day.
	*/
	boolean hasTime();

	/**
	* True if this date/time specification specifies a full date (year, month, day)
	*/
	boolean hasDate();

	/**
	* Gets the year. Should be a four-digit year specification.
	*/
	int getYear();

	/**
	* Gets the month-of-year. January is 1.
	*/
	int getMonth();

	/**
	* Gets the day-of-month. The first day of each month is 1.
	*/
	int getDay();

	/**
	* Gets the hour-of-day. Midnight is 0, and 11PM is 23.
	*/
	int getHour();

	/**
	* Gets the minute-of-hour. Range from 0 to 59.
	*/
	int getMinute();

	/**
	* Gets the second-of-minute. Range from 0 to 59.
	*/
	int getSecond();

	/**
	* Gets the time zone sign. For time zones east of GMT,
	* this is positive; for time zones west, this is negative.
	*/
	int getTimeZoneSign();

	/**
	* Gets the time zone hour.
	* This is always positive: for the sign, look at
	* getTimeZoneSign().
	*/
	int getTimeZoneHour();

	/**
	* Gets the time zone minutes.
	* This is always positive: for the sign, look at
	* getTimeZoneSign().
	*/
	int getTimeZoneMinute();

	/**
	* Gets the fraction-of-second. Range from 0 (inclusive) to 1 (exclusive).
	*/
	BigDecimal getFraction();

	/**
	* Gets the rounded millisecond value. Range from 0 to 999
	*/
	int getMillisecond();

	/**
	* Returns the Julian date corresponding to this Gregorian date.
	* The Julian date (JD) is a continuous count of days from
	* 1 January 4713 BC.
	*/
	int getJulianDate();

	/**
	* Retrieves the value of the current time as an {@link XmlCalendar}.
	* <p>
	* {@link XmlCalendar} is a subclass of {@link java.util.GregorianCalendar}
	* which is slightly customized to match XML schema date rules.
	* <p>
	* The returned {@link XmlCalendar} has only those time and date fields
	* set that are reflected in the GDate object. Because of the way the
	* {@link java.util.Calendar} contract works, any information in the isSet() vanishes
	* as soon as you view any unset field using get() methods.
	* This means that if it is important to understand which date fields
	* are set, you must call isSet() first before get().
	*/
	XmlCalendar getCalendar();

	/**
	* Retrieves the value of the current time as a java.util.Date
	* instance.
	*/
	Date getDate();

	/**
	* Comparison to another GDate.
	* <ul>
	* <li>Returns -1 if this < date. (less-than)
	* <li>Returns 0 if this == date. (equal)
	* <li>Returns 1 if this > date. (greater-than)
	* <li>Returns 2 if this <> date. (incomparable)
	* </ul>
	* Two instances are incomparable if they have different amounts
	* of information.
	*
	* @param gdatespec the date to compare against.
	*/
	int compareToGDate(GDateSpecification gdatespec);

	/**
	* Returns the builtin type code for the shape of the information
	* contained in this instance, or 0 if the
	* instance doesn't contain information corresponding to a
	* Schema type.
	* <p>
	* Value will be equal to
	* {@link SchemaType#BTC_NOT_BUILTIN},
	* {@link SchemaType#BTC_G_YEAR},
	* {@link SchemaType#BTC_G_YEAR_MONTH},
	* {@link SchemaType#BTC_G_MONTH},
	* {@link SchemaType#BTC_G_MONTH_DAY},
	* {@link SchemaType#BTC_G_DAY},
	* {@link SchemaType#BTC_DATE},
	* {@link SchemaType#BTC_DATE_TIME}, or
	* {@link SchemaType#BTC_TIME}.
	*/
	int getBuiltinTypeCode();

	/**
	* The canonical string representation. Specific moments or
	* times-of-day in a specified timezone are normalized to
	* UTC time to produce a canonical string form for them.
	* Other recurring time specifications keep their timezone
	* information.
	*/
	String canonicalString();

	/**
	* The natural string representation. This represents the information
	* that is available, including timezone. For types that correspond
	* to defined schema types (schemaBuiltinTypeCode() > 0),
	* this provides the natural lexical representation.
	*
	* When both time and timezone are specified, this string is not
	* the canonical representation unless the timezone is UTC (Z)
	* (since the same moment in time can be expressed in different
	* timezones). To get a canonical string, use the canonicalString()
	* method.
	*/
	String toString();

	}