Installation

Spider Silk requires Java 25 or later. Releases are published to Maven Central, so a build needs no repository beyond the default one. The current version is 1.1.0. CHANGELOG.md lists what changed in each release.

Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation 'net.benelog.spidersilk:spider-silk-core:1.1.0'
    testImplementation 'net.benelog.spidersilk:spider-silk-test:1.1.0'
}

Maven

Maven resolves from Central by default, so pom.xml declares the dependencies and nothing else:

<dependencies>
  <dependency>
    <groupId>net.benelog.spidersilk</groupId>
    <artifactId>spider-silk-core</artifactId>
    <version>1.1.0</version>
  </dependency>
  <dependency>
    <groupId>net.benelog.spidersilk</groupId>
    <artifactId>spider-silk-test</artifactId>
    <version>1.1.0</version>
    <scope>test</scope>
  </dependency>
</dependencies>

Hello, world

import net.benelog.spidersilk.App;
import net.benelog.spidersilk.WebResponse;

public class Main {

    public static void main(String[] args) {
        App app = new App();
        app.get("/hello/{name}", req -> WebResponse.text("Hello, " + req.pathParam("name")));
        app.start(8080);
    }
}
$ curl localhost:8080/hello/silk
Hello, silk

spider-silk-core brings embedded Jetty with it, so nothing else is needed to serve a request. See Deployment to deploy on an external servlet container instead.

Modules

The modules fall into four groups. Only the core group is needed, and the others are added one at a time, the same way as core.

Core

Every application uses these two.

Module Contents

spider-silk-core

The framework, with jte templates, embedded Jetty, and silk-json, the JSON library it is built on

spider-silk-test

WebTest and TestRequest, for test scope

Extensions

An extension is optional. Add one only when you want what it names instead of, or beside, the core default.

Module Use it when you want

Servers: core’s default is Jetty, and Choosing a server covers the choice

spider-silk-tomcat

TomcatServer: an embedded Tomcat

spider-silk-undertow

UndertowServer: an embedded Undertow

Templates: core’s default is jte

spider-silk-freemarker

FreeMarkerTemplates: FreeMarker

spider-silk-handlebars

HandlebarsTemplates: Handlebars

spider-silk-thymeleaf

ThymeleafTemplates: Thymeleaf

Features

spider-silk-jetty-websocket

WebSockets: WebSocket endpoints beside the routes, on Jetty only

spider-silk-jackson

JacksonCodecs: Jackson 3 behind the JsonWriter and JsonReader handlers take

spider-silk-openapi

OpenApi: the route list as an OpenAPI 3.1 document

spider-silk-opentelemetry-agent

An OpenTelemetry Java agent extension: spans named after the matched route, with the jar handed to the agent rather than added as a dependency

Build

The build modules carry optional packaging conventions, precompiled jte, a Jib image, and a native build, and the generator of JSON codecs.

Module Build tool

spider-silk-gradle-plugin

Gradle, applied as the plugin net.benelog.spidersilk

spider-silk-maven-parent

Maven, used as the parent POM

silk-json-processor

javac on either build tool, as an annotation processor: Generated JSON Codecs for the types annotated @JsonBound, with nothing added at run time

Example

example-flashcard is a flashcard study app built on core, spring-jdbc, and H2. It is not published.

Coordinates, packages, and module names

net.benelog.spidersilk is one string, used three ways on purpose.

Where What it is

Group id

net.benelog.spidersilk, with the module’s own name as the artifact id — net.benelog.spidersilk:spider-silk-core

Package root

net.benelog.spidersilk, with core owning it and each other module a subpackage — net.benelog.spidersilk.tomcat, net.benelog.spidersilk.jetty.websocket

Automatic-Module-Name

The package root the jar carries, so import and the module path spell the same name — net.benelog.spidersilk, net.benelog.spidersilk.tomcat, net.benelog.spidersilk.jetty.websocket

The Gradle plugin is applied by that same id, net.benelog.spidersilk, and the Maven parent is net.benelog.spidersilk:spider-silk-maven-parent. silk-json, a library of its own, follows the same rule under a string of its own, net.benelog.silkjson: the artifacts net.benelog.silkjson:silk-json and net.benelog.silkjson:silk-json-processor, the package root net.benelog.silkjson, and net.benelog.silkjson.processor for the processor. Decision 32 gives the reasoning.