You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2022/03/27 15:24:41 UTC
[commons-lang] branch master updated: Fixing and adding DateUtils exception javadocs with new tests when needed (#871)
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git
The following commit(s) were added to refs/heads/master by this push:
new 75bb103 Fixing and adding DateUtils exception javadocs with new tests when needed (#871)
75bb103 is described below
commit 75bb10331c02d979561b5804d41641bf82192d2d
Author: Diego Marcilio <dv...@gmail.com>
AuthorDate: Sun Mar 27 17:24:33 2022 +0200
Fixing and adding DateUtils exception javadocs with new tests when needed (#871)
---
.../org/apache/commons/lang3/time/DateUtils.java | 86 +++++++++++++---------
.../apache/commons/lang3/time/DateUtilsTest.java | 77 +++++++++++++++++--
2 files changed, 122 insertions(+), 41 deletions(-)
diff --git a/src/main/java/org/apache/commons/lang3/time/DateUtils.java b/src/main/java/org/apache/commons/lang3/time/DateUtils.java
index 13eec34..57eed68 100644
--- a/src/main/java/org/apache/commons/lang3/time/DateUtils.java
+++ b/src/main/java/org/apache/commons/lang3/time/DateUtils.java
@@ -389,7 +389,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addYears(final Date date, final int amount) {
return add(date, Calendar.YEAR, amount);
@@ -402,7 +402,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addMonths(final Date date, final int amount) {
return add(date, Calendar.MONTH, amount);
@@ -415,7 +415,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addWeeks(final Date date, final int amount) {
return add(date, Calendar.WEEK_OF_YEAR, amount);
@@ -428,7 +428,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addDays(final Date date, final int amount) {
return add(date, Calendar.DAY_OF_MONTH, amount);
@@ -441,7 +441,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addHours(final Date date, final int amount) {
return add(date, Calendar.HOUR_OF_DAY, amount);
@@ -454,7 +454,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addMinutes(final Date date, final int amount) {
return add(date, Calendar.MINUTE, amount);
@@ -467,7 +467,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addSeconds(final Date date, final int amount) {
return add(date, Calendar.SECOND, amount);
@@ -480,7 +480,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to add, may be negative
* @return the new {@code Date} with the amount added
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
*/
public static Date addMilliseconds(final Date date, final int amount) {
return add(date, Calendar.MILLISECOND, amount);
@@ -511,7 +511,7 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
* @since 2.4
*/
public static Date setYears(final Date date, final int amount) {
@@ -525,7 +525,9 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
+ * @throws IllegalArgumentException if {@code amount} is not in the range
+ * {@code 0 <= amount <= 11}
* @since 2.4
*/
public static Date setMonths(final Date date, final int amount) {
@@ -539,7 +541,9 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
+ * @throws IllegalArgumentException if {@code amount} is not in the range
+ * {@code 1 <= amount <= 31}
* @since 2.4
*/
public static Date setDays(final Date date, final int amount) {
@@ -554,7 +558,9 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
+ * @throws IllegalArgumentException if {@code amount} is not in the range
+ * {@code 0 <= amount <= 23}
* @since 2.4
*/
public static Date setHours(final Date date, final int amount) {
@@ -568,7 +574,9 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
+ * @throws IllegalArgumentException if {@code amount} is not in the range
+ * {@code 0 <= amount <= 59}
* @since 2.4
*/
public static Date setMinutes(final Date date, final int amount) {
@@ -582,7 +590,9 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
+ * @throws IllegalArgumentException if {@code amount} is not in the range
+ * {@code 0 <= amount <= 59}
* @since 2.4
*/
public static Date setSeconds(final Date date, final int amount) {
@@ -596,7 +606,9 @@ public class DateUtils {
* @param date the date, not null
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
+ * @throws IllegalArgumentException if {@code amount} is not in the range
+ * {@code 0 <= amount <= 999}
* @since 2.4
*/
public static Date setMilliseconds(final Date date, final int amount) {
@@ -612,7 +624,7 @@ public class DateUtils {
* @param calendarField the {@code Calendar} field to set the amount to
* @param amount the amount to set
* @return a new {@code Date} set with the specified value
- * @throws IllegalArgumentException if the date is null
+ * @throws NullPointerException if the date is null
* @since 2.4
*/
private static Date set(final Date date, final int calendarField, final int amount) {
@@ -676,6 +688,7 @@ public class DateUtils {
* @param date the date to work with, not null
* @param field the field from {@code Calendar} or {@code SEMI_MONTH}
* @return the different rounded date, not null
+ * @throws NullPointerException if the date is null
* @throws ArithmeticException if the year is over 280 million
*/
public static Date round(final Date date, final int field) {
@@ -710,7 +723,7 @@ public class DateUtils {
* @param date the date to work with, not null
* @param field the field from {@code Calendar} or {@code SEMI_MONTH}
* @return the different rounded date, not null
- * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the date is {@code null}
* @throws ArithmeticException if the year is over 280 million
*/
public static Calendar round(final Calendar date, final int field) {
@@ -750,7 +763,7 @@ public class DateUtils {
* @param date the date to work with, either {@code Date} or {@code Calendar}, not null
* @param field the field from {@code Calendar} or {@code SEMI_MONTH}
* @return the different rounded date, not null
- * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the date is {@code null}
* @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
* @throws ArithmeticException if the year is over 280 million
*/
@@ -802,7 +815,7 @@ public class DateUtils {
* @param date the date to work with, not null
* @param field the field from {@code Calendar} or {@code SEMI_MONTH}
* @return the different truncated date, not null
- * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the date is {@code null}
* @throws ArithmeticException if the year is over 280 million
*/
public static Calendar truncate(final Calendar date, final int field) {
@@ -826,7 +839,7 @@ public class DateUtils {
* @param date the date to work with, either {@code Date} or {@code Calendar}, not null
* @param field the field from {@code Calendar} or {@code SEMI_MONTH}
* @return the different truncated date, not null
- * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the date is {@code null}
* @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
* @throws ArithmeticException if the year is over 280 million
*/
@@ -879,7 +892,7 @@ public class DateUtils {
* @param date the date to work with, not null
* @param field the field from {@code Calendar} or {@code SEMI_MONTH}
* @return the different ceil date, not null
- * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the date is {@code null}
* @throws ArithmeticException if the year is over 280 million
* @since 2.5
*/
@@ -904,7 +917,7 @@ public class DateUtils {
* @param date the date to work with, either {@code Date} or {@code Calendar}, not null
* @param field the field from {@code Calendar} or {@code SEMI_MONTH}
* @return the different ceil date, not null
- * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the date is {@code null}
* @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
* @throws ArithmeticException if the year is over 280 million
* @since 2.5
@@ -1122,7 +1135,7 @@ public class DateUtils {
* {@link DateUtils#RANGE_WEEK_RELATIVE},
* {@link DateUtils#RANGE_WEEK_CENTER}
* @return the date iterator, not null
- * @throws IllegalArgumentException if the date is {@code null}
+ * @throws IllegalArgumentException if calendar is {@code null}
* @throws IllegalArgumentException if the rangeStyle is invalid
*/
public static Iterator<Calendar> iterator(final Calendar focus, final int rangeStyle) {
@@ -1255,8 +1268,8 @@ public class DateUtils {
* @param date the date to work with, not null
* @param fragment the {@code Calendar} field part of date to calculate
* @return number of milliseconds within the fragment of date
- * @throws IllegalArgumentException if the date is {@code null} or
- * fragment is not supported
+ * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the fragment is not supported
* @since 2.4
*/
public static long getFragmentInMilliseconds(final Date date, final int fragment) {
@@ -1293,8 +1306,8 @@ public class DateUtils {
* @param date the date to work with, not null
* @param fragment the {@code Calendar} field part of date to calculate
* @return number of seconds within the fragment of date
- * @throws IllegalArgumentException if the date is {@code null} or
- * fragment is not supported
+ * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the fragment is not supported
* @since 2.4
*/
public static long getFragmentInSeconds(final Date date, final int fragment) {
@@ -1331,8 +1344,8 @@ public class DateUtils {
* @param date the date to work with, not null
* @param fragment the {@code Calendar} field part of date to calculate
* @return number of minutes within the fragment of date
- * @throws IllegalArgumentException if the date is {@code null} or
- * fragment is not supported
+ * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the fragment is not supported
* @since 2.4
*/
public static long getFragmentInMinutes(final Date date, final int fragment) {
@@ -1369,8 +1382,8 @@ public class DateUtils {
* @param date the date to work with, not null
* @param fragment the {@code Calendar} field part of date to calculate
* @return number of hours within the fragment of date
- * @throws IllegalArgumentException if the date is {@code null} or
- * fragment is not supported
+ * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the fragment is not supported
* @since 2.4
*/
public static long getFragmentInHours(final Date date, final int fragment) {
@@ -1407,8 +1420,8 @@ public class DateUtils {
* @param date the date to work with, not null
* @param fragment the {@code Calendar} field part of date to calculate
* @return number of days within the fragment of date
- * @throws IllegalArgumentException if the date is {@code null} or
- * fragment is not supported
+ * @throws NullPointerException if the date is {@code null}
+ * @throws IllegalArgumentException if the fragment is not supported
* @since 2.4
*/
public static long getFragmentInDays(final Date date, final int fragment) {
@@ -1706,7 +1719,7 @@ public class DateUtils {
* @param date2 the second date, not {@code null}
* @param field the field from {@code Calendar}
* @return {@code true} if equal; otherwise {@code false}
- * @throws IllegalArgumentException if any argument is {@code null}
+ * @throws NullPointerException if any argument is {@code null}
* @see #truncate(Date, int)
* @see #truncatedEquals(Calendar, Calendar, int)
* @since 3.0
@@ -1744,7 +1757,7 @@ public class DateUtils {
* @param field the field from {@code Calendar}
* @return a negative integer, zero, or a positive integer as the first
* date is less than, equal to, or greater than the second.
- * @throws IllegalArgumentException if any argument is {@code null}
+ * @throws NullPointerException if any argument is {@code null}
* @see #truncate(Calendar, int)
* @see #truncatedCompareTo(Date, Date, int)
* @since 3.0
@@ -1755,6 +1768,9 @@ public class DateUtils {
return truncatedDate1.compareTo(truncatedDate2);
}
+ /**
+ * @throws NullPointerException if {@code date == null}
+ */
private static void validateDateNotNull(final Date date) {
Validate.notNull(date, "date");
}
diff --git a/src/test/java/org/apache/commons/lang3/time/DateUtilsTest.java b/src/test/java/org/apache/commons/lang3/time/DateUtilsTest.java
index 7247122..bd82335 100644
--- a/src/test/java/org/apache/commons/lang3/time/DateUtilsTest.java
+++ b/src/test/java/org/apache/commons/lang3/time/DateUtilsTest.java
@@ -230,6 +230,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 4, 4, 3, 2, 1);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addDays(null, 0));
}
@Test
@@ -248,6 +250,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 3, 3, 2, 1);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addHours(null, 0));
}
@Test
@@ -266,6 +270,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 4, 3, 2, 0);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addMilliseconds(null, 0));
}
@Test
@@ -284,6 +290,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 4, 2, 2, 1);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addMinutes(null, 0));
}
@Test
@@ -302,6 +310,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 5, 5, 4, 3, 2, 1);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addMonths(null, 0));
}
@Test
@@ -320,6 +330,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 4, 3, 1, 1);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addSeconds(null, 0));
}
@Test
@@ -338,6 +350,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1); // july
assertDate(result, 2000, 5, 28, 4, 3, 2, 1); // june
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addMonths(null, 0));
}
@Test
@@ -356,6 +370,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 1999, 6, 5, 4, 3, 2, 1);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.addYears(null, 0));
}
/**
@@ -1185,10 +1201,17 @@ public class DateUtilsTest {
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 29, 4, 3, 2, 1);
+ final String outsideOfRangeAssertionMessage = "DateUtils.setDays did not throw an expected IllegalArgumentException for amount outside of range 1 to 31.";
assertThrows(
IllegalArgumentException.class,
() -> DateUtils.setDays(BASE_DATE, 32),
- "DateUtils.setDays did not throw an expected IllegalArgumentException.");
+ outsideOfRangeAssertionMessage);
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> DateUtils.setDays(BASE_DATE, 0),
+ outsideOfRangeAssertionMessage);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.setDays(null, 1));
}
// -----------------------------------------------------------------------
@@ -1204,10 +1227,17 @@ public class DateUtilsTest {
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 23, 3, 2, 1);
+ final String outsideOfRangeAssertionMessage = "DateUtils.setHours did not throw an expected IllegalArgumentException for amount outside of range 0 to 23.";
assertThrows(
IllegalArgumentException.class,
() -> DateUtils.setHours(BASE_DATE, 24),
- "DateUtils.setHours did not throw an expected IllegalArgumentException.");
+ outsideOfRangeAssertionMessage);
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> DateUtils.setHours(BASE_DATE, -1),
+ outsideOfRangeAssertionMessage);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.setHours(null, 0));
}
// -----------------------------------------------------------------------
@@ -1223,10 +1253,17 @@ public class DateUtilsTest {
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 4, 3, 2, 999);
+ final String outsideOfRangeAssertionMessage = "DateUtils.setMilliseconds did not throw an expected IllegalArgumentException for range outside of 0 to 999.";
assertThrows(
IllegalArgumentException.class,
() -> DateUtils.setMilliseconds(BASE_DATE, 1000),
- "DateUtils.setMilliseconds did not throw an expected IllegalArgumentException.");
+ outsideOfRangeAssertionMessage);
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> DateUtils.setMilliseconds(BASE_DATE, -1),
+ outsideOfRangeAssertionMessage);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.setMilliseconds(null, 0));
}
// -----------------------------------------------------------------------
@@ -1242,10 +1279,17 @@ public class DateUtilsTest {
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 4, 59, 2, 1);
+ final String outsideOfRangeAssertionMessage = "DateUtils.setMinutes did not throw an expected IllegalArgumentException for amount outside of range 0 to 59.";
assertThrows(
IllegalArgumentException.class,
() -> DateUtils.setMinutes(BASE_DATE, 60),
- "DateUtils.setMinutes did not throw an expected IllegalArgumentException.");
+ outsideOfRangeAssertionMessage);
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> DateUtils.setMinutes(BASE_DATE, -1),
+ outsideOfRangeAssertionMessage);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.setMinutes(null, 0));
}
// -----------------------------------------------------------------------
@@ -1261,10 +1305,22 @@ public class DateUtilsTest {
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 1, 5, 4, 3, 2, 1);
+ result = DateUtils.setMonths(BASE_DATE, 0);
+ assertNotSame(BASE_DATE, result);
+ assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
+ assertDate(result, 2000, 0, 5, 4, 3, 2, 1);
+
+ final String outsideOfRangeAssertionMessage = "DateUtils.setMonths did not throw an expected IllegalArgumentException for amount outside of range 0 to 11.";
assertThrows(
IllegalArgumentException.class,
() -> DateUtils.setMonths(BASE_DATE, 12),
- "DateUtils.setMonths did not throw an expected IllegalArgumentException.");
+ outsideOfRangeAssertionMessage);
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> DateUtils.setMonths(BASE_DATE, -1),
+ outsideOfRangeAssertionMessage);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.setMonths(null, 0));
}
// -----------------------------------------------------------------------
@@ -1280,10 +1336,17 @@ public class DateUtilsTest {
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2000, 6, 5, 4, 3, 59, 1);
+ final String outsideOfRangeAssertionMessage = "DateUtils.setSeconds did not throw an expected IllegalArgumentException for amount outside of range 0 to 59.";
assertThrows(
IllegalArgumentException.class,
() -> DateUtils.setSeconds(BASE_DATE, 60),
- "DateUtils.setSeconds did not throw an expected IllegalArgumentException.");
+ outsideOfRangeAssertionMessage);
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> DateUtils.setSeconds(BASE_DATE, -1),
+ outsideOfRangeAssertionMessage);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.setSeconds(null, 0));
}
// -----------------------------------------------------------------------
@@ -1303,6 +1366,8 @@ public class DateUtilsTest {
assertNotSame(BASE_DATE, result);
assertDate(BASE_DATE, 2000, 6, 5, 4, 3, 2, 1);
assertDate(result, 2005, 6, 5, 4, 3, 2, 1);
+
+ assertThrows(NullPointerException.class, () -> DateUtils.setYears(null, 0));
}
@Test