0
# Flink Architecture Tests Base
1

2
Flink Architecture Tests Base is a foundational Java library that provides common ArchUnit extensions and utilities for writing architectural rules to validate code structure, field properties, and class hierarchies in Apache Flink projects.
3

4
Built on top of ArchUnit, this library offers specialized predicates, conditions, and utilities designed specifically for architectural testing in large-scale Java projects, with particular focus on avoiding circular dependencies and maintaining clean architecture.
5

6
## Package Information
7

8
- **Package Name**: flink-architecture-tests-base
9
- **Package Type**: Maven
10
- **Language**: Java
11
- **Group ID**: org.apache.flink
12
- **Artifact ID**: flink-architecture-tests-base
13
- **Version**: 2.1.0
14
- **Installation**: Add to your Maven dependencies:
15

16
```xml
17
<dependency>
18
    <groupId>org.apache.flink</groupId>
19
    <artifactId>flink-architecture-tests-base</artifactId>
20
    <version>2.1.0</version>
21
    <scope>test</scope>
22
</dependency>
23
```
24

25
## Core Imports
26

27
```java
28
import org.apache.flink.architecture.common.Predicates;
29
import org.apache.flink.architecture.common.JavaFieldPredicates;
30
import org.apache.flink.architecture.common.Conditions;
31
import org.apache.flink.architecture.common.GivenJavaClasses;
32
import org.apache.flink.architecture.common.ImportOptions;
33
import org.apache.flink.architecture.common.SourcePredicates;
34
```
35

36
## Basic Usage
37

38
```java
39
import com.tngtech.archunit.core.domain.JavaClasses;
40
import com.tngtech.archunit.core.importer.ClassFileImporter;
41
import com.tngtech.archunit.lang.ArchRule;
42
import org.apache.flink.architecture.common.GivenJavaClasses;
43
import org.apache.flink.architecture.common.ImportOptions;
44
import org.apache.flink.architecture.common.Predicates;
45

46
// Import classes with filtering
47
JavaClasses classes = new ClassFileImporter()
48
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
49
    .withImportOption(new ImportOptions.ExcludeShadedImportOption())
50
    .importPackages("org.apache.flink");
51

52
// Create architecture rules using Java-only class filtering
53
ArchRule publicConstantsRule = GivenJavaClasses.javaClassesThat()
54
    .areNotEnums()
55
    .should()
56
    .onlyAccessClassesThat(
57
        Predicates.areDirectlyAnnotatedWithAtLeastOneOf(Component.class)
58
    );
59

60
// Test field properties
61
ArchRule publicStaticFinalFieldsRule = GivenJavaClasses.javaClassesThat()
62
    .containAnyFieldsThat(
63
        Predicates.arePublicStaticFinalOfType("java.lang.String")
64
    )
65
    .should()
66
    .onlyHavePublicStaticFinalFields();
67

68
// Validate the rules
69
publicConstantsRule.check(classes);
70
publicStaticFinalFieldsRule.check(classes);
71
```
72

73
## Architecture
74

75
Flink Architecture Tests Base is organized around several key components:
76

77
- **Predicate System**: Composable predicates for analyzing classes, fields, and relationships
78
- **Condition Framework**: ArchUnit conditions for validating method signatures and types
79
- **Import Filtering**: Specialized import options for excluding non-Java code and shaded dependencies
80
- **Type Safety**: Strong emphasis on using fully qualified class names to avoid circular dependencies
81
- **Java Focus**: Special handling to work exclusively with Java classes, filtering out Scala code
82

83
## Capabilities
84

85
### General Predicates
86

87
Core predicates for analyzing Java classes and fields, with support for annotation checking, field property validation, and class hierarchy inspection.
88

89
```java { .api }
90
public class Predicates {
91
    public static DescribedPredicate<JavaClass> areDirectlyAnnotatedWithAtLeastOneOf(
92
        Class<? extends Annotation>... annotations);
93
    public static DescribedPredicate<JavaClass> containAnyFieldsInClassHierarchyThat(
94
        DescribedPredicate<? super JavaField> predicate);
95
    public static DescribedPredicate<JavaField> arePublicStaticFinalOfType(String fqClassName);
96
}
97
```
98

99
[General Predicates](./general-predicates.md)
100

101
### Field Analysis
102

103
Specialized predicates focused exclusively on JavaField analysis, including modifier checking, type validation, and annotation detection.
104

105
```java { .api }
106
public class JavaFieldPredicates {
107
    public static DescribedPredicate<JavaField> isPublic();
108
    public static DescribedPredicate<JavaField> isStatic();
109
    public static DescribedPredicate<JavaField> isFinal();
110
    public static DescribedPredicate<JavaField> ofType(String fqClassName);
111
    public static DescribedPredicate<JavaField> annotatedWith(Class<? extends Annotation> annotationType);
112
}
113
```
114

115
[Field Analysis](./field-analysis.md)
116

117
### Method Validation
118

119
ArchUnit conditions for validating method signatures, including deep analysis of parameter types, return types, and exception types.
120

121
```java { .api }
122
public class Conditions {
123
    public static <T extends HasName> ArchCondition<T> fulfill(DescribedPredicate<T> predicate);
124
    public static ArchCondition<JavaMethod> haveLeafTypes(DescribedPredicate<JavaClass> typePredicate);
125
    public static ArchCondition<JavaMethod> haveLeafReturnTypes(DescribedPredicate<JavaClass> typePredicate);
126
}
127
```
128

129
[Method Validation](./method-validation.md)
130

131
### Import Control
132

133
ImportOption implementations for controlling which classes are analyzed during ArchUnit import, with specific support for Maven projects and mixed Java/Scala codebases.
134

135
```java { .api }
136
public class ImportOptions {
137
    public static final class MavenMainClassesOnly implements ImportOption;
138
    public static final class ExcludeScalaImportOption implements ImportOption;
139
    public static final class ExcludeShadedImportOption implements ImportOption;
140
}
141
```
142

143
[Import Control](./import-control.md)
144

145
### Java-Only Rules
146

147
Utility methods that provide Java-only equivalents of standard ArchUnit rule definitions, essential for mixed Java/Scala projects.
148

149
```java { .api }
150
public class GivenJavaClasses {
151
    public static ClassesThat<GivenClassesConjunction> javaClassesThat();
152
    public static GivenClassesConjunction javaClassesThat(DescribedPredicate<JavaClass> predicate);
153
    public static ClassesThat<GivenClassesConjunction> noJavaClassesThat();
154
}
155
```
156

157
[Java-Only Rules](./java-only-rules.md)
158

159
### Source Predicates
160

161
Source-based predicates for filtering Java classes by source file characteristics, essential for mixed Java/Scala projects.
162

163
```java { .api }
164
public class SourcePredicates {
165
    public static DescribedPredicate<JavaClass> areJavaClasses();
166
    static boolean isJavaClass(JavaClass clazz);
167
}
168
```
169

170
[Source Predicates](./source-predicates.md)