tech.sirwellington.alchemy.arguments.AssertionBuilder Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of alchemy-arguments Show documentation
Part of the Alchemy Collection. Easy, Simple, and Robust argument checking logic for your Services, Libraries, and Scripts.
There is a newer version: 2.3
Show newest version
/*
 * Copyright 2015 SirWellington Tech.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package tech.sirwellington.alchemy.arguments;

import tech.sirwellington.alchemy.annotations.arguments.NonEmpty;
import tech.sirwellington.alchemy.annotations.arguments.NonNull;
import tech.sirwellington.alchemy.annotations.designs.FluidAPIDesign;

/**
 * The {@link AssertionBuilder} allows compositions of rich argument checks.
 *
 *  *
 * {@code
 * checkThat(password)
 *      .usingMessage("Invalid Password")
 *      .is(notNull())
 *      .is(nonEmptyString())
 *      .is(stringIsAtLeastOfLength(10));
 * }
 *  
 * Alternatively using custom Exception Thrower:
 *
 *  * {@code
 * checkThat(password)
      .throwing(ex -> new BadRequestException("Bad Password", ex))
      .is(notNull())
      .is(nonEmptyString())
      .is(stringIsAtLeastOfLength(10));
 }
 * 
 *
 * With no {@link ExceptionMapper} provided, an
 * {@linkplain ExceptionMapper#IDENTITY identity mapper} is used.
 *
 * @param  The type of the argument being checked
 * @param        The type of {@link Exception} that will be thrown if the given assertion fails.
 *
 * @author SirWellington
 */
@FluidAPIDesign
public interface AssertionBuilder
{

    /**
     * Makes it easy to override the
     * {@linkplain FailedAssertionException#getMessage() error message} in the Exception thrown, in
     * case the argument fails the assertion.
     *
     * @param message
     *
     * @return
     */
    AssertionBuilder usingMessage(@NonEmpty String message);

    /**
     * Provide the behavior that responds to an argument failing an {@link AlchemyAssertion}. If the
     * provided {@code ExceptionMapper} returns null, no exception will be thrown, and it will be as
     * if the assertion was passed.
     *
     * @param 
     * @param exceptionMapper
     *
     * @return
     *
     * @see ExceptionMapper
     */
     AssertionBuilder throwing(@NonNull ExceptionMapper exceptionMapper);

    /**
     * This operation runs the specified assertion on the {@code Argument}. This operation is
     * chain-able, to allow for multiple assertions on a single argument.
     *
     * @param assertion The assertion to run throw the argument. Must be non-null.
     *
     * @return
     *
     * @throws Ex Throws the desired exception if the assertion fails.
     */
    AssertionBuilder is(@NonNull AlchemyAssertion assertion) throws Ex;

    /**
     * Grammatical sugar in case multiple arguments are used.
     * 

     * It reads better to say
     *      *  checkThat(first, second, third)
     *      .are(notEmpty());
     *  than to say
     *      * checkThat(first, second, third)
     *      .is(notEmpty());
     *  but the result is the same.
     *
     * @param assertion
     * @return
     * @throws Ex
     */
    default AssertionBuilder are(@NonNull AlchemyAssertion assertion) throws Ex
    {
        return is(assertion);
    }

    /**
     * This is an alternate way to specify an Exception, using instead a class. The library will
     * create the exception instances for you, provided that the exception followed the common Java
     * Exception constructor convention. See {@link IllegalArgumentException} for an example of a
     * common Exception.
     *
     * @param            The type of the Exception that will be thrown.
     * @param exceptionClass The class of the Exception that will be thrown. Must be non-null.
     *
     * @return
     */
    default  AssertionBuilder throwing(@NonNull Class exceptionClass)
    {
        return AssertionBuilder.this.throwing(new DynamicExceptionSupplier<>(exceptionClass, ""));
    }

}