Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]

    1   /*   Copyright 2004 The Apache Software Foundation
    2    *
    3    *   Licensed under the Apache License, Version 2.0 (the "License");
    4    *   you may not use this file except in compliance with the License.
    5    *   You may obtain a copy of the License at
    6    *
    7    *       http://www.apache.org/licenses/LICENSE-2.0
    8    *
    9    *   Unless required by applicable law or agreed to in writing, software
   10    *   distributed under the License is distributed on an "AS IS" BASIS,
   11    *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12    *   See the License for the specific language governing permissions and
   13    *  limitations under the License.
   14    */
   15   
   16   package org.apache.xmlbeans;
   17   
   18   import java.math.BigDecimal;
   19   import java.util.Date;
   20   
   21   /**
   22    * Represents an XML Schema-compatible Gregorian date.
   23    * <p>
   24    * Both the immutable GDate and the mutable GDateBuilder are
   25    * GDateSpecifications.  Use this interface where you want to
   26    * allow callers to pass any implementation of a GDate.
   27    * 
   28    * @see GDate
   29    * @see XmlCalendar
   30    */
   31   public interface GDateSpecification
   32   {
   33       /**
   34        * Returns a combination of flags indicating the information
   35        * contained by this GDate.  The five flags are
   36        * {@link #HAS_TIMEZONE}, {@link #HAS_YEAR}, {@link #HAS_MONTH},
   37        * {@link #HAS_DAY}, and {@link #HAS_TIME}.
   38        */
   39       int getFlags();
   40   
   41       /** Timezone is specified. See {@link #getFlags}. */
   42       public final int HAS_TIMEZONE = 1;
   43       /** Year is specified. See {@link #getFlags}. */
   44       public final int HAS_YEAR = 2;
   45       /** Month of year is specified. See {@link #getFlags}. */
   46       public final int HAS_MONTH = 4;
   47       /** Day of month is specified. See {@link #getFlags}. */
   48       public final int HAS_DAY = 8;
   49       /** Time of day is specified. See {@link #getFlags}. */
   50       public final int HAS_TIME = 16;
   51   
   52       /**
   53        * True if this GDate specification is immutable. GDate returns true,
   54        * and GDateBuilder returns false.
   55        */
   56       boolean isImmutable();
   57   
   58       /**
   59        * True if this GDate corresponds to a valid gregorian date value
   60        * in XML schema.
   61        */
   62       boolean isValid();
   63   
   64       /**
   65        * True if this date/time specification specifies a timezone.
   66        */
   67       boolean hasTimeZone();
   68   
   69       /**
   70        * True if this date/time specification specifies a year.
   71        */
   72       boolean hasYear();
   73   
   74       /**
   75        * True if this date/time specification specifies a month-of-year.
   76        */
   77       boolean hasMonth();
   78   
   79       /**
   80        * True if this date/time specification specifies a day-of-month.
   81        */
   82       boolean hasDay();
   83   
   84       /**
   85        * True if this date/time specification specifies a time-of-day.
   86        */
   87       boolean hasTime();
   88   
   89       /**
   90        * True if this date/time specification specifies a full date (year, month, day)
   91        */
   92       boolean hasDate();
   93   
   94       /**
   95        * Gets the year. Should be a four-digit year specification.
   96        */
   97       int getYear();
   98   
   99       /**
  100        * Gets the month-of-year. January is 1.
  101        */
  102       int getMonth();
  103   
  104       /**
  105        * Gets the day-of-month. The first day of each month is 1.
  106        */
  107       int getDay();
  108   
  109       /**
  110        * Gets the hour-of-day. Midnight is 0, and 11PM is 23.
  111        */
  112       int getHour();
  113   
  114       /**
  115        * Gets the minute-of-hour. Range from 0 to 59.
  116        */
  117       int getMinute();
  118   
  119       /**
  120        * Gets the second-of-minute. Range from 0 to 59.
  121        */
  122       int getSecond();
  123   
  124       /**
  125        * Gets the time zone sign. For time zones east of GMT,
  126        * this is positive; for time zones west, this is negative.
  127        */
  128       int getTimeZoneSign();
  129   
  130       /**
  131        * Gets the time zone hour.
  132        * This is always positive: for the sign, look at
  133        * getTimeZoneSign().
  134        */
  135       int getTimeZoneHour();
  136   
  137       /**
  138        * Gets the time zone minutes.
  139        * This is always positive: for the sign, look at
  140        * getTimeZoneSign().
  141        */
  142       int getTimeZoneMinute();
  143   
  144       /**
  145        * Gets the fraction-of-second. Range from 0 (inclusive) to 1 (exclusive).
  146        */
  147       BigDecimal getFraction();
  148   
  149       /**
  150        * Gets the rounded millisecond value. Range from 0 to 999
  151        */
  152       int getMillisecond();
  153   
  154       /**
  155        * Returns the Julian date corresponding to this Gregorian date.
  156        * The Julian date (JD) is a continuous count of days from
  157        * 1 January 4713 BC.
  158        */
  159       int getJulianDate();
  160   
  161       /**
  162        * Retrieves the value of the current time as an {@link XmlCalendar}.
  163        * <p>
  164        * {@link XmlCalendar} is a subclass of {@link java.util.GregorianCalendar}
  165        * which is slightly customized to match XML schema date rules.
  166        * <p>
  167        * The returned {@link XmlCalendar} has only those time and date fields
  168        * set that are reflected in the GDate object.  Because of the way the
  169        * {@link java.util.Calendar} contract works, any information in the isSet() vanishes
  170        * as soon as you view any unset field using get() methods.
  171        * This means that if it is important to understand which date fields
  172        * are set, you must call isSet() first before get().
  173        */
  174       XmlCalendar getCalendar();
  175   
  176       /**
  177        * Retrieves the value of the current time as a java.util.Date
  178        * instance.
  179        */
  180       Date getDate();
  181   
  182       /**
  183        * Comparison to another GDate.
  184        * <ul>
  185        * <li>Returns -1 if this < date. (less-than)
  186        * <li>Returns 0 if this == date. (equal)
  187        * <li>Returns 1 if this > date. (greater-than)
  188        * <li>Returns 2 if this <> date. (incomparable)
  189        * </ul>
  190        * Two instances are incomparable if they have different amounts
  191        * of information.
  192        * 
  193        * @param gdatespec the date to compare against.
  194        */
  195       int compareToGDate(GDateSpecification gdatespec);
  196   
  197       /**
  198        * Returns the builtin type code for the shape of the information
  199        * contained in this instance, or 0 if the
  200        * instance doesn't contain information corresponding to a
  201        * Schema type.
  202        * <p> 
  203        * Value will be equal to
  204        * {@link SchemaType#BTC_NOT_BUILTIN},
  205        * {@link SchemaType#BTC_G_YEAR},
  206        * {@link SchemaType#BTC_G_YEAR_MONTH},
  207        * {@link SchemaType#BTC_G_MONTH},
  208        * {@link SchemaType#BTC_G_MONTH_DAY},
  209        * {@link SchemaType#BTC_G_DAY},
  210        * {@link SchemaType#BTC_DATE},
  211        * {@link SchemaType#BTC_DATE_TIME}, or
  212        * {@link SchemaType#BTC_TIME}.
  213        */
  214       int getBuiltinTypeCode();
  215   
  216       /**
  217        * The canonical string representation. Specific moments or
  218        * times-of-day in a specified timezone are normalized to
  219        * UTC time to produce a canonical string form for them.
  220        * Other recurring time specifications keep their timezone
  221        * information.
  222        */
  223       String canonicalString();
  224   
  225       /**
  226        * The natural string representation. This represents the information
  227        * that is available, including timezone. For types that correspond
  228        * to defined schema types (schemaBuiltinTypeCode() > 0),
  229        * this provides the natural lexical representation.
  230        *
  231        * When both time and timezone are specified, this string is not
  232        * the canonical representation unless the timezone is UTC (Z)
  233        * (since the same moment in time can be expressed in different
  234        * timezones). To get a canonical string, use the canonicalString()
  235        * method.
  236        */
  237       String toString();
  238   
  239   }

Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]