org.seedstack.business.specification.dsl.SpecificationBuilder Maven / Gradle / Ivy

Go to download
/*
 * Copyright © 2013-2024, The SeedStack authors 
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */
package org.seedstack.business.specification.dsl;

import org.seedstack.business.domain.AggregateRoot;
import org.seedstack.business.specification.Specification;

/**
 * SpecificationBuilder is a DSL that facilitates the creation of complex composite specifications.
 * It relies on expressing boolean predicates in the disjunctive normal form, which is a disjunction
 * (OR) of conjunctive clauses (AND). In other words it requires that the predicates are expressed
 * as an OR clause of AND clauses.
 *
 *  Examples of formulae in DNF: 
  (A ∧ ¬B ∧ ¬C) ∨ (¬D ∧ E ∧ F)
 (A ∧ B) ∨
 * C
 A ∧ B
 A ∨ B
 A
 
 */
public interface SpecificationBuilder {

    /**
     * Starts the building of a composite specification that applies on any type.
     *
     * @param anyClass the class the specification applies to.
     * @param       the type of the object the specification applies to.
     * @param       the type of the selector.
     * @return the next operation of the builder DSL, allowing to select all or a part of the object
     * the specification will apply to.
     */
    > S of(Class anyClass);

    /**
     * Starts the building of a composite specification that applies on any {@link AggregateRoot}.
     *
     * @param aggregateClass the aggregate class the specification applies to.
     * @param             the type of the aggregate the specification applies to.
     * @param             the type of the identifier of the aggregate.
     * @param             the type of the selector.
     * @return the next operation of the builder DSL, allowing to select all or a part of the object
     * the specification will apply to.
     */
    , I, S extends AggregateSelector> S ofAggregate(Class aggregateClass);

    /**
     * Starts the building of a composite specification from an existing one. Expression 'of(someSpec)' is
     * a equivalent 'of(SomeClass.class).whole().satisfying(someSpec)'.
     *
     * @param anySpec the existing specification to base the new specification on.
     * @param      the type of the object the specification applies to.
     * @param      the type of the selector.
     * @return the next operation of the builder DSL, allowing to select all or a part of the object
     * the specification will apply to.
     */
    > OperatorPicker satisfying(Specification anySpec);
}