Skip to content

README.md

Latest commit

 

History

History
95 lines (72 loc) · 3.38 KB

README.md

File metadata and controls

95 lines (72 loc) · 3.38 KB
Raw

sandbox_common_core

Eclipse-independent common core module for sandbox utilities.

Overview

sandbox_common_core is a plain Maven JAR (no OSGi/Eclipse dependencies beyond JDT Core) that contains the core utility classes extracted from sandbox_common. This separation enables:

  • Standalone usage: Use HelperVisitor, TriggerPattern API, and mining utilities without an Eclipse runtime
  • Fast testing: Tests can run without Xvfb or target platform resolution
  • CLI tools: Build refactoring-mining tools without Eclipse dependencies
  • Lightweight dependency: Only requires org.eclipse.jdt:org.eclipse.jdt.core

Packages

Package Description
org.sandbox.jdt.internal.common HelperVisitor API, LambdaASTVisitor, builders, and visitor utilities
org.sandbox.jdt.triggerpattern.api TriggerPattern engine, pattern matching, guard expressions, fix utilities
org.sandbox.jdt.triggerpattern.internal Pattern/hint file parsers, placeholder matching, BuiltInGuards, HintFileStore

Dependency Graph

sandbox_common_core (JAR, only JDT Core)
    ↑
    ├── sandbox_common (OSGi bundle, re-exports core)
    │       ↑
    │       ├── sandbox_junit_cleanup
    │       ├── sandbox_encoding_quickfix
    │       ├── sandbox_triggerpattern
    │       └── ... (all existing plugins)
    │
    └── sandbox_common_test (plain Maven JAR, tests core + common)

Testing

Tests that only depend on sandbox_common_core classes live in src/test/java/. These run as plain JUnit 5 tests without Xvfb, Eclipse runtime, or target platform resolution:

# Run all core tests (~324 tests, finishes in seconds)
mvn test -pl sandbox_common_core

Tests that require OSGi, Eclipse Platform, or classes from sandbox_common (mining, registries, HintContext, corext utilities) remain in sandbox_common_test.

Building

# Build standalone (no Eclipse target platform needed)
mvn clean verify -pl sandbox_common_core

# Install to local repository
mvn install -pl sandbox_common_core -DskipTests

Usage as Dependency

Maven (plain JAR)

<dependency>
    <groupId>org.sandbox</groupId>
    <artifactId>sandbox_common_core</artifactId>
    <version>${project.version}</version>
</dependency>

OSGi Bundle

The JAR includes OSGi manifest headers (generated by bnd-maven-plugin) with:

  • Bundle-SymbolicName: sandbox_common_core
  • Exported packages for all three packages

Eclipse Plugin (via sandbox_common)

Existing Eclipse plugins should continue to depend on sandbox_common which re-exports sandbox_common_core with visibility:=reexport.

Stateless typed AST actions

When a traversal needs no shared reference holder, register a typed action:

AstProcessing.independent()
    .visit(SimpleName.class, name -> names.add(name.getIdentifier()))
    .build(root);

visit always continues into descendants. Use on(Class, BiPredicate) when traversal decisions or shared state are needed. Each independent stage traverses the root separately; adding two stages does not create a nested query. excluding(nodes) skips callbacks for those exact AST nodes, not their children. Callback exceptions propagate; builders remain reusable. The functional converter's LoopVariableNames is a production consumer, with collision and repeated-preview characterization tests.