Soklet Logo

Code Samples

Barebones App

Here we demonstrate building and running a single-file "barebones" Soklet application with nothing but the soklet-4.0.0.jar and the JDK. There are no other libraries or frameworks, no Servlet container, no Maven build process - no special setup is required.

While a real production system will have more moving parts, this demonstrates that you can build server software without ceremony or dependencies.

This app lives in its own GitHub repository.

If you'd like an example of a production-ready system, see the Toy Store App.


Source Code

The entire application is contained in App.java, which is reproduced below.

public class App {
  @GET("/")
  public String index() {
    return "Hello, world!";
  }

  @GET("/test-input")
  public Response testInput(@QueryParameter Integer input) {
    return Response.withStatusCode(200)
        .headers(Map.of("Content-Type", List.of("application/json; charset=UTF-8")))
        // A real application would not construct JSON in this manner
        .body(String.format("{\"input\": %d}", input))
        .build();
  }

  public static void main(String[] args) throws Exception {
    SokletConfig sokletConfig = SokletConfig.withHttpServer(
        HttpServer.withPort(8080).host("127.0.0.1").build()
    ).build();

    Soklet soklet = Soklet.run(sokletConfig);
    System.out.println("Soklet Barebones App started on port 8080");
    soklet.awaitShutdown();
  }
}

The app listens on http://127.0.0.1:8080/. Use Ctrl+C to stop it; Soklet shuts down automatically with the JVM. For scoped runs and embedded applications, see Application Lifecycle.

Building and Running

You'll need to provide javac with these flags, including Soklet's SokletProcessor:

  • -parameters
  • -processor com.soklet.SokletProcessor

JDK 21+ is required.

If you need a JDK, Amazon provides Corretto - a free-to-use-commercially, production-ready distribution of OpenJDK that includes long-term support.

Build

javac -parameters -processor com.soklet.SokletProcessor -cp soklet-4.0.0.jar -d build src/com/soklet/barebones/App.java

Run (use Ctrl+C to stop)

java -cp soklet-4.0.0.jar:build com/soklet/barebones/App

Testing

These tests assume you have the command-line tool curl installed.

Alternatively, you can open the URLs in your web browser.

Happy Path

Request

curl  "http://localhost:8080/"

Response

Hello, world!

Query Parameters

Request

curl --verbose "http://localhost:8080/test-input?input=123"

Response

*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /test-input?input=123 HTTP/1.1
...
< HTTP/1.1 200 OK
< Content-Length: 14
< Content-Type: application/json; charset=UTF-8
< Date: Sun, 21 Mar 2024 16:19:01 GMT
<
* Connection #0 to host localhost left intact
{"input": 123}

Bad Input

Request

curl --verbose "http://localhost:8080/test-input?input=abc"

Response

*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /test-input?input=abc HTTP/1.1
...
< HTTP/1.1 400 Bad Request
< Content-Length: 21
< Content-Type: text/plain; charset=UTF-8
< Date: Sun, 21 Mar 2024 16:19:01 GMT
<
* Connection #0 to host localhost left intact
HTTP 400: Bad Request
Previous
Public API Map