0
# Import Control
1

2
ImportOption implementations for controlling which classes are analyzed during ArchUnit import. These options provide essential filtering capabilities for Maven projects and mixed Java/Scala codebases, helping manage memory consumption and focus analysis on relevant code.
3

4
## Capabilities
5

6
### Maven Project Filtering
7

8
Only imports class files from Maven main classes target directory, excluding test classes and other build artifacts.
9

10
```java { .api }
11
/**
12
 * ImportOption that only includes class files from Maven main classes target directory
13
 * Pattern: .*/target/classes/.*
14
 */
15
public static final class MavenMainClassesOnly implements ImportOption {
16
    public boolean includes(Location location);
17
}
18
```
19

20
**Usage Example:**
21

22
```java
23
import org.apache.flink.architecture.common.ImportOptions;
24
import com.tngtech.archunit.core.importer.ClassFileImporter;
25

26
// Import only main classes, excluding tests
27
JavaClasses mainClasses = new ClassFileImporter()
28
    .withImportOption(new ImportOptions.MavenMainClassesOnly())
29
    .importPackages("org.apache.flink");
30

31
// Apply architecture rules only to production code
32
ArchRule productionCodeRule = classes()
33
    .that().areNotEnums()
34
    .should().notAccessClassesThat().haveSimpleNameContaining("Test");
35

36
productionCodeRule.check(mainClasses);
37
```
38

39
### Scala Code Exclusion
40

41
Excludes Scala classes on a best-effort basis, since ArchUnit doesn't fully support Scala analysis.
42

43
```java { .api }
44
/**
45
 * ImportOption that excludes Scala classes to avoid ArchUnit compatibility issues
46
 * Pattern: .*/scala/.* (excluded)
47
 * Note: This is best-effort; use SourcePredicates.areJavaClasses() in rules as well
48
 */
49
public static final class ExcludeScalaImportOption implements ImportOption {
50
    public boolean includes(Location location);
51
}
52
```
53

54
**Usage Example:**
55

56
```java
57
import org.apache.flink.architecture.common.ImportOptions;
58
import org.apache.flink.architecture.common.GivenJavaClasses;
59

60
// Exclude Scala classes during import
61
JavaClasses javaOnlyClasses = new ClassFileImporter()
62
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
63
    .importPackages("org.apache.flink");
64

65
// Use Java-only rule definitions for additional safety
66
ArchRule javaOnlyRule = GivenJavaClasses.javaClassesThat()
67
    .arePublic()
68
    .should().onlyDependOnClassesThat().areNotAnnotatedWith(Deprecated.class);
69

70
javaOnlyRule.check(javaOnlyClasses);
71
```
72

73
### Shaded Dependency Exclusion
74

75
Excludes shaded (relocated) dependencies to avoid analyzing external code and reduce memory consumption.
76

77
```java { .api }
78
/**
79
 * ImportOption that excludes shaded dependencies and relocated packages
80
 * Pattern: .*/shaded/.* (excluded)
81
 * Essential for memory consumption control when analyzing large projects
82
 */
83
public static final class ExcludeShadedImportOption implements ImportOption {
84
    public boolean includes(Location location);
85
}
86
```
87

88
**Usage Example:**
89

90
```java
91
import org.apache.flink.architecture.common.ImportOptions;
92

93
// Exclude shaded dependencies to focus on core code
94
JavaClasses coreClasses = new ClassFileImporter()
95
    .withImportOption(new ImportOptions.ExcludeShadedImportOption())
96
    .importPackages("org.apache.flink");
97

98
// Validate that core code doesn't directly access shaded packages
99
ArchRule noShadedAccessRule = classes()
100
    .should().onlyAccessClassesThat()
101
    .haveFullyQualifiedName(not(containsString(".shaded.")));
102

103
noShadedAccessRule.check(coreClasses);
104
```
105

106
## Combined Import Strategies
107

108
### Production Java Code Only
109

110
Combines all import options for the cleanest analysis focused on production Java code.
111

112
```java
113
import org.apache.flink.architecture.common.ImportOptions;
114

115
JavaClasses productionJavaClasses = new ClassFileImporter()
116
    .withImportOption(new ImportOptions.MavenMainClassesOnly())
117
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
118
    .withImportOption(new ImportOptions.ExcludeShadedImportOption())
119
    .importPackages("org.apache.flink");
120
```
121

122
### Memory-Optimized Import
123

124
For large codebases where memory consumption is a concern.
125

126
```java
127
// Import strategy for large projects
128
JavaClasses optimizedClasses = new ClassFileImporter()
129
    .withImportOption(new ImportOptions.ExcludeShadedImportOption()) // Critical for memory
130
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())  // Avoid analysis issues
131
    .withImportOption(location -> !location.contains("test"))        // Custom test exclusion
132
    .importPackagesOf(MyMainClass.class); // Import specific package tree
133
```
134

135
### Module-Specific Analysis
136

137
Target specific modules while excluding irrelevant code.
138

139
```java
140
// Analyze only streaming API module
141
JavaClasses streamingClasses = new ClassFileImporter()
142
    .withImportOption(new ImportOptions.MavenMainClassesOnly())
143
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
144
    .withImportOption(location -> location.contains("streaming"))
145
    .importPackages("org.apache.flink.streaming");
146

147
// Apply streaming-specific rules
148
ArchRule streamingRule = classes()
149
    .that().haveSimpleNameEndingWith("Stream")
150
    .should().implement("org.apache.flink.streaming.api.DataStream");
151
```
152

153
## Performance Considerations
154

155
### Memory Usage
156

157
```java
158
// High memory usage - imports everything
159
JavaClasses allClasses = new ClassFileImporter()
160
    .importPackages("org.apache.flink"); // May cause OutOfMemoryError
161

162
// Optimized memory usage
163
JavaClasses optimizedClasses = new ClassFileImporter()
164
    .withImportOption(new ImportOptions.ExcludeShadedImportOption()) // Biggest impact
165
    .withImportOption(new ImportOptions.MavenMainClassesOnly())      // Reduces test noise
166
    .importPackages("org.apache.flink.streaming.api");               // Specific package
167
```
168

169
### Analysis Scope
170

171
```java
172
// Broad analysis - slower but comprehensive
173
JavaClasses broadAnalysis = new ClassFileImporter()
174
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
175
    .importPackages("org.apache.flink");
176

177
// Focused analysis - faster and more targeted
178
JavaClasses focusedAnalysis = new ClassFileImporter()
179
    .withImportOption(new ImportOptions.MavenMainClassesOnly())
180
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
181
    .withImportOption(new ImportOptions.ExcludeShadedImportOption())
182
    .importPackagesOf(SpecificModuleClass.class);
183
```
184

185
## Integration with Other Components
186

187
### Working with GivenJavaClasses
188

189
```java
190
import org.apache.flink.architecture.common.ImportOptions;
191
import org.apache.flink.architecture.common.GivenJavaClasses;
192

193
// Import with filtering
194
JavaClasses filteredClasses = new ClassFileImporter()
195
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
196
    .importPackages("org.apache.flink");
197

198
// Apply Java-only rules for additional safety
199
ArchRule javaClassRule = GivenJavaClasses.javaClassesThat()
200
    .arePublic()
201
    .should().notHaveSimpleNameContaining("Scala");
202

203
javaClassRule.check(filteredClasses);
204
```
205

206
### Custom Import Options
207

208
```java
209
// Create custom import option
210
ImportOption customOption = location -> 
211
    !location.contains("deprecated") && 
212
    !location.contains("experimental");
213

214
JavaClasses customFilteredClasses = new ClassFileImporter()
215
    .withImportOption(new ImportOptions.MavenMainClassesOnly())
216
    .withImportOption(new ImportOptions.ExcludeScalaImportOption())
217
    .withImportOption(customOption)
218
    .importPackages("org.apache.flink");
219
```
220

221
## Design Principles
222

223
- **Memory Efficiency**: Designed to reduce memory consumption when analyzing large codebases
224
- **Best-Effort Filtering**: Scala exclusion is best-effort; additional filtering in rules is recommended
225
- **Composability**: Multiple import options can be combined for precise control
226
- **Maven Integration**: Specifically designed for Maven project structures and conventions
227
- **Performance Optimization**: Essential for making architectural analysis feasible on large projects