Package com.tngtech.archunit.library.modules

Class ArchModules<DESCRIPTOR extends ArchModule.Descriptor>

java.lang.Object

com.tngtech.archunit.base.ForwardingCollection<ArchModule<DESCRIPTOR>>

com.tngtech.archunit.library.modules.ArchModules<DESCRIPTOR>

All Implemented Interfaces:

Iterable<ArchModule<DESCRIPTOR>>, Collection<ArchModule<DESCRIPTOR>>

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public final class ArchModules<DESCRIPTOR extends ArchModule.Descriptor>
extends ForwardingCollection<ArchModule<DESCRIPTOR>>

A collection of "architectural modules". This class provides a convenient API to partition the classes of a code base into (cohesive) modules and assert properties of these modules, e.g. their dependencies to each other or dependencies not contained in any of the constructed modules.
This class provides several entry points to create modules from a set of classes:

• defineBy(IdentifierAssociation) - the most generic/flexible API
• defineByPackages(String) - an API similar to Slices.matching(String)
• defineByRootClasses(Predicate) - an API that derives modules from the packages of some specific classes
• defineByAnnotation(Class) - a convenience API for defineByRootClasses(Predicate) that picks the relevant classes by looking for an annotation

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ArchModules.Creator	An element of the fluent API to create ArchModules
static class	ArchModules.CreatorByRootClass	An element of the fluent API to create ArchModules
static interface	ArchModules.DescriptorCreator<DESCRIPTOR extends ArchModule.Descriptor>	A generic interface to be extended by users for providing custom implementations of ArchModule.Descriptor that can carry along more meta-information from the modularized JavaClasses.
static interface	ArchModules.IdentifierAssociation	Defines which classes belong to the same ArchModule.Identifier and thus will eventually end up in the same ArchModule.
static interface	ArchModules.RootClassDescriptorCreator<DESCRIPTOR extends ArchModule.Descriptor>	A more convenient ArchModules.DescriptorCreator tailored to the case that we define our modules by root classes.

Method Summary

Modifier and Type	Method	Description
static ArchModules.Creator	defineBy(ArchModules.IdentifierAssociation identifierFunction)	Entrypoint to create ArchModules by a generic mapping function JavaClass -> ArchModule.Identifier.
static <A extends Annotation> ArchModules.Creator.WithGenericDescriptor<AnnotationDescriptor<A>>	defineByAnnotation(Class<A> annotationType)	Same as defineByAnnotation(Class, Function), but the name will be automatically derived from the name attribute of the respective annotation.
static <A extends Annotation> ArchModules.Creator.WithGenericDescriptor<AnnotationDescriptor<A>>	defineByAnnotation(Class<A> annotationType, Function<A,String> nameFunction)	Entrypoint to create ArchModules by partitioning a set of classes into packages defined by "root classes" containing annotations of the given annotationType.
static ArchModules.Creator	defineByPackages(String packageIdentifier)	Entrypoint to create ArchModules by partitioning a set of classes into specific packages matching the supplied packageIdentifier interpreted as PackageMatcher. Partitioning is done according to capturing groups.
static ArchModules.CreatorByRootClass	defineByRootClasses(Predicate<? super JavaClass> rootClassPredicate)	Entrypoint to create ArchModules by partitioning a set of classes into packages defined by specific "root classes".
protected Collection<ArchModule<DESCRIPTOR>>	delegate()
ArchModule<DESCRIPTOR>	getByIdentifier(String... identifier)
ArchModule<DESCRIPTOR>	getByName(String name)
Set<String>	getNames()
Optional<ArchModule<DESCRIPTOR>>	tryGetByIdentifier(String... identifier)
Optional<ArchModule<DESCRIPTOR>>	tryGetByName(String name)

Methods inherited from class com.tngtech.archunit.base.ForwardingCollection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, removeIf, spliterator, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Method Details

delegate

protected Collection<ArchModule<DESCRIPTOR>> delegate()

Specified by:

delegate in class ForwardingCollection<ArchModule<DESCRIPTOR extends ArchModule.Descriptor>>

getByIdentifier

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public ArchModule<DESCRIPTOR> getByIdentifier(String... identifier)

Parameters:

identifier - The (textual) parts of an ArchModule.Identifier.

Returns:

The contained ArchModule having an ArchModule.Identifier comprised of the passed identifier parts. This method will throw an exception if no matching ArchModule is contained.

tryGetByIdentifier

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public Optional<ArchModule<DESCRIPTOR>> tryGetByIdentifier(String... identifier)

Parameters:

identifier - The (textual) parts of an ArchModule.Identifier.

Returns:

The contained ArchModule having an ArchModule.Identifier comprised of the passed identifier parts, or Optional.empty() if no matching ArchModule is contained.

getByName

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public ArchModule<DESCRIPTOR> getByName(String name)

Parameters:

name - The name of an ArchModule

Returns:

A contained ArchModule with the passed name. This method will throw an exception if no matching ArchModule is contained.

See Also:

• tryGetByName(String)

tryGetByName

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public Optional<ArchModule<DESCRIPTOR>> tryGetByName(String name)

Parameters:

name - The name of an ArchModule

Returns:

A contained ArchModule with the passed name, or Optional.empty() if no matching ArchModule is contained.

See Also:

• getByName(String)

getNames

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public Set<String> getNames()

Returns:

The names of all modules contained within these ArchModules

defineByPackages

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public static ArchModules.Creator defineByPackages(String packageIdentifier)

Entrypoint to create ArchModules by partitioning a set of classes into specific packages matching the supplied packageIdentifier interpreted as PackageMatcher.
Partitioning is done according to capturing groups. For example

Suppose there are three classes:

com.example.module.one.SomeClass
com.example.module.one.AnotherClass
com.example.module.two.YetAnotherClass

If modules are created by specifying

ArchModules.defineByPackages("..module.(*)..").modularize(javaClasses)

then the result will be two modules, the module where the capturing group is 'one' and the module where the capturing group is 'two'. The first module will have an ArchModule.Identifier consisting of the single string "one", while the latter will have an ArchModule.Identifier consisting of the single string "two". If multiple packages would be matched, e.g. by "..module.(*).(*)..", the respective ArchModule.Identifier would contain the two matched (sub-)package names as its parts.

Parameters:

packageIdentifier - A package identifier

Returns:

A fluent API to further customize how to create ArchModules

defineByRootClasses

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public static ArchModules.CreatorByRootClass defineByRootClasses(Predicate<? super JavaClass> rootClassPredicate)

Entrypoint to create ArchModules by partitioning a set of classes into packages defined by specific "root classes". The rootClassPredicate will determine which classes are root classes. ArchModules are formed by grouping together all classes that reside in the same package or a subpackage of the respective root class. Thus, the packages of the defined root classes may not overlap, i.e. no root class must reside in the same or a subpackage of another root class. All classes not contained in any package induced by a root class will be ignored from the derived ArchModules.

Take for example the following three classes:

com.example.module.one.SomeClass
com.example.module.one.AnotherClass
com.example.module.two.SomeOtherClass

Then the rootClassPredicate

 javaClass -> javaClass.getSimpleName().startsWith("Some")
 

would pick the classes SomeClass and SomeOtherClass and derive the ArchModules from their packages, which in turn would put SomeClass and AnotherClass in the same ArchModule derived from SomeClass.

Parameters:

rootClassPredicate - A Predicate determining which JavaClass is a "root class", thus defining a ArchModule by its package

Returns:

A fluent API to further customize how to create ArchModules

defineByAnnotation

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public static <A extends Annotation>
ArchModules.Creator.WithGenericDescriptor<AnnotationDescriptor<A>> defineByAnnotation(Class<A> annotationType)

Same as defineByAnnotation(Class, Function), but the name will be automatically derived from the name attribute of the respective annotation. I.e. to use this method the respective annotation must provide a name like in the following example:

@SomeExample(name = "Example Module")
 class SomeClass {}
 

In case the respective annotationType doesn't offer a name attribute like this please refer to defineByAnnotation(Class, Function) instead.

defineByAnnotation

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public static <A extends Annotation>
ArchModules.Creator.WithGenericDescriptor<AnnotationDescriptor<A>> defineByAnnotation(Class<A> annotationType,
 Function<A,String> nameFunction)

Entrypoint to create ArchModules by partitioning a set of classes into packages defined by "root classes" containing annotations of the given annotationType. This is basically a convenience function for defineByRootClasses(Predicate) where the Predicate exactly identifies classes carrying the passed annotationType and the annotation will be carried forward into the derived ArchModules by the derived AnnotationDescriptor.

Take for example the following three classes:

@SomeAnnotation com.example.module.one.SomeClass
com.example.module.one.AnotherClass
@SomeAnnotation com.example.module.two.YetAnotherClass

Then

 ArchModules.defineByAnnotation(SomeAnnotation.class).modularize(javaClasses)
 

would pick the classes SomeClass and YetAnotherClass, since they are annotated with SomeAnnotation, and derive the ArchModules from their packages. This in turn would put SomeClass and AnotherClass in the same ArchModule derived from SomeClass. The final ArchModule would have a descriptor of type AnnotationDescriptor from which the specific Annotation (i.e. instance of @SomeAnnotation) on SomeClass or YetAnotherClass could be obtained.
As with defineByRootClasses(Predicate) users of this method must make sure that packages of the classes annotated with the given annotationType don't overlap.

Parameters:

annotationType - The type of Annotation defining which JavaClass is a root class

nameFunction - A function determining how to derive the module name from the respective annotation

Returns:

A fluent API to further customize how to create ArchModules

defineBy

@PublicAPI(usage=ACCESS,
           state=EXPERIMENTAL)
public static ArchModules.Creator defineBy(ArchModules.IdentifierAssociation identifierFunction)

Entrypoint to create ArchModules by a generic mapping function JavaClass -> ArchModule.Identifier. All classes that are mapped to the same ArchModule.Identifier will end up in the same ArchModule.
A simple example would be the identifierFunction

 javaClass -> ArchModule.Identifier.from(javaClass.getPackageName())
 

This would then create one ArchModule for each full package name and each JavaClass would be contained in the ArchModule where the ArchModule.Identifier coincides with the class's full package name.

Parameters:

identifierFunction - A function defining how each JavaClass is mapped to the respective ArchModule.Identifier

Returns:

A fluent API to further customize how to create ArchModules