net.sourceforge.domian.specification
Interface Specification<T>

All Known Subinterfaces:

CompositeSpecification<T>, LeafSpecification<T>, ValueBoundSpecification<T>

public interface Specification<T>

Part of the Evans/Fowler Specifications pattern.

Note on type parameterization:
Domian specifications are typed. It is only relevant to send candidate objects of correct type to a Specification for approval. Generics should be used when creating specifications, making this specification type vs. candidate type a compile-time issue.

Since:

0.1

Author:

Eirik Torske

See Also:

The Specifications Pattern

Method Summary

CompositeSpecification<T>	and(Specification<? super T> otherSpecification) Creates a conjunction of two specifications: This composite specification A parameterized specification based on the java.lang.reflect.AccessibleObject name parameter and the accompanying specification parameter
java.lang.Class<T>	getType()
java.lang.Boolean	isDisjointWith(Specification<?> otherSpecification) Two specifications are disjoint if the two sets of satisfiable objects have no objects in common.
java.lang.Boolean	isGeneralizationOf(Specification<? extends T> otherSpecification) Specification subsumption.
java.lang.Boolean	isSatisfiedBy(T candidate) Specification satisfaction.
java.lang.Boolean	isSpecialCaseOf(Specification<? super T> otherSpecification) Specification subsumption.
CompositeSpecification<T>	or(Specification<? super T> otherSpecification) Creates a disjunction out of two specifications: This composite specification The given specification parameter
<F> CompositeSpecification<T>	where(java.lang.String accessibleObjectName, Specification<F> accessibleObjectSpecification) Alias of and method.

Method Detail

where

<F> CompositeSpecification<T> where(java.lang.String accessibleObjectName,
                                    Specification<F> accessibleObjectSpecification)

Alias of and method.

Type Parameters:

F - the type of the accessible object to specify

Parameters:

accessibleObjectName - the name of the accessible object to specify

accessibleObjectSpecification - the specification coupled to the accessible object

Returns:

a conjunction of this specification and the accessible object specification

Throws:

java.lang.IllegalArgumentException - if any of the parameters are null

java.lang.UnsupportedOperationException - if this method is called twice in the overall specification expression (fluent interface constraint)

and

CompositeSpecification<T> and(Specification<? super T> otherSpecification)

Creates a conjunction of two specifications:

1. This composite specification
2. A parameterized specification based on the java.lang.reflect.AccessibleObject name parameter and the accompanying specification parameter

Parameters:

otherSpecification - the specification to combine with this specification

Returns:

a new composite specification: this specification AND the parameterized specification

Throws:

java.lang.IllegalArgumentException - if any of the parameters are null

java.lang.IllegalArgumentException - if the accessible object name is illegal

java.lang.IllegalArgumentException - if the type of the accessible object and the type of the specification are not compatible

java.lang.UnsupportedOperationException - if this method is not placed behind a where clause in the overall specification expression (fluent interface constraint)

or

CompositeSpecification<T> or(Specification<? super T> otherSpecification)

Creates a disjunction out of two specifications:

1. This composite specification
2. The given specification parameter

Parameters:

otherSpecification - the specification to combine with this specification

Returns:

a new composite specification: this specification OR the specification parameter

Throws:

java.lang.IllegalArgumentException - if the parameter is null

getType

java.lang.Class<T> getType()

Returns:

the specification type

isSatisfiedBy

java.lang.Boolean isSatisfiedBy(T candidate)

Specification satisfaction.

Parameters:

candidate - The candidate object

Returns:

true only if this specification is satisfied by/approves the given candidate (null is never approved)

isGeneralizationOf

java.lang.Boolean isGeneralizationOf(Specification<? extends T> otherSpecification)

Specification subsumption.

Given:

1. Set K consisting of candidates specified by specA : specA.isSatisfiedBy(candidate)
2. Set L consisting of candidates specified by specB : specB.isSatisfiedBy(candidate)

Then:
if specA.isGeneralizationOf(specB) => Set K contains Set L [Set K UNION Set L = Set K]

Parameters:

otherSpecification - The candidate specification

Returns:

true only if this specification is a generalization of the given candidate specification

Throws:

java.lang.IllegalArgumentException - if parameter is null

Since:

0.3

isSpecialCaseOf

java.lang.Boolean isSpecialCaseOf(Specification<? super T> otherSpecification)

Specification subsumption.

Given:

1. Set K consisting of candidates specified by specA : specA.isSatisfiedBy(candidate)
2. Set L consisting of candidates specified by specB : specB.isSatisfiedBy(candidate)

Then:
if specA.isSpecializationOf(specB) => Set L contains Set K [Set K UNION Set L = Set L]

Parameters:

otherSpecification - The candidate specification

Returns:

true only if this specification is a special case of the given candidate specification

Throws:

java.lang.IllegalArgumentException - if parameter is null

Since:

0.3

isDisjointWith

java.lang.Boolean isDisjointWith(Specification<?> otherSpecification)

Two specifications are disjoint if the two sets of satisfiable objects have no objects in common.

Parameters:

otherSpecification - The candidate specification

Returns:

true only if this specification is disjoint with the given candidate specification

Throws:

java.lang.IllegalArgumentException - if parameter is null

Since:

0.5