/*

 * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.xml.datatype;

import java.math.BigDecimal;

import java.math.BigInteger;

import java.util.Calendar;

import java.util.Date;

import java.util.GregorianCalendar;

import javax.xml.namespace.QName;

/**

 * <p>Immutable representation of a time span as defined in

 *

 * <p>A Duration object represents a period of Gregorian time,

 * which consists of six fields (years, months, days, hours,

 *

 * (which represents that the field is not set),

 * and the seconds field has a non-negative decimal or null.

 *

 * <p>This class provides a number of methods that make it easy

 * to use for the duration datatype of XML Schema 1.0 with

 *

 * <h2>Order relationship</h2>

 * <p>Duration objects only have partial order, where two values A and B

 * <ol>

 *  <li>A==B   (A and B are of the same duration)

 * </ol>

 *

 * <p>For example, 30 days cannot be meaningfully compared to one month.

 * The {@link #compare(Duration duration)} method implements this

 *

 * <p>See the {@link #isLongerThan(Duration)} method for details about

 *

 * <h2>Operations over Duration</h2>

 * <p>This class provides a set of basic arithmetic operations, such

 * as addition, subtraction and multiplication.

 * Because durations don't have total order, an operation could

 * fail for some combinations of operations. For example, you cannot

 * subtract 15 days from 1 month. See the javadoc of those methods

 *

 * <p>Also, division of a duration by a number is not provided because

 *

 * <p>However, you could substitute a division by 3 with multiplying

 *

 * <h2>Range of allowed values</h2>

 * <p>

 * even though {@link Duration} can hold very large or very small values,

 * The impacted methods document their dependency on {@link Calendar}.

 *

 * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>

 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>

 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>

 * @author <a href="mailto:Sunitha.Reddy@Sun.com">Sunitha Reddy</a>

 * @see XMLGregorianCalendar#add(Duration)

 * @since 1.5

 */

public abstract class Duration {

    /**

     */

    private static final boolean DEBUG = true;

    /**

     * Default no-arg constructor.

     *

     * <p>Note: Always use the {@link DatatypeFactory} to

     * The constructor on this class cannot be guaranteed to

     * produce an object with a consistent state and may be

     */

    public Duration() {

    }

    /**

     * maps to. Type is computed based on fields that are set,

     *

     * <table border="2" rules="all" cellpadding="2">

     *   <thead>

     *     <tr>

     *       <th align="center" colspan="7">

     *         <i>(timezone is optional for all date/time datatypes)</i>

     *       </th>

     *     </tr>

     *   </thead>

     *   <tbody>

     *     <tr>

     *       <td>Datatype</td>

     *       <td>year</td>

     *       <td>month</td>

     *       <td>day</td>

     *       <td>hour</td>

     *       <td>minute</td>

     *       <td>second</td>

     *     </tr>

     *     <tr>

     *       <td>{@link DatatypeConstants#DURATION}</td>

     *       <td>X</td>

     *       <td>X</td>

     *       <td>X</td>

     *       <td>X</td>

     *       <td>X</td>

     *       <td>X</td>

     *     </tr>

     *     <tr>

     *       <td>{@link DatatypeConstants#DURATION_DAYTIME}</td>

     *       <td></td>

     *       <td></td>

     *       <td>X</td>

     *       <td>X</td>

     *       <td>X</td>

     *       <td>X</td>

     *     </tr>

     *     <tr>

     *       <td>{@link DatatypeConstants#DURATION_YEARMONTH}</td>

     *       <td>X</td>

     *       <td>X</td>

     *       <td></td>

     *       <td></td>

     *       <td></td>

     *       <td></td>

     *     </tr>

     *   </tbody>

     * </table>

     *

     * @return one of the following constants:

     *   {@link DatatypeConstants#DURATION},

     *   {@link DatatypeConstants#DURATION_DAYTIME} or

     *   {@link DatatypeConstants#DURATION_YEARMONTH}.

     *

     * @throws IllegalStateException If the combination of set fields does not match one of the XML Schema date/time datatypes.

     */

    public QName getXMLSchemaType() {

        boolean yearSet = isSet(DatatypeConstants.YEARS);

        boolean monthSet = isSet(DatatypeConstants.MONTHS);

        boolean daySet = isSet(DatatypeConstants.DAYS);

        boolean hourSet = isSet(DatatypeConstants.HOURS);

        boolean minuteSet = isSet(DatatypeConstants.MINUTES);

        boolean secondSet = isSet(DatatypeConstants.SECONDS);

        // DURATION

        if (yearSet

            && monthSet

            && daySet

            && hourSet

            && minuteSet

            && secondSet) {

            return DatatypeConstants.DURATION;

        }

        // DURATION_DAYTIME

        if (!yearSet

            && !monthSet

            && daySet

            && hourSet

            && minuteSet

            && secondSet) {

            return DatatypeConstants.DURATION_DAYTIME;

        }

        // DURATION_YEARMONTH

        if (yearSet

            && monthSet

            && !daySet

            && !hourSet

            && !minuteSet

            && !secondSet) {

            return DatatypeConstants.DURATION_YEARMONTH;

        }

        // nothing matches

        throw new IllegalStateException(

                "javax.xml.datatype.Duration#getXMLSchemaType():"

                + " this Duration does not match one of the XML Schema date/time datatypes:"

                + " year set = " + yearSet

                + " month set = " + monthSet

                + " day set = " + daySet

                + " hour set = " + hourSet

                + " minute set = " + minuteSet

                + " second set = " + secondSet

        );

    }

    /**

     * Returns the sign of this duration in -1,0, or 1.

     *

     * @return

     *      -1 if this duration is negative, 0 if the duration is zero,

     *      and 1 if the duration is positive.

     */

    public abstract int getSign();

    /**

     *

     *

     *

     */

    public int getYears() {

        return getField(DatatypeConstants.YEARS).intValue();

    }

    /**

     * Obtains the value of the MONTHS field as an integer value,

     * or 0 if not present.

     *

     * This method works just like {@link #getYears()} except

     * that this method works on the MONTHS field.

     *

     */

    public int getMonths() {

        return getField(DatatypeConstants.MONTHS).intValue();

    }

    /**

     * Obtains the value of the DAYS field as an integer value,

     * or 0 if not present.

     *

     * This method works just like {@link #getYears()} except

     * that this method works on the DAYS field.

     *

     */

    public int getDays() {

        return getField(DatatypeConstants.DAYS).intValue();

    }

    /**

     * Obtains the value of the HOURS field as an integer value,

     * or 0 if not present.

     *

     * This method works just like {@link #getYears()} except

     * that this method works on the HOURS field.

     *

     *

     */

    public int getHours() {

        return getField(DatatypeConstants.HOURS).intValue();

    }

    /**

     * Obtains the value of the MINUTES field as an integer value,

     * or 0 if not present.

     *

     * This method works just like {@link #getYears()} except

     * that this method works on the MINUTES field.

     *

     *

     */

    public int getMinutes() {

        return getField(DatatypeConstants.MINUTES).intValue();

    }

    /**

     * Obtains the value of the SECONDS field as an integer value,

     * or 0 if not present.

     *

     * This method works just like {@link #getYears()} except

     * that this method works on the SECONDS field.

     *

     * @return seconds in the integer value. The fraction of seconds

     *   will be discarded (for example, if the actual value is 2.5,

     *   this method returns 2)

     */

    public int getSeconds() {

        return getField(DatatypeConstants.SECONDS).intValue();

    }

    /**

     *

     * <p>If the seconds field carries more digits than milli-second order,

     * those will be simply discarded (or in other words, rounded to zero.)

     * <pre>

     * </pre>

     *

     * <p>

     * Note that this method uses the {@link #addTo(Calendar)} method,

     * very large values in its fields. See the {@link #addTo(Calendar)}

     * method for details.

     *

     * @param startInstant

     *      used to disambiguate this variance. Specifically, this method

     *

     *

     * is null.

     *

     */

    public long getTimeInMillis(final Calendar startInstant) {

        Calendar cal = (Calendar) startInstant.clone();

        addTo(cal);

        return getCalendarTimeInMillis(cal)

                    - getCalendarTimeInMillis(startInstant);

    }

    /**

     *

     * <p>If the seconds field carries more digits than milli-second order,

     * those will be simply discarded (or in other words, rounded to zero.)

     * <pre>

     * </pre>

     *

     * <p>

     * Note that this method uses the {@link #addTo(Date)} method,

     * very large values in its fields. See the {@link #addTo(Date)}

     * method for details.

     *

     * @param startInstant

     *      used to disambiguate this variance. Specifically, this method

     *

     * @throws NullPointerException

     *      If the startInstant parameter is null.

     *

     *

     * @see #getTimeInMillis(Calendar)

     */

    public long getTimeInMillis(final Date startInstant) {

        Calendar cal = new GregorianCalendar();

        cal.setTime(startInstant);

        this.addTo(cal);

        return getCalendarTimeInMillis(cal) - startInstant.getTime();

    }

    /**

     * Gets the value of a field.

     *

     * Fields of a duration object may contain arbitrary large value.

     * Therefore this method is designed to return a {@link Number} object.

     *

     * In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned

     * number will be a non-negative integer. In case of seconds,

     * the returned number may be a non-negative decimal value.

     *

     * @param field

     *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,

     *      MINUTES, or SECONDS.)

     * @return

     *      If the specified field is present, this method returns

     *      a non-null non-negative {@link Number} object that

     *      represents its value. If it is not present, return null.

     *      For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method

     *      returns a {@link java.math.BigInteger} object. For SECONDS, this

     *      method returns a {@link java.math.BigDecimal}.

     *

     */

    public abstract Number getField(final DatatypeConstants.Field field);

    /**

     * Checks if a field is set.

     *

     * A field of a duration object may or may not be present.

     * This method can be used to test if a field is present.

     *

     * @param field

     *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,

     *      MINUTES, or SECONDS.)

     * @return

     *      true if the field is present. false if not.

     *

     * @throws NullPointerException

     *      If the field parameter is null.

     */

    public abstract boolean isSet(final DatatypeConstants.Field field);

    /**

     *

     * <pre>

     * "1 day" + "-3 days" = "-2 days"

     * "1 year" + "1 day" = "1 year and 1 day"

     * "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"

     * "15 hours" + "-3 days" = "-(2 days,9 hours)"

     * "1 year" + "-1 day" = IllegalStateException

     * </pre>

     *

     * <p>Since there's no way to meaningfully subtract 1 day from 1 month,

     * there are cases where the operation fails in

     *

     * <p>

     * <p>

     * are both positive without losing generality (i.e.,

     *

     * <p>

     * field by field addition where missing fields are treated as 0.

     * <p>

     * <p>

     *

     *

     * @return

     *      non-null valid Duration object.

     *

     * @throws NullPointerException

     *      If the rhs parameter is null.

     * @throws IllegalStateException

     *      If two durations cannot be meaningfully added. For

     *      example, adding negative one day to one month causes

     *      this exception.

     *

     *

     * @see #subtract(Duration)

     */

    public abstract Duration add(final Duration rhs);

    /**

     * Adds this duration to a {@link Calendar} object.

     *

     * <p>

     * Calls {@link java.util.Calendar#add(int,int)} in the

     * order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS

     * if those fields are present. Because the {@link Calendar} class

     * uses int to hold values, there are cases where this method

     * won't work correctly (for example if values of fields

     * exceed the range of int.)

     *

     * <p>

     * Also, since this duration class is a Gregorian duration, this

     * method will not work correctly if the given {@link Calendar}

     * object is based on some other calendar systems.

     *

     * <p>

     * beyond milliseconds will be simply ignored. For example, if

     * this duration is "P1.23456S", then 1 is added to SECONDS,

     * 234 is added to MILLISECONDS, and the rest will be unused.

     *

     * <p>