Building and Running

Soklet requires JDK 21+. The homepage example and MCP Quickstart show how to compile and run an application using only the JDK and Soklet JAR. For an existing Maven or Gradle project, use the configurations below.

Upgrading an existing application? Read the 4.0.0 migration guide for the Java baseline, lifecycle APIs, collection changes, and other compatibility boundaries.

See Application Lifecycle to choose between a standalone server, scoped execution, and a host-managed service.

Maven build configuration

Add the Soklet dependency to your POM's dependencies section, then configure the compiler in its build/plugins section. Soklet's processor generates the HTTP/SSE route indexes and MCP endpoint descriptors; the dependency alone is not sufficient to enable processing on JDK 23+.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.16.0</version>
  <configuration>
    <release>21</release>
    <parameters>true</parameters>
    <annotationProcessorPaths>
      <path>
        <groupId>com.soklet</groupId>
        <artifactId>soklet</artifactId>
        <version>4.0.0</version>
      </path>
    </annotationProcessorPaths>
    <annotationProcessors>
      <annotationProcessor>com.soklet.SokletProcessor</annotationProcessor>
    </annotationProcessors>
  </configuration>
</plugin>

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.16.0</version>
  <configuration>
    <release>21</release>
    <parameters>true</parameters>
    <annotationProcessorPaths>
      <path>
        <groupId>com.soklet</groupId>
        <artifactId>soklet</artifactId>
        <version>4.0.0</version>
      </path>
    </annotationProcessorPaths>
    <annotationProcessors>
      <annotationProcessor>com.soklet.SokletProcessor</annotationProcessor>
    </annotationProcessors>
  </configuration>
</plugin>

Merge this configuration with your existing compiler-plugin configuration. The explicit processor path replaces compile-classpath discovery, and the named processor list selects which processors run. Preserve every other processor your build needs (such as Lombok or MapStruct) by keeping its artifact in annotationProcessorPaths and its processor class name in annotationProcessors alongside Soklet.

Gradle build configuration

plugins {
  id 'java'
}

repositories {
  mavenCentral()
}

dependencies {
  implementation 'com.soklet:soklet:4.0.0'
  annotationProcessor 'com.soklet:soklet:4.0.0'
}

tasks.withType(JavaCompile).configureEach {
  options.release = 21
  options.compilerArgs += ['-parameters']
}

plugins {
  id 'java'
}

repositories {
  mavenCentral()
}

dependencies {
  implementation 'com.soklet:soklet:4.0.0'
  annotationProcessor 'com.soklet:soklet:4.0.0'
}

tasks.withType(JavaCompile).configureEach {
  options.release = 21
  options.compilerArgs += ['-parameters']
}

Both examples target Java 21, including when the build runs on a newer JDK. Use a higher release if your application requires newer Java features.

If your build combines -Xlint:all with -Werror, use -Xlint:all,-processing -Werror when running Soklet's processor. This suppresses annotation-processing warnings while retaining the other compiler warnings as errors.

Gradle loads annotation processors from annotationProcessor, not implementation. Add testAnnotationProcessor 'com.soklet:soklet:4.0.0' when test sources declare annotated routes or MCP endpoints.

Packaging

In either build, preserve generated provider classes and META-INF/soklet indexes when shading or repackaging the application. Compilation without those resources does not prove that routes or endpoints will be discovered at runtime.

See Packaging and Static Analysis for annotation dependencies, dependency analysis, and custom runtime image considerations.