Java SDK

The Java SDK instruments methods with @VPoint. Three pieces cooperate: the annotation processor generates schema-bearing aggregate classes at compile time, the varianz-agent intercepts annotated methods at class-load time, and RegistryBinding connects the process to the registry. The Gradle plugin wires all three.

Canonical imports

import io.varianz.annotations.vpoint.VPoint;          // the annotation
import io.varianz.annotations.vpoint.VPointControl;   // per-VPoint handle
import io.varianz.annotations.vpoint.VPoints;         // auto-wired aggregate
import io.varianz.annotations.vpoint.param.VarianzId; // session-id marker
import io.varianz.annotations.struct.Struct;          // DTO struct marker
import io.varianz.annotations.struct.Function;        // context-function marker
import io.varianz.binding.RegistryBinding;            // registry connection

These are the only correct paths — io.varianz.annotations.VPoint (missing the vpoint package), io.varianz.sdk.VPoint, and similar guesses do not exist.

Defining VPoints

public class PricingService {
    @VPoint(name = "pricing/calculate")
    public double calculatePrice(double amount, double discount) {
        return amount * (1 - discount);
    }
}

Always set an explicit name. Omitted names derive from package/class/method names and break under refactoring.
Any class and method visibility works — the agent rewrites bytecode, so private/final/synchronized methods are fine. (One limit: for private inner classes, the generated aggregate can’t expose direct typed invocation; stages by name still work.)
Plain beans and public-field DTOs are introspected automatically — fields from getters or public fields, constructors matched by type compatibility (static factories like Quote.of(...) included). No @Struct needed for typical types. Field names convert camelCase → snake_case in CEL (basePrice → base_price).
For gRPC handlers, extract business logic into a plain-typed @VPoint method — keep StreamObserver out of schemas. See the pattern.

The processor generates a PricingServiceVPoints aggregate in the same package, wrapping the method with stage execution and embedding the VPD schema.

How interception works

The agent transforms each @VPoint method at class load: the original body is cloned to <method>$varianzDirect (keeping line tables, so breakpoints still land in your source), and the method itself becomes a dispatch stub into the stage chain. Calling the method normally routes through the pipeline — no bind()-proxy calls needed:

PricingService service = new PricingService();
double price = service.calculatePrice(100.0, 0.1);  // stages apply automatically

With no stages registered, dispatch reads one volatile and calls the clone directly — the no-stage path is essentially free after JIT warmup. If the agent is not attached, the SDK prints one loud warning at first class load and @VPoint methods run their original bodies. The Gradle/Maven plugins attach the agent for test and run tasks; production launchers must attach it explicitly:

application {
    applicationDefaultJvmArgs = listOf(
        "-javaagent:\$APP_HOME/lib/varianz-agent-0.2.1-agent.jar",
        "--enable-native-access=io.varianz.native_loader",  // Java 22+
    )
}

Connecting to the registry

Call RegistryBinding.init() early — before your server starts serving — then bind() each service instance to register its VPDs:

public static void main(String[] args) {
    String addr = System.getenv().getOrDefault("VARIANZ_REGISTRY_ADDR", "http://localhost:50051");
    RegistryBinding.init(addr);          // idempotent

    AdServiceImpl adService = new AdServiceImpl();
    AdServiceImplVPoints.bind(adService);

    Server server = ServerBuilder.forPort(9555)
        .intercept(new VarianzServerInterceptor())   // session propagation
        .addService(adService)
        .build()
        .start();
}

In Spring Boot, do both in a @PostConstruct. Session propagation uses the pull-based @VarianzId @Function(global = true) pattern — the full setup is in Propagate sessions.

Control annotations

@VPointControl(name = "pricing/calculate")
private VPointHandle calculateControl;   // enable/disable stages, query state

@VPoints
private PricingServiceVPoints vpoints;   // auto-wired aggregate

Aggregate.bind(service) returning a typed proxy exists for advanced cases (test harnesses, programmatic stage composition) — normal code doesn’t need it.

Disabling interception

In order of preference: don’t attach the agent (Gradle weave.set(false), Maven -Dvarianz.skipAgent=true); disable at runtime with -Dvarianz.proc.weave=false; or opt out one method with @VPoint(wrapped = false).

Maven

<repositories>
  <repository><id>varianz</id><url>https://pkgs.varianz.io/maven</url></repository>
</repositories>
<pluginRepositories>
  <pluginRepository><id>varianz</id><url>https://pkgs.varianz.io/maven</url></pluginRepository>
</pluginRepositories>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.varianz</groupId>
      <artifactId>varianz-bom</artifactId>
      <version>0.2.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.varianz</groupId>
    <artifactId>varianz-starter</artifactId>
    <type>pom</type>
  </dependency>
  <dependency>
    <groupId>io.varianz</groupId>
    <artifactId>varianz-junit</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <annotationProcessorPaths>
          <!-- The `all` classifier bundles JavaParser and other processor deps -->
          <path>
            <groupId>io.varianz</groupId>
            <artifactId>java-processor</artifactId>
            <version>0.2.1</version>
            <classifier>all</classifier>
          </path>
        </annotationProcessorPaths>
      </configuration>
    </plugin>

    <!-- Resolves the agent JAR and exposes -javaagent:… as ${varianz.agentArgs},
         same idiom as jacoco's prepare-agent. -->
    <plugin>
      <groupId>io.varianz</groupId>
      <artifactId>varianz-maven-plugin</artifactId>
      <version>0.2.1</version>
      <dependencies>
        <dependency>
          <groupId>io.varianz</groupId>
          <artifactId>varianz-agent</artifactId>
          <classifier>agent</classifier>
          <version>0.2.1</version>
        </dependency>
      </dependencies>
      <executions>
        <execution>
          <id>prepare-varianz-agent</id>
          <goals><goal>prepare-agent</goal></goals>
        </execution>
      </executions>
    </plugin>

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <configuration>
        <argLine>@{varianz.agentArgs}</argLine>
      </configuration>
    </plugin>
  </plugins>
</build>

On Java 22+, append --enable-native-access=io.varianz.native_loader to the <argLine>. To disable interception for a build, pass -Dvarianz.skipAgent=true.

Native access (Java 22+)

The SDK loads its Rust runtime via System.load, a restricted method under JEP 472. All Varianz JNI loading funnels through the io.varianz.native_loader module, so one flag covers the SDK:

--enable-native-access=io.varianz.native_loader

The Gradle plugin injects it automatically for Test/JavaExec on Java 22+; Maven and hand-rolled launchers add it to their JVM args. Prefer this targeted grant over ALL-UNNAMED.

Troubleshooting

@VPoint methods not intercepted — almost always the agent isn’t attached; look for the [varianz] Varianz agent not attached warning. Check weave (Gradle) or the prepare-agent execution + @{varianz.agentArgs} (Maven). For custom launchers, verify with -Dvarianz.proc.debug=true (the agent logs its transformer registration).
NoClassDefFoundError for a ...VPoints class at first call — the annotation processor didn’t run at compile time, so the aggregate doesn’t exist. With Gradle, compileJava should log Note: [Varianz] Generated adapters....
System.load warnings on Java 24+ — the JVM fork is missing the native-access flag; see above.

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

Canonical imports

Defining VPoints

How interception works

Connecting to the registry

Control annotations

Disabling interception

Maven

Native access (Java 22+)

Troubleshooting

​Canonical imports

​Defining VPoints

​How interception works

​Connecting to the registry

​Control annotations

​Disabling interception

​Maven

​Native access (Java 22+)

​Troubleshooting

Canonical imports

Defining VPoints

How interception works

Connecting to the registry

Control annotations

Disabling interception

Maven

Native access (Java 22+)

Troubleshooting