Core Operations

/**
 * Main API class for scanning and querying classpath metadata
 */
class Reflections {
    /** Create Reflections instance with custom configuration */
    Reflections(Configuration configuration);
    
    /** Create Reflections instance from existing metadata store */
    Reflections(Store store);
    
    /** Create Reflections instance for package prefix with optional scanners */
    Reflections(String prefix, Scanner... scanners);
    
    /** Convenient constructor accepting various parameter types */
    Reflections(Object... params);
    
    /** Generic query method using QueryFunction - modern functional API */
    <T> Set<T> get(QueryFunction<Store, T> query);
    
    /** Get underlying metadata store */
    Store getStore();
    
    /** Get configuration object */
    Configuration getConfiguration();
    
    /** Merge another Reflections instance into this one */
    Reflections merge(Reflections reflections);
}

/**
 * Static methods for collecting saved metadata
 */
class Reflections {
    /** Collect saved XML metadata from META-INF/reflections */
    static Reflections collect();
    
    /** Collect saved metadata with custom package prefix and filter */
    static Reflections collect(String packagePrefix, Predicate<String> resourceNameFilter);
    
    /** Collect saved metadata with custom serializer */
    static Reflections collect(String packagePrefix, Predicate<String> resourceNameFilter, Serializer serializer);
    
    /** Collect metadata from input stream using specified serializer */
    Reflections collect(InputStream inputStream, Serializer serializer);
    
    /** Collect metadata from file using specified serializer */
    Reflections collect(File file, Serializer serializer);
}

/**
 * Super type expansion for transitivity
 */
class Reflections {
    /** 
     * Expand super types after scanning for types that were not directly scanned
     * Provides transitive closure of metadata without scanning large 3rd party URLs
     */
    void expandSuperTypes(Map<String, Set<String>> subTypesStore, 
                         Map<String, Set<String>> typesAnnotatedStore);
}

/**
 * Metadata access methods
 */
class Reflections {
    /** Get parameter names for method or constructor using MethodParameterNamesScanner */
    List<String> getMemberParameterNames(Member member);
    
    /** Get code usage locations for member using MemberUsageScanner */
    Collection<Member> getMemberUsage(Member member);
    
    /** Get all keys/values for a specific scanner */
    Set<String> getAll(Scanner scanner);
    
    /** @Deprecated Get all scanned type names */
    @Deprecated Set<String> getAllTypes();
}

/**
 * Serialization and file operations
 */
class Reflections {
    /** Save metadata to file using default XmlSerializer */
    File save(String filename);
    
    /** Save metadata to file using specified serializer */
    File save(String filename, Serializer serializer);
}

import org.reflections.Reflections;
import org.reflections.util.ConfigurationBuilder;

// Simple package scanning with defaults
Reflections reflections = new Reflections("com.mycompany");

// Custom configuration
Reflections reflections = new Reflections(new ConfigurationBuilder()
    .forPackages("com.mycompany.api", "com.mycompany.core")
    .addScanners(Scanners.SubTypes, Scanners.TypesAnnotated)
    .filterInputsBy(new FilterBuilder().includePackage("com.mycompany")));

import static org.reflections.scanners.Scanners.*;

// Query subtypes using functional API
Set<Class<?>> subtypes = reflections.get(SubTypes.of(MyInterface.class).asClass());

// Query annotated methods with filtering
Set<Method> publicMethods = reflections.get(
    MethodsAnnotated.with(MyAnnotation.class)
        .as(Method.class)
        .filter(method -> Modifier.isPublic(method.getModifiers())));

// Query resources with pattern matching
Set<String> configFiles = reflections.get(Resources.with(".*\\.xml"));

// Collect pre-saved metadata
Reflections collected = Reflections.collect();

// Merge multiple Reflections instances
Reflections combined = new Reflections("com.mycompany.core")
    .merge(new Reflections("com.mycompany.api"))
    .merge(collected);

// Access underlying store and configuration
Store store = reflections.getStore();
Configuration config = reflections.getConfiguration();

// Create from existing store
Store existingStore = new Store();
Reflections fromStore = new Reflections(existingStore);

// Get raw store data
Map<String, Map<String, Set<String>>> storeData = reflections.getStore();

// Expand super types for transitivity
reflections.expandSuperTypes(
    store.get("SubTypes"), 
    store.get("TypesAnnotated"));

// Get parameter names for methods/constructors (requires MethodParameterNamesScanner)
Method method = MyClass.class.getMethod("myMethod", String.class, int.class);
List<String> paramNames = reflections.getMemberParameterNames(method);

// Get code usage locations for members (requires MemberUsageScanner)
Field field = MyClass.class.getField("myField");
Collection<Member> usages = reflections.getMemberUsage(field);

// Get all scanned data for a specific scanner
Set<String> allSubTypes = reflections.getAll(Scanners.SubTypes);

// Save to XML file (default serializer)
File xmlFile = reflections.save("/path/to/reflections-metadata.xml");

// Save using specific serializer
File jsonFile = reflections.save("/path/to/metadata.json", new JsonSerializer());

// Save to Java source code
File javaFile = reflections.save("/path/to/ReflectionsMetadata.java", new JavaCodeSerializer());

/**
 * Multimap storage for scanned metadata
 */
class Store extends HashMap<String, Map<String, Set<String>>> {
    /** Default constructor */
    Store();
    
    /** Constructor with initial store data */
    Store(Map<String, Map<String, Set<String>>> storeMap);
}

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

/**
 * Runtime exception for Reflections operations
 */
class ReflectionsException extends RuntimeException {
    ReflectionsException(String message);
    ReflectionsException(String message, Throwable cause);
    ReflectionsException(Throwable cause);
}