AnalyzeClasses.java

/*
 * Copyright 2014-2025 TNG Technology Consulting GmbH
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.tngtech.archunit.junit;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.core.importer.ImportOption.DoNotIncludeJars;
import com.tngtech.archunit.core.importer.ImportOption.DoNotIncludeTests;

import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * Specifies which packages/locations should be scanned and tested when running a test with the {@link ArchUnitRunner}.
 * <br><br>
 * To ignore certain classes (e.g. classes in test scope) see {@link #importOptions()}, in particular {@link DoNotIncludeTests} and
 * {@link DoNotIncludeJars}.
 * <br><br>
 * When checking rules, it is important to remember that all relevant information/classes need to be imported for the rules
 * to work. For example, if class A accesses class B and class B extends class C, but class B is not imported, then
 * a rule checking for no accesses to classes assignable to C will not fail, since ArchUnit does not know about the details
 * of class B, but only simple information like the fully qualified name. For information how to configure the import and
 * resolution behavior of missing classes, compare {@link ClassFileImporter}.
 * <br><br>
 * Classes to be analyzed can be specified in different ways:
 * <ul>
 *     <li>{@link #packages()} - specify package names as strings</li>
 *     <li>{@link #packagesOf()} - specify packages relative to classes</li>
 *     <li>{@link #classes()} - specify individual classes to analyze</li>
 *     <li>{@link #locations()} - specify custom locations via {@link LocationProvider}</li>
 *     <li>{@link #wholeClasspath()} - import all classes on the classpath</li>
 * </ul>
 * These options can be combined. If no option is specified, the package of the annotated test class will be imported.
 *
 * @see ArchUnitRunner
 * @see ClassFileImporter
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface AnalyzeClasses {
    /**
     * @return Packages to look for within the classpath / modulepath
     */
    String[] packages() default {};

    /**
     * @return Classes that specify packages to look for within the classpath / modulepath
     */
    Class<?>[] packagesOf() default {};

    /**
     * @return Implementations of {@link LocationProvider}. Allows to completely customize the sources,
     * where classes are imported from.
     */
    Class<? extends LocationProvider>[] locations() default {};

    /**
     * @return Whether to import all classes on the classpath.
     *         Warning: Without any further filtering this can require a lot of resources.
     */
    boolean wholeClasspath() default false;

    /**
     * Allows to filter the class import. The supplied types will be instantiated and used to create the
     * {@link ImportOption ImportOptions} passed to the {@link ClassFileImporter}. Considering caching, compare the notes on
     * {@link ImportOption}.
     *
     * @return The types of {@link ImportOption} to use for the import
     */
    Class<? extends ImportOption>[] importOptions() default {};

    /**
     * Controls, if {@link JavaClasses} should be cached by location,
     * to be reused between several test classes, or just within the same class.
     *
     * @return The {@link CacheMode} to use for this test class.
     */
    CacheMode cacheMode() default CacheMode.FOREVER;

    /**
     * @return Classes to be used for testing instead of packages
     */
    Class<?>[] classes() default {};
}