net.degreedays.time

Class StartOfYear

java.lang.Object

net.degreedays.time.StartOfYear

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<StartOfYear>

public final class StartOfYear
extends java.lang.Object
implements java.lang.Comparable<StartOfYear>, java.io.Serializable

Specifies a definition of "years" that begin on a specified day of the year (e.g. January 1st for calendar years).

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.

Constructor Summary

Constructors

Constructor and Description
StartOfYear(int monthOfYearWithJanAs1, int dayOfMonth) Constructs a StartOfYear object specifying a definition of "years" that begin on the specified first day of the year.

Method Summary

Modifier and Type	Method and Description
int	compareTo(StartOfYear comparisonStartOfYear) Compares this StartOfYear with the specified comparison StartOfYear for chronological order.
int	dayOfMonth() Returns the number between 1 and the number of days in monthOfYear() (inclusive) indicating which day in monthOfYear() is the first day of the "year" defined by this StartOfYear.
boolean	equals(java.lang.Object o) Returns true if o is a StartOfYear object representing the same day of the year as this; false otherwise.
static StartOfYear	fromString(java.lang.String startOfYearString) Parses a string representation of a StartOfYear in --MM-DD format, the format used by XML Schema's gMonthDay type (based on ISO 8601).
int	hashCode() Overridden to ensure consistency with equals.
int	monthOfYear() Returns the number between 1 (January) and 12 (December) indicating the month of the calendar year in which the "year" defined by this StartOfYear starts.
static StartOfYear	of(int monthOfYearWithJanAs1, int dayOfMonth) Returns a non-null StartOfYear object specifying a definition of "years" that begin on the specified first day of the year.
java.lang.String	toString() Returns a non-null, non-empty string representation of this object in --MM-DD format, the format used by XML Schema's gMonthDay type (based on ISO 8601).

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

StartOfYear

public StartOfYear(int monthOfYearWithJanAs1,
                   int dayOfMonth)

Constructs a StartOfYear object specifying a definition of "years" that begin on the specified first day of the year.

Parameters:

monthOfYearWithJanAs1 - a number between 1 and 12 (inclusive) indicating the month of the year in which the "year" should start. For example, if you're working with UK financial years, choose 4 to specify that your "years" start in April.

dayOfMonth - a number between 1 and the number of days in monthOfYearWithJanAs1 (inclusive) indicating which day in monthOfYearWithJanAs1 should be taken as the first day of the "year". Note that the upper limit for February ( monthOfYearWithJanAs1 == 2) is 28, not 29, since February only has 29 days on leap years and a StartOfYear must be applicable to all years.

Throws:

java.lang.IllegalArgumentException - if monthOfYearWithJanAs1 and/or dayOfMonth are invalid according to the rules explained above.

Method Detail

of

public static StartOfYear of(int monthOfYearWithJanAs1,
                             int dayOfMonth)

Returns a non-null StartOfYear object specifying a definition of "years" that begin on the specified first day of the year.

Parameters:

monthOfYearWithJanAs1 - a number between 1 and 12 (inclusive) indicating the month of the year in which the "year" should start. For example, if you're working with UK financial years, choose 4 to specify that your "years" start in April.

dayOfMonth - a number between 1 and the number of days in monthOfYearWithJanAs1 (inclusive) indicating which day in monthOfYearWithJanAs1 should be taken as the first day of the "year". Note that the upper limit for February ( monthOfYearWithJanAs1 == 2) is 28, not 29, since February only has 29 days on leap years and a StartOfYear must be applicable to all years.

Throws:

java.lang.IllegalArgumentException - if monthOfYearWithJanAs1 and/or dayOfMonth are invalid according to the rules explained above.

monthOfYear

public int monthOfYear()

Returns the number between 1 (January) and 12 (December) indicating the month of the calendar year in which the "year" defined by this StartOfYear starts.

dayOfMonth

public int dayOfMonth()

Returns the number between 1 and the number of days in monthOfYear() (inclusive) indicating which day in monthOfYear() is the first day of the "year" defined by this StartOfYear.

If monthOfYear() is 2 (for February), this dayOfMonth() will never be greater than 28, as February 29th only exists in leap years, and StartOfYear has to be applicable to all years.

fromString

public static StartOfYear fromString(java.lang.String startOfYearString)
                              throws java.lang.NumberFormatException

Parses a string representation of a StartOfYear in --MM-DD format, the format used by XML Schema's gMonthDay type (based on ISO 8601).

Note that this method will not accept a string containing the time-zone information that is optionally allowed by XML Schema's gMonthDay type. It also will not accept "--02-29", since that month-day combination only makes sense on leap years, and StartOfYear is designed to be applicable to all years.

Returns:

a non-null StartOfYear object corresponding to the month-day combination represented by startOfYearString.

Throws:

java.lang.NullPointerException - if startOfYearString is null.

java.lang.NumberFormatException - if startOfYearString has an invalid format, or represents an impossible month-day combination.

See Also:

toString()

toString

public java.lang.String toString()

Returns a non-null, non-empty string representation of this object in --MM-DD format, the format used by XML Schema's gMonthDay type (based on ISO 8601).

Overrides:

toString in class java.lang.Object

See Also:

fromString(java.lang.String)

equals

public boolean equals(java.lang.Object o)

Returns true if o is a StartOfYear object representing the same day of the year as this; false otherwise.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overridden to ensure consistency with equals.

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(StartOfYear comparisonStartOfYear)

Compares this StartOfYear with the specified comparison StartOfYear for chronological order.

Specified by:

compareTo in interface java.lang.Comparable<StartOfYear>

Parameters:

comparisonStartOfYear - the StartOfYear to be compared. Cannot be null.

Returns:

a negative integer if this StartOfYear is before comparisonStartOfYear; zero if this StartOfYear is equal to comparisonStartOfYear; or a positive integer if this StartOfYear is after comparisonStartOfYear.

Throws:

java.lang.NullPointerException - if comparisonStartOfYear is null.