Skip to content

MAVEN_PLUGIN.md

Latest commit

 

History

History
184 lines (128 loc) · 4.04 KB

MAVEN_PLUGIN.md

File metadata and controls

184 lines (128 loc) · 4.04 KB

BPJ Maven Plugin (bpj:prepare)

bpj-maven-plugin enables ergonomic one-argument BPJ calls by rewriting source code during build.

For end-to-end activation steps (including IDE behavior), see:

  • docs/PLUGIN_ACTIVATION_GUIDE.md

Easiest Setup

Use bpj-starter-parent and you get this plugin preconfigured automatically.

<parent>
  <groupId>io.github.oriontheprogrammer</groupId>
  <artifactId>bpj-starter-parent</artifactId>
  <version>0.3.1</version>
</parent>

For Spring Boot projects that need BPJ auto-start without manual plugin wiring, use:

<parent>
  <groupId>io.github.oriontheprogrammer</groupId>
  <artifactId>bpj-spring-boot-parent</artifactId>
  <version>0.3.1</version>
</parent>

Goal

prepare

  • Default phase: generate-sources
  • Thread-safe: yes

What It Rewrites

Supported method names:

  • format
  • formatStrict
  • print
  • println
  • formatHighlighted
  • printHighlighted
  • printlnHighlighted

Supported call styles:

  • BPJ.println("Hello {name}")
  • io.github.bpj.BPJ.println("Hello {name}")
  • println("Hello {name}") when statically imported from io.github.bpj.BPJ
  • Compatibility in static methods: BPJ.print("El error es: {e}", this) is rewritten to generated map context

Conditions:

  • Exactly one argument
  • Argument is string literal or text block
  • At least one BPJ placeholder exists

Example

Input:

BPJ.println("Welcome {user.name}");

Generated:

BPJ.println("Welcome {user.name}", java.util.Map.of("user", user));

Placeholder Root Extraction

For each placeholder:

  • {user.name} -> root variable is user
  • {price} -> root variable is price

Repeated roots are de-duplicated in insertion order.

Generated map strategy:

  • Up to 10 roots: java.util.Map.of(...)
  • More than 10 roots: java.util.Map.ofEntries(...)

Plugin Parameters

inputDirectory

Default: ${project.build.sourceDirectory}

Source root to read from.

outputDirectory

Default: ${project.build.directory}/generated-sources/bpj

Generated source root.

replaceCompileSourceRoot

Default: true

When enabled:

  • removes original src/main/java compile root
  • compiles only generated source root

This prevents duplicate class compilation.

failOnError

Default: true

If true, transformation errors fail the build. If false, plugin logs a warning and build continues.

failOnUnresolved

Default: false

When true, BPJ fails the build if a placeholder root cannot be resolved from the current source scope.

Example:

  • Template: "Hello {name} {missing}"
  • In-scope variable: name
  • Missing variable: missing
  • Result with failOnUnresolved=true: plugin throws a clear error before compilation.

verbose

Default: false

Logs transformed files and replacement counts.

writeReport

Default: false

When enabled, the plugin writes a per-file transformation report.

reportFile

Default: ${project.build.directory}/reports/bpj-transform-report.txt

Destination file for the transformation report when writeReport=true.

Configuration

<build>
  <plugins>
    <plugin>
      <groupId>io.github.oriontheprogrammer</groupId>
      <artifactId>bpj-maven-plugin</artifactId>
      <version>0.3.1</version>
      <executions>
        <execution>
          <goals>
            <goal>prepare</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <verbose>true</verbose>
        <failOnUnresolved>true</failOnUnresolved>
        <writeReport>true</writeReport>
      </configuration>
    </plugin>
  </plugins>
</build>

Limitations

  • Does not rewrite calls with non-literal template arguments.
  • Does not evaluate arbitrary Java expressions inside placeholders.
  • Does not transform methods other than BPJ public formatting/printing APIs.
  • Operates at source level, not bytecode level.

Recommended Usage Pattern

  1. Add bpj dependency.
  2. Add bpj-maven-plugin execution (prepare).
  3. Write simple BPJ calls with placeholders.
  4. Let build-time transformation inject context maps automatically.