tessl/maven-org-reflections--reflections

Java runtime metadata analysis library that enables reverse querying of classpath metadata for type system introspection

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/maven-org-reflections--reflections
Author: tessl

Flexible configuration system for setting up scanning parameters, URLs, filters, class loaders, and scanner selection. Configuration is essential for controlling what gets scanned and how the scanning process behaves.

Capabilities

Configuration Interface

Core configuration contract that defines all settings needed for Reflections scanning.

/**
 * Configuration contract for Reflections instances
 */
interface Configuration {
    /** Scanner instances used for indexing metadata (defaults to SubTypes and TypesAnnotated) */
    Set<Scanner> getScanners();
    
    /** URLs to be scanned (required) */
    Set<URL> getUrls();
    
    /** Filter used to filter types to be scanned (defaults to accept all if null) */
    Predicate<String> getInputsFilter();
    
    /** Whether to scan URLs in parallel (defaults to true) */
    boolean isParallel();
    
    /** Optional class loaders for resolving types */
    ClassLoader[] getClassLoaders();
    
    /** Whether to expand super types after scanning for unscanned types (defaults to true) */
    boolean shouldExpandSuperTypes();
}

ConfigurationBuilder

Builder class implementing Configuration interface for easy and flexible configuration creation.

/**
 * Configuration builder for instantiating Reflections
 */
class ConfigurationBuilder implements Configuration {
    /** Default scanners: SubTypes and TypesAnnotated */
    public static final Set<Scanner> DEFAULT_SCANNERS;
    
    /** Default inputs filter: accepts all */
    public static final Predicate<String> DEFAULT_INPUTS_FILTER;
    
    /** Default constructor */
    ConfigurationBuilder();
    
    /** Build configuration from various parameter types */
    static ConfigurationBuilder build(Object... params);
}

Package Configuration Methods

Methods for configuring which packages and URLs to scan.

/**
 * Package and URL configuration methods
 */
class ConfigurationBuilder implements Configuration {
    /** Add URLs for package prefix with optional class loaders */
    ConfigurationBuilder forPackage(String pkg, ClassLoader... classLoaders);
    
    /** Add URLs for multiple package prefixes */
    ConfigurationBuilder forPackages(String... packages);
    
    /** Set URLs to be scanned (replaces existing) */
    ConfigurationBuilder setUrls(Collection<URL> urls);
    
    /** Set URLs to be scanned from array (replaces existing) */
    ConfigurationBuilder setUrls(URL... urls);
    
    /** Add URLs to existing set */
    ConfigurationBuilder addUrls(Collection<URL> urls);
    
    /** Add URLs from array to existing set */
    ConfigurationBuilder addUrls(URL... urls);
}

Scanner Configuration Methods

Methods for configuring which scanners to use for metadata indexing.

/**
 * Scanner configuration methods
 */
class ConfigurationBuilder implements Configuration {
    /** Set scanners to use (replaces existing) */
    ConfigurationBuilder setScanners(Scanner... scanners);
    
    /** Add scanners to existing set */
    ConfigurationBuilder addScanners(Scanner... scanners);
}

Filter Configuration Methods

Methods for configuring input filtering to control which types get scanned.

/**
 * Filter configuration methods
 */
class ConfigurationBuilder implements Configuration {
    /** Set input filter predicate */
    ConfigurationBuilder setInputsFilter(Predicate<String> inputsFilter);
    
    /** Set input filter predicate (alias for setInputsFilter) */
    ConfigurationBuilder filterInputsBy(Predicate<String> inputsFilter);
}

Other Configuration Methods

Methods for configuring parallelism, class loaders, and super type expansion.

/**
 * Other configuration options
 */
class ConfigurationBuilder implements Configuration {
    /** Set whether to scan URLs in parallel */
    ConfigurationBuilder setParallel(boolean parallel);
    
    /** Set class loaders for type resolution (replaces existing) */
    ConfigurationBuilder setClassLoaders(ClassLoader[] classLoaders);
    
    /** Add class loaders to existing array */
    ConfigurationBuilder addClassLoaders(ClassLoader... classLoaders);
    
    /** Set whether to expand super types after scanning */
    ConfigurationBuilder setExpandSuperTypes(boolean expandSuperTypes);
}

Usage Examples

Basic Package Configuration

import org.reflections.util.ConfigurationBuilder;
import org.reflections.scanners.Scanners;

// Simple package configuration with defaults
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackage("com.mycompany");

// Multiple packages
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany.api", "com.mycompany.core", "com.mycompany.util");

// Package with specific class loaders
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackage("com.mycompany", MyClass.class.getClassLoader());

Scanner Configuration

// Use specific scanners
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .setScanners(Scanners.SubTypes, Scanners.TypesAnnotated, Scanners.MethodsAnnotated);

// Add additional scanners to defaults
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .addScanners(Scanners.FieldsAnnotated, Scanners.Resources);

// Use all available scanners
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .setScanners(Scanners.values());

URL Configuration

import org.reflections.util.ClasspathHelper;
import java.net.URL;
import java.util.Collection;

// Explicit URL configuration
Collection<URL> urls = ClasspathHelper.forPackage("com.mycompany");
ConfigurationBuilder config = new ConfigurationBuilder()
    .setUrls(urls)
    .addScanners(Scanners.SubTypes);

// Add specific URLs
URL jarUrl = new URL("jar:file:/path/to/my.jar!/");
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .addUrls(jarUrl);

// Use classpath URLs
ConfigurationBuilder config = new ConfigurationBuilder()
    .addUrls(ClasspathHelper.forJavaClassPath())
    .addUrls(ClasspathHelper.forClassLoader());

Filter Configuration

import org.reflections.util.FilterBuilder;

// Include/exclude package patterns
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .filterInputsBy(new FilterBuilder()
        .includePackage("com.mycompany")
        .excludePackage("com.mycompany.internal")
        .excludePackage("com.mycompany.test"));

// Pattern-based filtering
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .filterInputsBy(new FilterBuilder()
        .includePattern(".*Service.*")
        .includePattern(".*Controller.*")
        .excludePattern(".*Test.*"));

// Custom predicate filtering
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .filterInputsBy(className -> 
        className.contains("Service") || 
        className.contains("Repository"));

Advanced Configuration

// Complete configuration example
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany.api", "com.mycompany.core")
    .addUrls(ClasspathHelper.forClassLoader(Thread.currentThread().getContextClassLoader()))
    .setScanners(Scanners.values())
    .filterInputsBy(new FilterBuilder()
        .includePackage("com.mycompany")
        .excludePackage("com.mycompany.test")
        .excludePattern(".*\\$.*")) // exclude inner classes
    .setParallel(true)
    .setExpandSuperTypes(true)
    .addClassLoaders(MyClass.class.getClassLoader());

// Use with Reflections
Reflections reflections = new Reflections(config);

Configuration from Various Parameters

// ConfigurationBuilder.build() accepts various parameter types
ConfigurationBuilder config = ConfigurationBuilder.build(
    "com.mycompany",                    // package name
    ClasspathHelper.forPackage("com.mycompany"), // URLs
    new FilterBuilder().includePackage("com.mycompany"), // filter
    Scanners.SubTypes,                  // scanners
    MyClass.class.getClassLoader()      // class loader
);

Performance and Parallelism Configuration

// Optimize for performance
ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .setParallel(true) // scan in parallel (default)
    .setExpandSuperTypes(false) // skip super type expansion if not needed
    .filterInputsBy(new FilterBuilder()
        .includePackage("com.mycompany")) // filter early to reduce scanning
    .setScanners(Scanners.SubTypes); // use minimal scanners needed

Class Loader Configuration

// Multiple class loaders
ClassLoader appClassLoader = MyApp.class.getClassLoader();
ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();

ConfigurationBuilder config = new ConfigurationBuilder()
    .forPackages("com.mycompany")
    .setClassLoaders(new ClassLoader[]{appClassLoader, contextClassLoader})
    .addClassLoaders(ClassLoader.getSystemClassLoader());

Configuration Best Practices

URL Selection

Use forPackage() or forPackages() for simple package-based scanning
Use ClasspathHelper utilities for more control over URL selection
Filter URLs early to avoid scanning unnecessary JARs

Scanner Selection

Use minimal set of scanners needed for your use case
Default scanners (SubTypes, TypesAnnotated) are sufficient for most cases
Add specific scanners (MethodsAnnotated, FieldsAnnotated, etc.) only when needed

Filtering Strategy

Always use input filters to avoid scanning system classes
Include only packages you need to scan
Exclude test packages, internal packages, and third-party packages when possible

Performance Optimization

Keep parallel scanning enabled (default: true)
Use restrictive filters to minimize scanning scope
Consider disabling super type expansion if not needed
Cache and reuse Reflections instances when possible

Types

/**
 * Filter builder for creating input filters
 */
class FilterBuilder implements Predicate<String> {
    /** Parse include/exclude string in CSV format */
    static FilterBuilder parsePackages(String includeExcludeString);
    
    /** Include package prefix */
    FilterBuilder includePackage(String value);
    
    /** Exclude package prefix */
    FilterBuilder excludePackage(String value);
    
    /** Include regex pattern */
    FilterBuilder includePattern(String regex);
    
    /** Exclude regex pattern */
    FilterBuilder excludePattern(String regex);
    
    /** Add custom predicate */
    FilterBuilder add(Predicate<String> filter);
    
    /** Test string against filters */
    boolean test(String regex);
}

Install with Tessl CLI

npx tessl i tessl/maven-org-reflections--reflections

docs

configuration.md

core-operations.md

functional-queries.md