some javadoc; some new methods in packers

Author: terzerm

src/main/java/org/tools4j/time/pack/DatePacker.java

@@ -32,33 +32,85 @@
 import java.util.Objects;
 
 import static org.tools4j.time.base.Allocation.Type.RESULT;
+import static org.tools4j.time.validate.DateValidator.isValidDate;
 
 /**
  * Packs a date (year, month, day) into an integer.  Packing and unpacking can be done with or without date validation
- * using different {@link #validationMethod() validation methods}.  A {@link #DECIMAL} and a {@link #BINARY} packing is
- * supported and both packings preserve the natural date ordering, that is, if the packed integers are sorted then the
- * corresponding dates are also sorted.  Packing and unpacking of null values is supported via {@link #packNull()} and
- * {@link #unpackNull(int)}.
+ * using different {@linkplain #validationMethod() validation methods}.  A {@linkplain #DECIMAL} and a
+ * {@linkplain #BINARY} packing is supported and both packings preserve the natural date ordering, that is, if the
+ * packed integers are sorted then the corresponding dates are also sorted.  Packing and unpacking of null values is
+ * supported via {@link #packNull()} and {@link #unpackNull(int)}.
  * <p>
  * <i>Examples:</i>
  * <ul>
- *     <li>{@link #DECIMAL} packing for a date 21-Jan-2017 is 20170121</li>
- *     <li>{@link #BINARY} packing uses shifts to pack the date parts which is more efficient but the result is not
+ *     <li>{@linkplain #DECIMAL} packing for a date 21-Jan-2017 is 20170121</li>
+ *     <li>{@linkplain #BINARY} packing uses shifts to pack the date parts which is more efficient but the result is not
  *     easily human-readable</li>
  * </ul>
  * @see #valueOf(Packing, ValidationMethod)
  * @see #BINARY
  * @see #DECIMAL
  */
 public interface DatePacker {
+    /**
+     * Value returned from pack methods for invalid date inputs if
+     * {@linkplain ValidationMethod#INVALIDATE_RESULT INVALIDATE_RESULT}
+     * {@linkplain #validationMethod() validation method} is in use.
+     */
     int INVALID = -1;
+    /** Value returned by {@link #packNull()} and from {@link #pack(LocalDate)} for null values. */
     int NULL = 0;
 
+    /**
+     * Returns {@linkplain Packing#DECIMAL DECIMAL} or {@linkplain Packing#BINARY BINARY} packing type.
+     *
+     * @return the packing type
+     */
     Packing packing();
+
+    /**
+     * Returns {@linkplain ValidationMethod validation method} used by this packer instance.
+     *
+     * @return the method used to validate dates
+     */
     ValidationMethod validationMethod();
+
+    /**
+     * Returns the packer instance with the same {@linkplain #packing() packing} type as {@code this} packer but using
+     * the specified {@linkplain ValidationMethod validation method} to validate dates.
+     *
+     * @param validationMethod the validation method used by the returned packer to validate dates
+     * @return the instance with packing type inherited from this packer and validation method as specified
+     */
     DatePacker forValidationMethod(ValidationMethod validationMethod);
+
+    /**
+     * Packs the given year, month and day value into an int and returns it.
+     * @param year  the four digit year such as 2017
+     * @param month the month value from 1 to 12
+     * @param day   the day of the month from 1 to no more than 31
+     * @return  the packed date value, or {@linkplain #INVALID} if the date is invalid and
+     *          {@linkplain ValidationMethod#INVALIDATE_RESULT INVALIDATE_RESULT}
+     *          {@linkplain #validationMethod() validation method} is in use
+     * @throws java.time.DateTimeException  if the specified date is invalid and
+     *                                      {@linkplain ValidationMethod#THROW_EXCEPTION THROW_EXCEPTION}
+     *                                      {@linkplain #validationMethod() validation method} is in use
+     */
     int pack(int year, int month, int day);
-    int pack(long packedDateTime, Packing packing);
+
+    /**
+     * Re-packs the date from specified packed date/time value and returns it.
+     * @param packedDateTime    the packed date/time value
+     * @param packing           the packing type of the date/time value
+     * @return  the packed date value, or {@linkplain #INVALID} if the date is invalid and
+     *          {@linkplain ValidationMethod#INVALIDATE_RESULT INVALIDATE_RESULT}
+     *          {@linkplain #validationMethod() validation method} is in use
+     * @throws java.time.DateTimeException  if the specified date is invalid and
+     *                                      {@linkplain ValidationMethod#THROW_EXCEPTION THROW_EXCEPTION}
+     *                                      {@linkplain #validationMethod() validation method} is in use
+     */
+    int packFromDateTime(long packedDateTime, Packing packing);
+    int packFromDate(int packedDate, Packing packing);
     int unpackYear(int packed);
     int unpackMonth(int packed);
     int unpackDay(int packed);
@@ -72,6 +124,10 @@ public interface DatePacker {
     int packEpochMilli(long millisSinceEpoch);
     long unpackEpochMilli(int packed);
 
+    boolean isValid(int packed);
+    int validate(int packed);
+    int validate(int packed, ValidationMethod validationMethod);
+
     /**
      * Returns a date packer that performs no validation.
      * @param packing the packing type for the returned packer
@@ -113,7 +169,7 @@ default int pack(final LocalDate localDate) {
         }
 
         @Override
-        default int pack(final long packedDateTime, final Packing packing) {
+        default int packFromDateTime(final long packedDateTime, final Packing packing) {
             final DateTimePacker unpacker = DateTimePacker.valueOf(packing, validationMethod());
             return pack(
                     unpacker.unpackYear(packedDateTime),
@@ -122,6 +178,15 @@ default int pack(final long packedDateTime, final Packing packing) {
             );
         }
 
+        @Override
+        default int packFromDate(final int packedDate, final Packing packing) {
+            if (packing == packing() && validationMethod() == ValidationMethod.UNVALIDATED) {
+                return packedDate;
+            }
+            final DatePacker dp = DatePacker.valueOf(packing, validationMethod());
+            return pack(dp.unpackYear(packedDate), dp.unpackMonth(packedDate), dp.unpackMonth(packedDate));
+        }
+
         @Override
         @Allocation(RESULT)
         default LocalDate unpackLocalDate(final int packed) {
@@ -150,6 +215,27 @@ default long unpackEpochMilli(final int packed) {
             return Epoch.valueOf(validationMethod()).toEpochMilli(packed, this);
         }
 
+        @Override
+        default boolean isValid(final int packed) {
+            return packed != INVALID && (packed == NULL || isValidDate(unpackDay(packed), unpackMonth(packed), unpackDay(packed)));
+        }
+
+        @Override
+        default int validate(final int packed) {
+            return validate(packed, validationMethod());
+        }
+
+        @Override
+        default int validate(final int packed, final ValidationMethod validationMethod) {
+            if (packed == NULL || packed == INVALID || validationMethod == ValidationMethod.UNVALIDATED) {
+                return packed;
+            }
+            final DateValidator dateValidator = validationMethod.dateValidator();
+            return dateValidator.validateDay(
+                    unpackYear(packed), unpackMonth(packed), unpackDay(packed)
+            ) != DateValidator.INVALID ? packed : INVALID;
+        }
+
         @Override
         default DatePacker forValidationMethod(final ValidationMethod validationMethod) {
             return valueOf(packing(), validationMethod);

src/main/java/org/tools4j/time/pack/DateTimePacker.java

@@ -37,19 +37,21 @@
 import static org.tools4j.time.base.Allocation.Type.RESULT;
 import static org.tools4j.time.base.TimeFactors.MILLIS_PER_SECOND;
 import static org.tools4j.time.base.TimeFactors.NANOS_PER_MILLI;
+import static org.tools4j.time.validate.DateValidator.isValidDate;
+import static org.tools4j.time.validate.TimeValidator.isValidTimeWithMillis;
 
 /**
  * Packs a date/time value (year, month, day, hour, minute, second, millis) into a single long.  Packing and unpacking
- * can be done with or without date/time validation using different {@link #validationMethod() validation methods}.
- * A {@link #DECIMAL} and a {@link #BINARY} packing is supported and both packings preserve the natural date ordering,
- * that is, if the packed longs are sorted then the corresponding date/time values are also sorted.  Packing and
- * unpacking of null values is supported via {@link #packNull()} and {@link #unpackNull(long)}.
+ * can be done with or without date/time validation using different {@linkplain #validationMethod() validation methods}.
+ * A {@linkplain #DECIMAL} and a {@linkplain #BINARY} packing is supported and both packings preserve the natural date
+ * ordering, that is, if the packed longs are sorted then the corresponding date/time values are also sorted.  Packing
+ * and unpacking of null values is supported via {@link #packNull()} and {@link #unpackNull(long)}.
  * <p>
  * <i>Examples:</i>
  * <ul>
- *     <li>{@link #DECIMAL} packing for a date/time value 21-Jan-2017 14:15:16.170 is 20170121141516170</li>
- *     <li>{@link #BINARY} packing uses shifts to pack the date/time parts which is more efficient but the result is not
- *     easily human-readable</li>
+ *     <li>{@linkplain #DECIMAL} packing for a date/time value 21-Jan-2017 14:15:16.170 is 20170121141516170</li>
+ *     <li>{@linkplain #BINARY} packing uses shifts to pack the date/time parts which is more efficient but the result
+ *     is not easily human-readable</li>
  * </ul>
  * @see #valueOf(Packing, ValidationMethod)
  * @see #BINARY
@@ -64,8 +66,9 @@ public interface DateTimePacker {
     long pack(int year, int month, int day);
     long pack(int year, int month, int day, int hour, int minute, int second);
     long pack(int year, int month, int day, int hour, int minute, int second, int milli);
-    long pack(int packedDate, Packing datePacking, int packedTime, TimePacker timePacker);
-    long pack(int packedDate, Packing datePacking, int packedMilliTime, MilliTimePacker milliTimePacker);
+    long packFromDateAndTime(int packedDate, Packing datePacking, int packedTime, Packing timePacking);
+    long packFromDateAndMilliTime(int packedDate, Packing datePacking, int packedMilliTime, Packing milliTimePacking);
+    long packFromDateTime(long packedDateTime, Packing dateTimePacking);
     int unpackYear(long packed);
     int unpackMonth(long packed);
     int unpackDay(long packed);
@@ -82,6 +85,10 @@ public interface DateTimePacker {
     long packEpochMilli(long millisSinceEpoch);
     long unpackEpochMilli(long packed);
 
+    boolean isValid(long packed);
+    long validate(long packed);
+    long validate(long packed, ValidationMethod validationMethod);
+
     /**
      * Returns a date/time packer that performs no validation.
      * @param packing the packing type for the returned packer
@@ -127,23 +134,38 @@ default long pack(final int year, final int month, final int day,
         }
 
         @Override
-        default long pack(final int packedDate, final Packing datePacking,
-                          final int packedTime, final TimePacker timePacker) {
-            final DatePacker datePacker = DatePacker.valueOf(datePacking, validationMethod());
+        default long packFromDateAndTime(final int packedDate, final Packing datePacking,
+                                         final int packedTime, final Packing timePacking) {
+            final DatePacker dp = DatePacker.valueOf(datePacking, validationMethod());
+            final TimePacker tp = TimePacker.valueOf(timePacking, validationMethod());
             return pack(
-                    datePacker.unpackYear(packedDate), datePacker.unpackMonth(packedDate), datePacker.unpackDay(packedDate),
-                    timePacker.unpackHour(packedTime), timePacker.unpackMinute(packedTime), timePacker.unpackSecond(packedTime)
+                    dp.unpackYear(packedDate), dp.unpackMonth(packedDate), dp.unpackDay(packedDate),
+                    tp.unpackHour(packedTime), tp.unpackMinute(packedTime), tp.unpackSecond(packedTime)
             );
         }
 
         @Override
-        default long pack(final int packedDate, final Packing datePacking,
-                          final int packedMilliTime, final MilliTimePacker milliTimePacker) {
-            final DatePacker datePacker = DatePacker.valueOf(datePacking, validationMethod());
+        default long packFromDateAndMilliTime(final int packedDate, final Packing datePacking,
+                                              final int packedMilliTime, final Packing milliTimePacking) {
+            final DatePacker dp = DatePacker.valueOf(datePacking, validationMethod());
+            final MilliTimePacker mtp = MilliTimePacker.valueOf(milliTimePacking, validationMethod());
             return pack(
-                    datePacker.unpackYear(packedDate), datePacker.unpackMonth(packedDate), datePacker.unpackDay(packedDate),
-                    milliTimePacker.unpackHour(packedMilliTime), milliTimePacker.unpackMinute(packedMilliTime),
-                    milliTimePacker.unpackSecond(packedMilliTime), milliTimePacker.unpackMilli(packedMilliTime)
+                    dp.unpackYear(packedDate), dp.unpackMonth(packedDate), dp.unpackDay(packedDate),
+                    mtp.unpackHour(packedMilliTime), mtp.unpackMinute(packedMilliTime),
+                    mtp.unpackSecond(packedMilliTime), mtp.unpackMilli(packedMilliTime)
+            );
+        }
+
+        @Override
+        default long packFromDateTime(final long packedDateTime, final Packing dateTimePacking) {
+            if (dateTimePacking == packing() && validationMethod() == ValidationMethod.UNVALIDATED) {
+                return packedDateTime;
+            }
+            final DateTimePacker dtp = DateTimePacker.valueOf(dateTimePacking, validationMethod());
+            return pack(
+                    dtp.unpackYear(packedDateTime), dtp.unpackMonth(packedDateTime), dtp.unpackDay(packedDateTime),
+                    dtp.unpackHour(packedDateTime), dtp.unpackMinute(packedDateTime),
+                    dtp.unpackSecond(packedDateTime), dtp.unpackMilli(packedDateTime)
             );
         }
 
@@ -184,6 +206,33 @@ default long unpackEpochMilli(final long packed) {
             return Epoch.valueOf(validationMethod()).toEpochMilli(packed, this);
         }
 
+        @Override
+        default boolean isValid(final long packed) {
+            return packed != INVALID && (packed == NULL || (
+                    isValidDate(unpackDay(packed), unpackMonth(packed), unpackDay(packed)) &&
+                    isValidTimeWithMillis(unpackHour(packed), unpackMinute(packed), unpackSecond(packed), unpackMilli(packed)))
+            );
+        }
+
+        @Override
+        default long validate(final long packed) {
+            return validate(packed, validationMethod());
+        }
+
+        @Override
+        default long validate(final long packed, final ValidationMethod validationMethod) {
+            if (packed == NULL || packed == INVALID || validationMethod == ValidationMethod.UNVALIDATED) {
+                return packed;
+            }
+            final DateValidator dv = validationMethod.dateValidator();
+            final TimeValidator tv = validationMethod.timeValidator();
+            return dv.validateDay(
+                    unpackYear(packed), unpackMonth(packed), unpackDay(packed)
+            ) != DateValidator.INVALID && tv.validateTimeWithMillis(
+                    unpackHour(packed), unpackMinute(packed), unpackSecond(packed), unpackMilli(packed)
+            ) != TimeValidator.INVALID ? packed : INVALID;
+        }
+
         @Override
         default DateTimePacker forValidationMethod(final ValidationMethod validationMethod) {
             return valueOf(packing(), validationMethod);