Package org.joda.time

Class MutableDateTime

  • All Implemented Interfaces:
    Serializable, Cloneable, Comparable<ReadableInstant>, ReadableDateTime, ReadableInstant, ReadWritableDateTime, ReadWritableInstant
    public class MutableDateTime
extends BaseDateTime
implements ReadWritableDateTime, Cloneable, Serializable
    MutableDateTime is the standard implementation of a modifiable datetime class. It holds the datetime as milliseconds from the Java epoch of 1970-01-01T00:00:00Z.

    This class uses a Chronology internally. The Chronology determines how the millisecond instant value is converted into the date time fields. The default Chronology is ISOChronology which is the agreed international standard and compatible with the modern Gregorian calendar.

    Each individual field can be accessed in two ways:

    • getHourOfDay()
    • hourOfDay().get()
    The second technique also provides access to other useful methods on the field:
    • get numeric value
    • set numeric value
    • add to numeric value
    • add to numeric value wrapping with the field
    • get text value
    • get short text value
    • set text value
    • field maximum value
    • field minimum value

    MutableDateTime is mutable and not thread-safe, unless concurrent threads are not invoking mutator methods.

    Since:
    1.0
    See Also:
    DateTime, Serialized Form

    • Constructor Detail

      • MutableDateTime

        public MutableDateTime()
        Constructs an instance set to the current system millisecond time using ISOChronology in the default time zone.
        See Also:
        now()

      • MutableDateTime

        public MutableDateTime​(DateTimeZone zone)
        Constructs an instance set to the current system millisecond time using ISOChronology in the specified time zone.

        If the specified time zone is null, the default zone is used.

        Parameters:
        zone - the time zone, null means default zone
        See Also:
        now(DateTimeZone)

      • MutableDateTime

        public MutableDateTime​(Chronology chronology)
        Constructs an instance set to the current system millisecond time using the specified chronology.

        If the chronology is null, ISOChronology in the default time zone is used.

        Parameters:
        chronology - the chronology, null means ISOChronology in default zone
        See Also:
        now(Chronology)

      • MutableDateTime

        public MutableDateTime​(long instant)
        Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z using ISOChronology in the default time zone.
        Parameters:
        instant - the milliseconds from 1970-01-01T00:00:00Z

      • MutableDateTime

        public MutableDateTime​(long instant,
                       DateTimeZone zone)
        Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z using ISOChronology in the specified time zone.

        If the specified time zone is null, the default zone is used.

        Parameters:
        instant - the milliseconds from 1970-01-01T00:00:00Z
        zone - the time zone, null means default zone

      • MutableDateTime

        public MutableDateTime​(long instant,
                       Chronology chronology)
        Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z using the specified chronology.

        If the chronology is null, ISOChronology in the default time zone is used.

        Parameters:
        instant - the milliseconds from 1970-01-01T00:00:00Z
        chronology - the chronology, null means ISOChronology in default zone

      • MutableDateTime

        public MutableDateTime​(Object instant)
        Constructs an instance from an Object that represents a datetime.

        If the object implies a chronology (such as GregorianCalendar does), then that chronology will be used. Otherwise, ISO default is used. Thus if a GregorianCalendar is passed in, the chronology used will be GJ, but if a Date is passed in the chronology will be ISO.

        The recognised object types are defined in ConverterManager and include ReadableInstant, String, Calendar and Date.

        Parameters:
        instant - the datetime object, null means now
        Throws:
        IllegalArgumentException - if the instant is invalid

      • MutableDateTime

        public MutableDateTime​(Object instant,
                       DateTimeZone zone)
        Constructs an instance from an Object that represents a datetime, forcing the time zone to that specified.

        If the object implies a chronology (such as GregorianCalendar does), then that chronology will be used, but with the time zone adjusted. Otherwise, ISO is used in the specified time zone. If the specified time zone is null, the default zone is used. Thus if a GregorianCalendar is passed in, the chronology used will be GJ, but if a Date is passed in the chronology will be ISO.

        The recognised object types are defined in ConverterManager and include ReadableInstant, String, Calendar and Date.

        Parameters:
        instant - the datetime object, null means now
        zone - the time zone, null means default time zone
        Throws:
        IllegalArgumentException - if the instant is invalid

      • MutableDateTime

        public MutableDateTime​(Object instant,
                       Chronology chronology)
        Constructs an instance from an Object that represents a datetime, using the specified chronology.

        If the chronology is null, ISO in the default time zone is used. Any chronology implied by the object (such as GregorianCalendar does) is ignored.

        The recognised object types are defined in ConverterManager and include ReadableInstant, String, Calendar and Date.

        Parameters:
        instant - the datetime object, null means now
        chronology - the chronology, null means ISOChronology in default zone
        Throws:
        IllegalArgumentException - if the instant is invalid

      • MutableDateTime

        public MutableDateTime​(int year,
                       int monthOfYear,
                       int dayOfMonth,
                       int hourOfDay,
                       int minuteOfHour,
                       int secondOfMinute,
                       int millisOfSecond)
        Constructs an instance from datetime field values using ISOChronology in the default time zone.
        Parameters:
        year - the year
        monthOfYear - the month of the year
        dayOfMonth - the day of the month
        hourOfDay - the hour of the day
        minuteOfHour - the minute of the hour
        secondOfMinute - the second of the minute
        millisOfSecond - the millisecond of the second

      • MutableDateTime

        public MutableDateTime​(int year,
                       int monthOfYear,
                       int dayOfMonth,
                       int hourOfDay,
                       int minuteOfHour,
                       int secondOfMinute,
                       int millisOfSecond,
                       DateTimeZone zone)
        Constructs an instance from datetime field values using ISOChronology in the specified time zone.

        If the specified time zone is null, the default zone is used.

        Parameters:
        year - the year
        monthOfYear - the month of the year
        dayOfMonth - the day of the month
        hourOfDay - the hour of the day
        minuteOfHour - the minute of the hour
        secondOfMinute - the second of the minute
        millisOfSecond - the millisecond of the second
        zone - the time zone, null means default time zone

      • MutableDateTime

        public MutableDateTime​(int year,
                       int monthOfYear,
                       int dayOfMonth,
                       int hourOfDay,
                       int minuteOfHour,
                       int secondOfMinute,
                       int millisOfSecond,
                       Chronology chronology)
        Constructs an instance from datetime field values using the specified chronology.

        If the chronology is null, ISOChronology in the default time zone is used.

        Parameters:
        year - the year
        monthOfYear - the month of the year
        dayOfMonth - the day of the month
        hourOfDay - the hour of the day
        minuteOfHour - the minute of the hour
        secondOfMinute - the second of the minute
        millisOfSecond - the millisecond of the second
        chronology - the chronology, null means ISOChronology in default zone

    • Method Detail

      • now

        public static MutableDateTime now()
        Obtains a MutableDateTime set to the current system millisecond time using ISOChronology in the default time zone.
        Returns:
        the current date-time, not null
        Since:
        2.0

      • now

        public static MutableDateTime now​(DateTimeZone zone)
        Obtains a MutableDateTime set to the current system millisecond time using ISOChronology in the specified time zone.
        Parameters:
        zone - the time zone, not null
        Returns:
        the current date-time, not null
        Since:
        2.0

      • now

        public static MutableDateTime now​(Chronology chronology)
        Obtains a MutableDateTime set to the current system millisecond time using the specified chronology.
        Parameters:
        chronology - the chronology, not null
        Returns:
        the current date-time, not null
        Since:
        2.0

      • parse

        public static MutableDateTime parse​(String str,
                                    DateTimeFormatter formatter)
        Parses a MutableDateTime from the specified string using a formatter.
        Parameters:
        str - the string to parse, not null
        formatter - the formatter to use, not null
        Since:
        2.0

      • getRoundingField

        public DateTimeField getRoundingField()
        Gets the field used for rounding this instant, returning null if rounding is not enabled.
        Returns:
        the rounding field

      • getRoundingMode

        public int getRoundingMode()
        Gets the rounding mode for this instant, returning ROUND_NONE if rounding is not enabled.
        Returns:
        the rounding mode constant

      • setRounding

        public void setRounding​(DateTimeField field)
        Sets the status of rounding to use the specified field and ROUND_FLOOR mode. A null field will disable rounding. Once set, the instant is then rounded using the new field and mode.

        Enabling rounding will cause all subsequent calls to setMillis(long) to be rounded. This can be used to control the precision of the instant, for example by setting a rounding field of minuteOfDay, the seconds and milliseconds will always be zero.

        Parameters:
        field - rounding field or null to disable

      • setRounding

        public void setRounding​(DateTimeField field,
                        int mode)
        Sets the status of rounding to use the specified field and mode. A null field or mode of ROUND_NONE will disable rounding. Once set, the instant is then rounded using the new field and mode.

        Enabling rounding will cause all subsequent calls to setMillis(long) to be rounded. This can be used to control the precision of the instant, for example by setting a rounding field of minuteOfDay, the seconds and milliseconds will always be zero.

        Parameters:
        field - rounding field or null to disable
        mode - rounding mode or ROUND_NONE to disable
        Throws:
        IllegalArgumentException - if mode is unknown, no exception if field is null

      • setMillis

        public void setMillis​(long instant)
        Set the milliseconds of the datetime.

        All changes to the millisecond field occurs via this method.

        Specified by:
        setMillis in interface ReadWritableInstant
        Parameters:
        instant - the milliseconds since 1970-01-01T00:00:00Z to set the datetime to

      • setMillis

        public void setMillis​(ReadableInstant instant)
        Sets the millisecond instant of this instant from another.

        This method does not change the chronology of this instant, just the millisecond instant.

        Specified by:
        setMillis in interface ReadWritableInstant
        Parameters:
        instant - the instant to use, null means now

      • add

        public void add​(long duration)
        Add an amount of time to the datetime.
        Specified by:
        add in interface ReadWritableInstant
        Parameters:
        duration - the millis to add
        Throws:
        ArithmeticException - if the result exceeds the capacity of the instant

      • add

        public void add​(ReadableDuration duration)
        Adds a duration to this instant.

        This will typically change the value of most fields.

        Specified by:
        add in interface ReadWritableInstant
        Parameters:
        duration - the duration to add, null means add zero
        Throws:
        ArithmeticException - if the result exceeds the capacity of the instant

      • add

        public void add​(ReadableDuration duration,
                int scalar)
        Adds a duration to this instant specifying how many times to add.

        This will typically change the value of most fields.

        Specified by:
        add in interface ReadWritableInstant
        Parameters:
        duration - the duration to add, null means add zero
        scalar - direction and amount to add, which may be negative
        Throws:
        ArithmeticException - if the result exceeds the capacity of the instant

      • add

        public void add​(ReadablePeriod period)
        Adds a period to this instant.

        This will typically change the value of most fields.

        Specified by:
        add in interface ReadWritableInstant
        Parameters:
        period - the period to add, null means add zero
        Throws:
        ArithmeticException - if the result exceeds the capacity of the instant

      • add

        public void add​(ReadablePeriod period,
                int scalar)
        Adds a period to this instant specifying how many times to add.

        This will typically change the value of most fields.

        Specified by:
        add in interface ReadWritableInstant
        Parameters:
        period - the period to add, null means add zero
        scalar - direction and amount to add, which may be negative
        Throws:
        ArithmeticException - if the result exceeds the capacity of the instant

      • setChronology

        public void setChronology​(Chronology chronology)
        Set the chronology of the datetime.

        All changes to the chronology occur via this method.

        Specified by:
        setChronology in interface ReadWritableInstant
        Parameters:
        chronology - the chronology to use, null means ISOChronology in default zone

      • setZone

        public void setZone​(DateTimeZone newZone)
        Sets the time zone of the datetime, changing the chronology and field values.

        Changing the zone using this method retains the millisecond instant. The millisecond instant is adjusted in the new zone to compensate. chronology. Setting the time zone does not affect the millisecond value of this instant.

        If the chronology already has this time zone, no change occurs.

        Specified by:
        setZone in interface ReadWritableInstant
        Parameters:
        newZone - the time zone to use, null means default zone
        See Also:
        setZoneRetainFields(org.joda.time.DateTimeZone)

      • setZoneRetainFields

        public void setZoneRetainFields​(DateTimeZone newZone)
        Sets the time zone of the datetime, changing the chronology and millisecond.

        Changing the zone using this method retains the field values. The millisecond instant is adjusted in the new zone to compensate.

        If the chronology already has this time zone, no change occurs.

        Specified by:
        setZoneRetainFields in interface ReadWritableInstant
        Parameters:
        newZone - the time zone to use, null means default zone
        See Also:
        setZone(org.joda.time.DateTimeZone)

      • set

        public void set​(DateTimeFieldType type,
                int value)
        Sets the value of one of the fields of the instant, such as hourOfDay.
        Specified by:
        set in interface ReadWritableInstant
        Parameters:
        type - a field type, usually obtained from DateTimeFieldType, not null
        value - the value to set the field to
        Throws:
        IllegalArgumentException - if the value is null or invalid

      • add

        public void add​(DurationFieldType type,
                int amount)
        Adds to the instant specifying the duration and multiple to add.
        Specified by:
        add in interface ReadWritableInstant
        Parameters:
        type - a field type, usually obtained from DateTimeFieldType, not null
        amount - the amount to add of this duration
        Throws:
        IllegalArgumentException - if the value is null or invalid
        ArithmeticException - if the result exceeds the capacity of the instant

      • setWeekOfWeekyear

        public void setWeekOfWeekyear​(int weekOfWeekyear)
        Set the week of weekyear to the specified value.
        Specified by:
        setWeekOfWeekyear in interface ReadWritableDateTime
        Parameters:
        weekOfWeekyear - the week of the weekyear
        Throws:
        IllegalArgumentException - if the value is invalid

      • setSecondOfMinute

        public void setSecondOfMinute​(int secondOfMinute)
        Set the second of the minute to the specified value.
        Specified by:
        setSecondOfMinute in interface ReadWritableDateTime
        Parameters:
        secondOfMinute - the second of minute
        Throws:
        IllegalArgumentException - if the value is invalid

      • setMillisOfSecond

        public void setMillisOfSecond​(int millisOfSecond)
        Set the millis of the second to the specified value.
        Specified by:
        setMillisOfSecond in interface ReadWritableDateTime
        Parameters:
        millisOfSecond - the millis of second
        Throws:
        IllegalArgumentException - if the value is invalid

      • addMillis

        public void addMillis​(int millis)
        Add a number of milliseconds to the date. The implementation of this method differs from the add(long) method in that a DateTimeField performs the addition.
        Specified by:
        addMillis in interface ReadWritableDateTime
        Parameters:
        millis - the milliseconds to add
        Throws:
        IllegalArgumentException - if the value is invalid

      • setDate

        public void setDate​(long instant)
        Set the date from milliseconds. The time part of this object will be unaffected.
        Parameters:
        instant - an instant to copy the date from, time part ignored
        Throws:
        IllegalArgumentException - if the value is invalid

      • setDate

        public void setDate​(ReadableInstant instant)
        Set the date from another instant. The time part of this object will be unaffected.

        If the input is a ReadableDateTime then it is converted to the same time-zone as this object before using the instant millis.

        Parameters:
        instant - an instant to copy the date from, time part ignored
        Throws:
        IllegalArgumentException - if the object is invalid

      • setDate

        public void setDate​(int year,
                    int monthOfYear,
                    int dayOfMonth)
        Set the date from fields. The time part of this object will be unaffected.
        Specified by:
        setDate in interface ReadWritableDateTime
        Parameters:
        year - the year
        monthOfYear - the month of the year
        dayOfMonth - the day of the month
        Throws:
        IllegalArgumentException - if the value is invalid

      • setTime

        public void setTime​(long millis)
        Set the time from milliseconds. The date part of this object will be unaffected.
        Parameters:
        millis - an instant to copy the time from, date part ignored
        Throws:
        IllegalArgumentException - if the value is invalid

      • setTime

        public void setTime​(ReadableInstant instant)
        Set the time from another instant. The date part of this object will be unaffected.
        Parameters:
        instant - an instant to copy the time from, date part ignored
        Throws:
        IllegalArgumentException - if the object is invalid

      • setTime

        public void setTime​(int hour,
                    int minuteOfHour,
                    int secondOfMinute,
                    int millisOfSecond)
        Set the time from fields. The date part of this object will be unaffected.
        Specified by:
        setTime in interface ReadWritableDateTime
        Parameters:
        hour - the hour
        minuteOfHour - the minute of the hour
        secondOfMinute - the second of the minute
        millisOfSecond - the millisecond of the second
        Throws:
        IllegalArgumentException - if the value is invalid

      • setDateTime

        public void setDateTime​(int year,
                        int monthOfYear,
                        int dayOfMonth,
                        int hourOfDay,
                        int minuteOfHour,
                        int secondOfMinute,
                        int millisOfSecond)
        Set the date and time from fields.
        Specified by:
        setDateTime in interface ReadWritableDateTime
        Parameters:
        year - the year
        monthOfYear - the month of the year
        dayOfMonth - the day of the month
        hourOfDay - the hour of the day
        minuteOfHour - the minute of the hour
        secondOfMinute - the second of the minute
        millisOfSecond - the millisecond of the second
        Throws:
        IllegalArgumentException - if the value is invalid

      • property

        public MutableDateTime.Property property​(DateTimeFieldType type)
        Gets the property object for the specified type, which contains many useful methods.
        Parameters:
        type - the field type to get the chronology for
        Returns:
        the property object
        Throws:
        IllegalArgumentException - if the field is null or unsupported
        Since:
        1.2

      • centuryOfEra

        public MutableDateTime.Property centuryOfEra()
        Get the century of era property.
        Returns:
        the year of era property

      • yearOfCentury

        public MutableDateTime.Property yearOfCentury()
        Get the year of century property.
        Returns:
        the year of era property

      • yearOfEra

        public MutableDateTime.Property yearOfEra()
        Get the year of era property.
        Returns:
        the year of era property

      • weekyear

        public MutableDateTime.Property weekyear()
        Get the year of a week based year property.
        Returns:
        the year of a week based year property

      • monthOfYear

        public MutableDateTime.Property monthOfYear()
        Get the month of year property.
        Returns:
        the month of year property

      • weekOfWeekyear

        public MutableDateTime.Property weekOfWeekyear()
        Get the week of a week based year property.
        Returns:
        the week of a week based year property

      • dayOfYear

        public MutableDateTime.Property dayOfYear()
        Get the day of year property.
        Returns:
        the day of year property

      • hourOfDay

        public MutableDateTime.Property hourOfDay()
        Get the hour of day field property
        Returns:
        the hour of day property

      • minuteOfDay

        public MutableDateTime.Property minuteOfDay()
        Get the minute of day property
        Returns:
        the minute of day property

      • minuteOfHour

        public MutableDateTime.Property minuteOfHour()
        Get the minute of hour field property
        Returns:
        the minute of hour property

      • secondOfDay

        public MutableDateTime.Property secondOfDay()
        Get the second of day property
        Returns:
        the second of day property

      • secondOfMinute

        public MutableDateTime.Property secondOfMinute()
        Get the second of minute field property
        Returns:
        the second of minute property

      • millisOfDay

        public MutableDateTime.Property millisOfDay()
        Get the millis of day property
        Returns:
        the millis of day property

      • millisOfSecond

        public MutableDateTime.Property millisOfSecond()
        Get the millis of second property
        Returns:
        the millis of second property

      • copy

        public MutableDateTime copy()
        Clone this object without having to cast the returned object.
        Returns:
        a clone of the this object.

      • clone

        public Object clone()
        Clone this object.
        Returns:
        a clone of this object.