/**
 * The annotation {@link com.github.naoghuman.lib.validation.core.annotation.NewDuration} 
 * lets the developer verify if a given {@link java.time.LocalDateTime} is in the range 
 * from a {@link java.time.Duration} which starts with ({@link java.time.LocalDateTime#now()} 
 * - {@link com.github.naoghuman.lib.validation.core.annotation.NewDuration#days()}) and ends 
 * with {@link java.time.LocalDateTime#now()}.
 * <br>
 * If a given {@code LocalDateTime} is in the range then the validated entity can be flagged 
 * as {@code 'New'}.
 * <p>
 * For example given is:<br>
 * TODO
 * 
 * @author  Naoghuman
 * @since   0.2.0
 * @version 0.3.0
 * @see     java.time.Duration
 * @see     java.time.LocalDateTime
 * @see     java.time.LocalDateTime#now()
 */
@Target({ FIELD, LOCAL_VARIABLE })
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = NewDurationValidator.class)
public @interface NewDuration

/**
 * Returns the message key for the message if the validator verify that the 
 * checked {@link java.time.LocalDateTime} is in the range from the defined 
 * {@link java.time.Duration}.
 * <p>
 * The message for the key can be found in:<br>
 *  - {@code com.github.naoghuman.lib.validation.core.ValidationMessages.properties}
 * 
 * @author Naoghuman
 * @since  0.2.0
 * @return the message key.
 * @see    com.github.naoghuman.lib.validation.core.validator.NewDurationValidator
 * @see    java.time.Duration
 * @see    java.time.LocalDateTime
 */
public String message() default "{com.github.naoghuman.lib.validation.core.annotation.newduration.message}"; // NOI18N

/**
 * The attribute {@code groups} allows the specification of validation groups, 
 * to which this constraint belongs.
 * <p>
 * This must be default an empty array of type Class&lt;?&gt;.
 * 
 * @author Naoghuman
 * @since  0.2.0
 * @return the groups which should be validate.
 */
public Class<?>[] groups() default { };

/**
 * The attribute {@code payload} can be used by clients of the {@code Bean Validation API} 
 * to assign custom payload objects to a constraint. This attribute is not used by the API 
 * itself.
 * 
 * @author Naoghuman
 * @since  0.2.0
 * @return the payload which should be validate.
 */
public Class<? extends Payload>[] payload() default { };

/**
 * The attribute {@code days} defines the start-point from the {@link java.time.Duration} 
 * which is ({@link java.time.LocalDateTime#now()} - 
 * {@link com.github.naoghuman.lib.validation.core.annotation.NewDuration#days()}) and 
 * ends with {@link java.time.LocalDateTime#now()}.
 * <p>
 * Default value is {@code 3} days.
 * 
 * @author  Naoghuman
 * @since   0.2.0
 * @version 0.3.0
 * @return  the start-point from the {@code Duration} in days.
 * @see     java.time.Duration
 * @see     java.time.LocalDateTime#now()
 */
public int days() default 3;

/**
 * The annotation {@link com.github.naoghuman.lib.validation.core.annotation.UpdatedDuration} 
 * lets the developer verify if a given {@link java.time.LocalDateTime} is in the range 
 * from a {@link java.time.Duration} which starts with ({@link java.time.LocalDateTime#now()} 
 * - {@link com.github.naoghuman.lib.validation.core.annotation.UpdatedDuration#weeks()}) and 
 * ends with {@link java.time.LocalDateTime#now()}.
 * <br>
 * If a given {@code LocalDateTime} is in the range then the validated entity can be flagged 
 * as {@code 'Updated'}.
 * <p>
 * For example given is:<br>
 * TODO
 * 
 * @author Naoghuman
 * @since  0.3.0
 * @see    java.time.Duration
 * @see    java.time.LocalDateTime
 * @see    java.time.LocalDateTime#now()
 */
@Target({ FIELD, LOCAL_VARIABLE })
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = UpdatedDurationValidator.class)
public @interface UpdatedDuration

/**
 * Returns the message key for the message if 
 * {@link com.github.naoghuman.lib.validation.core.validator.UpdatedDurationValidator} 
 * verify that the checked {@link java.time.LocalDateTime} is in the defined 
 * {@link java.time.Duration}.
 * <p>
 * The message for the key can be found in:<br>
 *  - {@code com.github.naoghuman.lib.validation.core.ValidationMessages.properties}
 * 
 * @author Naoghuman
 * @since  0.3.0
 * @return the message key.
 * @see    com.github.naoghuman.lib.validation.core.validator.UpdatedDurationValidator
 * @see    java.time.Duration
 * @see    java.time.LocalDateTime
 */
public String message() default "{com.github.naoghuman.lib.validation.core.annotation.updatedduration.message}"; // NOI18N

/**
 * The attribute {@code groups} allows the specification of validation groups, 
 * to which this constraint belongs.
 * <p>
 * This must be default an empty array of type Class&lt;?&gt;.
 * 
 * @author Naoghuman
 * @since  0.3.0
 * @return the groups which should be validate.
 */
public Class<?>[] groups() default { };

/**
 * The attribute {@code payload} can be used by clients of the {@code Bean Validation API} 
 * to assign custom payload objects to a constraint. This attribute is not used by the API 
 * itself.
 * 
 * @author Naoghuman
 * @since  0.3.0
 * @return the payload which should be validate.
 */
public Class<? extends Payload>[] payload() default { };

/**
 * The attribute {@code weeks} defines the start-point from the {@link java.time.Duration} 
 * which is ({@link java.time.LocalDateTime#now()} - 
 * {@link com.github.naoghuman.lib.validation.core.annotation.UpdatedDuration#weeks()}) and 
 * ends with {@link java.time.LocalDateTime#now()}.
 * <p>
 * Default value is {@code 4} weeks.
 * 
 * @author Naoghuman
 * @since  0.3.0
 * @return the start-point from the {@code Duration} in weeks.
 * @see    java.time.Duration
 * @see    java.time.LocalDateTime#now()
 */
public int weeks() default 4;

/**
 * The {@code validator} for the annotation {@link com.github.naoghuman.lib.validation.core.annotation.NewDuration}.
 * <p>
 * Returns {@code TRUE} if the to checked {@link java.time.LocalDateTime} is in the range from  
 * the defined {@link java.time.Duration} which starts with {@link java.time.LocalDateTime#now()} 
 * and ends with {@link com.github.naoghuman.lib.validation.core.annotation.NewDuration#days()}.
 *
 * @author Naoghuman
 * @since  0.2.0
 * @see    com.github.naoghuman.lib.validation.core.annotation.NewDuration
 * @see    com.github.naoghuman.lib.validation.core.annotation.NewDuration#days()
 * @see    java.time.Duration
 * @see    java.time.LocalDateTime
 */
public final class NewDurationValidator implements ConstraintValidator<NewDuration, LocalDateTime>

/**
 * The {@code Validator} for the annotation {@link com.github.naoghuman.lib.validation.core.annotation.UpdatedDuration}.
 * <p>
 * Returns {@code TRUE} if the to checked {@link java.time.LocalDateTime} is between 
 * the defined {@link java.time.Duration} which starts with {@link java.time.LocalDateTime#now()} 
 * and ends with {@link com.github.naoghuman.lib.validation.core.annotation.UpdatedDuration#weeks()}.
 *
 * @author Naoghuman
 * @since  0.3.0
 * @see    com.github.naoghuman.lib.validation.core.annotation.UpdatedDuration
 * @see    com.github.naoghuman.lib.validation.core.annotation.UpdatedDuration#weeks()
 * @see    java.time.Duration
 * @see    java.time.LocalDateTime
 * @see    java.time.LocalDateTime#now()
 */
public final class UpdatedDurationValidator implements ConstraintValidator<UpdatedDuration, LocalDateTime>

/**
 * Simple factory class which alloweds momentary to access an initialized instance 
 * from a {@link javax.validation.Validator} using the factory defaults for message 
 * interpolator, traversable resolver and constraint validator factory.
 * 
 * @author Naoghuman
 * @since  0.2.0
 * @see    javax.validation.Validator
 */
public final class ValidationFactory

private static final Optional<ValidationFactory> INSTANCE = Optional.of(new ValidationFactory());

    /**
 * Returns a singleton instance from the class {@code ValidationFactory}.
 *
 * @author Naoghuman
 * @since  0.2.0
 * @return a singleton instance from this class {@code ValidationFactory}.
 */
public static final ValidationFactory getDefault()

/**
 * Returns an initialized {@link Validator} instance using the
 * factory defaults for message interpolator, traversable resolver
 * and constraint validator factory.
 * <p>
 * Validator instances can be pooled and shared by the implementation.
 *
 * @author Naoghuman
 * @since  0.2.0
 * @return an initialized {@code Validator} instance.
 */
public Validator getValidator()

/**
 * This {@code Class} contains different methods to validate if an {@link java.lang.Object} 
 * conforms specific behaviours or not. For example if an {@code Object} is {@code NULL} or not.
 *
 * @author Naoghuman
 * @since  0.2.0
 * @see    java.lang.Object
 */
public final class PreConditionValidator

/**
 * Returns a singleton instance from the class {@code PreConditionValidator}.
 *
 * @author Naoghuman
 * @since  0.2.0
 * @return a singleton instance from this class {@code PreConditionValidator}.
 */
public static final PreConditionValidator getDefault()

/**
 * Returns {@code TRUE} if an annotation from the specified type is <em>present</em> 
 * on given class otherwise {@code FALSE}. This method is designed primarily for 
 * convenient access to marker annotations.
 * <p>
 * This method simple delegates to {@link java.lang.Class#isAnnotationPresent(java.lang.Class)}.
 * 
 * @author Naoghuman
 * @since  0.3.0
 * @param  annotation the Class object corresponding to the annotation type.
 * @param  classToCheck the object which should be checked if the given annotation 
 *         type is present on the instance or not.
 * @return {@code TRUE} if an annotation from the specified annotation type is 
 *         present on given instance otherwise {@code FALSE}.
 * @see    java.lang.Class#isAnnotationPresent(java.lang.Class)
 */
public boolean isAnnotationPresent(final Class<? extends Annotation> annotation, final Class classToCheck)

/**
 * Delegates to {@link java.util.Objects#isNull(java.lang.Object)}. Returns 
 * {@code TRUE} if the provided reference is {@code NULL} otherwise {@code FALSE}.
 * <p>
 * This method exists to be used as a {@link java.util.function.Predicate}, 
 * {@code filter(Objects::isNull)}.
 * 
 * @author Naoghuman
 * @since  0.2.0
 * @param  obj a reference which will be checked against {@code NULL}.
 * @return {@code TRUE} if the provided reference is {@code NULL} otherwise
 *         {@code FALSE}.
 */
public boolean isNull(final Object obj)

/**
 * Delegates to {@link java.util.Objects#nonNull(java.lang.Object)}. Returns 
 * {@code TRUE} if the provided reference is {@code NON-NULL} otherwise {@code FALSE}.
 * <p>
 * This method exists to be used as a {@link java.util.function.Predicate},
 * {@code filter(Objects::nonNull)}.
 * 
 * @author Naoghuman
 * @since  0.2.0
 * @param  obj a reference which will be checked against {@code NULL}.
 * @return {@code TRUE} if the provided reference is {@code NON-NULL} otherwise
 *         {@code FALSE}.
 */
public boolean nonNull(final Object obj)

/**
 * Validates if the attribute {@code value} isn't {@code NULL}.
 *
 * @author Naoghuman
 * @since  0.1.0
 * @param  value the attribute which should be validated.
 * @param  <T>   the type of the reference.
 * @throws NullPointerException if {@code (value == NULL)}.
 */
public <T> void requireNonNull(final T value) throws NullPointerException

/**
 * Validates if the attribute {@code value} isn't {@code NULL} and not {@code EMPTY}.
 *
 * @author Naoghuman
 * @since  0.1.0
 * @param  value the attribute which should be validated.
 * @throws NullPointerException     if {@code (value        == NULL)}.
 * @throws IllegalArgumentException if {@code (value.trim() == EMPTY)}.
 */
public void requireNonNullAndNotEmpty(final String value) throws NullPointerException, IllegalArgumentException