DPoP is one of the most exciting developments in the IAM (Identity and Access Management) space in recent years. Yet many backend developers either have not heard of it or are unsure what it actually changes. In this article, I will break down what DPoP is, what problem it solves, and walk through a working implementation with Keycloak and Quarkus.

What is DPoP?

DPoP (Demonstration of Proof-of-Possession) is an OAuth 2.0 security mechanism defined in RFC 9449. Its core purpose is simple: cryptographically bind an access token to the client that requested it. This way, even if a token is intercepted, it cannot be used by another client.

In the traditional Bearer token model, anyone who possesses the token is considered authorized. DPoP changes this model; to use a token, the client must also prove possession of the corresponding private key.

The Problem: Bearer Tokens and the “Finders Keepers” Risk

Bearer tokens are tokens carried in the HTTP Authorization header and accepted by the server without any additional verification of the presenter. RFC 6750 explicitly states that possession of the token is the sole authorization criterion. This means any party that obtains the token can act as if it were the legitimate client.

This is not a theoretical risk. Real-world breaches have shown, time and again, that stolen Bearer tokens translate directly into unauthorized access:

This is not a theoretical risk. Real-world breaches have shown, time and again, that stolen Bearer tokens translate directly into unauthorized access:

• Codecov Supply Chain Attack (2021): Attackers who infiltrated Codecov’s CI/CD process harvested tokens stored in customers’ environment variables. These tokens potentially granted access to private repositories of hundreds of organizations, including HashiCorp, which confirmed it was affected.
• GitHub OAuth Token Leak (2022): OAuth tokens belonging to Heroku and Travis CI were stolen, allowing attackers to list private repositories and access repository metadata across dozens of GitHub organizations, including npm.
• Microsoft SAS Token Incident (2023): Microsoft’s AI research team accidentally shared an overly permissive SAS token in a GitHub repository. This token made it possible to access 38 TB of internal data.

The common thread across these incidents is that a token was obtained and seamlessly used in a different context by a different actor. What makes this possible is the Bearer token model’s core assumption: whoever presents the token = the authorized actor. The model checks who holds the token, not who the token belongs to.

How Does DPoP Work?

DPoP requires the client to send a DPoP Proof JWT with every request. This proof is signed with the client’s private key and contains the following claims:

1. htm and htu (HTTP method and URL): Restricts the proof to a specific endpoint, preventing a proof generated for one resource from being used against another.
2. jti (JWT ID): Each proof carries a unique ID. The server records used jti values and rejects any proof that attempts to reuse one.
3. iat (Issued At): Indicates when the proof was generated, allowing the server to enforce a validity window and reject stale proofs.
4. ath (Access Token Hash): Specifies which access token the proof is associated with.

The flow works as follows:

1. Client generates an asymmetric key pair.
2. During the token request, the client sends a DPoP proof JWT whose header contains the public key (JWK).
3. The authorization server issues a DPoP-bound access token containing the JWK thumbprint (cnf.jkt).
4. When calling a protected resource, the client sends:
   - Authorization: DPoP <access_token>
   - DPoP: <signed proof JWT>
5. The resource server:
   - Verifies the proof signature
   - Checks that the proof's public key matches the token's cnf.jkt
   - Validates htm, htu, iat, jti
   - Verifies the ath claim binding the proof to the access token

With this model, stealing the token alone is not enough. The attacker cannot generate valid proofs without the private key, limiting any potential misuse to an already captured, unused proof within its narrow validity window. Compare this to the Bearer model, where a stolen token grants unrestricted access until it expires. DPoP does not eliminate token theft, but it makes stolen tokens fundamentally harder to exploit.

Configuring DPoP in Keycloak

For this article, I use Keycloak (v26.5.5) as the identity provider. It is open-source, widely adopted, and provides built-in DPoP support with a straightforward configuration.

DPoP was introduced as a preview feature in Keycloak 23.0.0 and became officially supported in version 26.4, working out of the box without any additional client configuration. If a client sends a DPoP proof during the token request, Keycloak validates it and includes the key thumbprint in the issued token. No extra setup is needed for this default behavior.

However, if you want to enforce DPoP for a specific client, meaning Bearer tokens will no longer be accepted for that client’s resources, follow these steps:

Step 1: In the Keycloak Admin Console, navigate to the relevant realm and select the client from the Clients menu.

Step 2: In the Settings tab, locate the Capability config section.

Step 3: Enable the Require DPoP bound tokens switch.

With this option enabled, the client must include a DPoP proof with every token request. Requests without valid proof will be rejected, and Bearer tokens will not be accepted to access this client’s resources.

DPoP in Action with Quarkus

To see DPoP in practice, I built a Quarkus application with protected REST endpoints and tested them using a k6 script. The full source code is available on GitHub.

Project Setup

The application uses Quarkus 3.32.2 with the following key extension: OpenId Connect. Quarkus provides extensions for OpenID Connect and OAuth 2.0 access token management, focusing on acquiring, refreshing, and propagating tokens.

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc</artifactId>
</dependency>

The quarkus.oidc.auth-server-url property specifies the base URL of the OpenID Connect (OIDC) server, which points to the Keycloak instance in this case:

quarkus.http.port=8180
quarkus.oidc.auth-server-url=http://localhost:8080/realms/master
quarkus.oidc.client-id=dpop-demo
quarkus.oidc.token.authorization-scheme=dpop

The key line here is quarkus.oidc.token.authorization-scheme=dpop. This property tells Quarkus OIDC extension to expect the Authorization: DPoP <token> scheme and to perform the full DPoP proof verification process as defined by RFC 9449. This includes validating the proof's signature, htm, htu, ath, and the cnf thumbprint binding between the token and the proof's public key.

Protected Endpoints

The application exposes three endpoints under the /api path, all requiring authentication. Each endpoint returns the caller's name and the token type (Bearer or DPoP) by checking the presence of the cnf claim in the JWT:

@Path("/api")
@Authenticated
public class ProtectedResource {

    private final JsonWebToken jwt;

    public ProtectedResource(JsonWebToken jwt) {
        this.jwt = jwt;
    }

    @GET
    @Path("/user-info")
    @Produces(MediaType.TEXT_PLAIN)
    public String getUserInfo() {
        return buildResponse();
    }

    @POST
    @Path("/user-info")
    @Produces(MediaType.TEXT_PLAIN)
    public String postUserInfo() {
        return buildResponse();
    }

    @POST
    @Path("/list-users")
    @Produces(MediaType.TEXT_PLAIN)
    public String listUsers() {
        return buildResponse();
    }

    private String buildResponse() {
        return "Hello, %s! Token type: %s".formatted(
                jwt.getName(),
                jwt.containsClaim("cnf") ? "DPoP" : "Bearer"
        );
    }
}

Having both GET and POST on /user-info plus a separate /list-users endpoint is intentional. These allow us to demonstrate how DPoP proof claims (htm and htu) restrict token usage to a specific HTTP method and URL.

Replay Protection with a jti Filter

As mentioned above, Quarkus OIDC extension handles the core DPoP verification. However, jti replay protection is not part of that process, since tracking used values requires server-side state, which falls outside the scope of a stateless token validation layer.

I added a minimal @ServerRequestFilter that records each proof's jti and rejects any reuse:

@Singleton
public class DpopJtiFilter {

    private final Set<String> usedJtis = ConcurrentHashMap.newKeySet();

    @ServerRequestFilter
    public Optional<Response> checkJti(ContainerRequestContext ctx) {
        String dpopHeader = ctx.getHeaderString("DPoP");
        if (dpopHeader == null || dpopHeader.isBlank()) {
            return Optional.empty();
        }

        String[] parts = dpopHeader.split("\\.");
        if (parts.length != 3) {
            return Optional.empty();
        }

        try {
            String payloadJson = new String(
                    Base64.getUrlDecoder().decode(parts[1]));
            String jti = extractJti(payloadJson);
            if (jti != null && !usedJtis.add(jti)) {
                return Optional.of(Response.status(Response.Status.UNAUTHORIZED)
                        .type(MediaType.TEXT_PLAIN)
                        .entity("DPoP proof replay detected: jti '%s' has already been used"
                                .formatted(jti))
                        .build());
            }
        } catch (Exception e) {
            // Let Quarkus OIDC handle malformed proofs
        }

        return Optional.empty();
    }

    // ...
}

In this example, I use an in-memory ConcurrentHashMap to keep the demo simple. In a production environment, you would use a distributed store such as Redis or Infinispan to track used jti values across multiple application instances and to apply TTL-based eviction aligned with the proof's validity window.

It is worth noting that Keycloak already performs jti replay protection at the authorization server level. Internally, its DPoPReplayCheck uses the SingleUseObjectProvider, which is backed by Infinispan's replicated cache. When a DPoP proof arrives at the token endpoint, Keycloak hashes the jti combined with the request URI using SHA-1 and stores it with a TTL derived from the proof's iat claim. If the same proof is submitted again, the putIfAbsent call fails and the request is rejected.

However, this protection only covers requests made to Keycloak itself. Once a DPoP-bound token is issued, the resource server is responsible for its own jti tracking. A stolen proof could be replayed against the Quarkus application, and Keycloak would have no visibility into that. This is why I added the jti filter at the resource server level, creating a two-layer defense: Keycloak guards the token endpoint, and the filter guards the application endpoints.

Testing with k6

The repository includes a k6 test script (k6/dpop-test.js) that exercises the full DPoP flow. Run it with:

k6 run k6/dpop-test.js

Security note: The k6 test script in the repository uses extractable: true when generating the DPoP key pair. This is fine for k6 since it’s a server-side test runner with no XSS attack surface. In browser-based implementations, you should set this to false so the private key material can never be accessed or exported by JavaScript. The key will still be usable for signing DPoP proofs via crypto.subtle.sign().

The script performs seven HTTP calls in sequence. The first request obtains a DPoP-bound token from Keycloak, the next three are happy-path requests (one per endpoint), and the final three test failure scenarios. Let’s take a closer look at what happens behind the scenes at both the Keycloak and Quarkus layers:

1. Token Request (Keycloak)

Before any resource access, the script requests a DPoP-bound access token:

1. The script generates an EC key pair (P-256) using the WebCrypto API.
2. It creates a DPoP proof JWT targeting Keycloak’s token endpoint (htm: POST, htu: .../protocol/openid-connect/token), signed with the private key. The public key is embedded in the proof's jwk header.
3. It sends a POST to the token endpoint with the DPoP header and user credentials (grant_type=password).
4. Keycloak validates the DPoP proof (signature, structure, claims), then issues an access token containing a cnf (confirmation) claim with the SHA-256 thumbprint of the client's public key. This binds the token to that specific key pair. Notice the typ: DPoP and the cnf.jkt field in the issued token:

{
  "typ": "DPoP",
  "azp": "dpop-demo",
  "sub": "830783f9-ab1b-4c41-9c23-fa6a335de1bc",
  "cnf": {
    "jkt": "8iU6dz7Uclsxek7kgyreJc8sc2LjZIbFqtUUFpWKZIc"
  },
  "scope": "email profile",
  "preferred_username": "hakdogan"
}

2. GET /user-info (Happy Path)

1. The script creates a fresh DPoP proof for GET /api/user-info with a new jti, current iat, and an ath computed from the access token's SHA-256 hash. The proof payload looks like this:

{
  "jti": "6f0bf628-309d-489b-9243-38ed169e1d8c",
  "htm": "GET",
  "htu": "http://localhost:8180/api/user-info",
  "iat": 1772897361,
  "ath": "3yFPVhSab16gaSgMAFtZCgm7GXpBMx5t3ZYCeuWqT0w"
}

1. It sends GET /api/user-info with Authorization: DPoP <token> and DPoP: <proof>.
2. Quarkus jti filter checks the proof’s jti against the used-jti store. This is a new jti, so the request passes through.
3. Quarkus OIDC extension validates the DPoP proof as required by RFC 9449 (Section 7.1), which assigns this responsibility to the resource server. It verifies the proof’s signature, confirms htm matches GET, htu matches the request URL, ath matches the token hash, and the cnf thumbprint in the token matches the proof's public key. All checks pass.
4. The endpoint reads the cnf claim from the token, identifies it as a DPoP token, and responds:

HTTP 200: Hello, hakdogan! Token type: DPoP

The script repeats this same flow for POST /user-info and POST /list-users, each with a fresh proof matching the target method and URL. Both return 200 with the same response.

3. GET /user-info (Replay Attack)

1. The script sends the exact same proof that was used in the happy path request.
2. Quarkus jti filter checks the jti and finds it already in the used-jti store. The request is rejected before reaching OIDC validation:

HTTP 401: DPoP proof replay detected: jti '...' has already been used

Note: The error message above includes the jti value for demonstration purposes, making it easy to observe what the filter caught. In a production environment, avoid exposing internal claim values in error responses. A generic 401 Unauthorized with no body, or a minimal message like "invalid DPoP proof", is sufficient and prevents information leakage.

4. POST /user-info (Method Mismatch — htm)

1. The script creates a new proof with htm: GET targeting /api/user-info, but sends it as a POST request.
2. Quarkus jti filter passes the request (new jti).
3. Quarkus OIDC extension compares the proof’s htm (GET) with the actual request method (POST). They do not match. The request is rejected:

HTTP 401

5. POST /list-users (URL Mismatch — htu)

1. The script creates a new proof targeting POST /api/user-info.
2. It sends the request to POST /api/list-users instead.
3. Quarkus jti filter passes the request (new jti).
4. Quarkus OIDC extension compares the proof’s htu with the actual request URL. They do not match. The request is rejected:

HTTP 401

All seven checks pass:

✓ Token request succeeds
✓ GET /user-info returns 200
✓ POST /user-info returns 200
✓ POST /list-users returns 200
✓ Replay attack returns 401
✓ htm mismatch returns 401
✓ htu mismatch returns 401

In contrast, if the same requests were sent as plain Bearer tokens without DPoP proofs, all of them would succeed with 200. The replay, method mismatch, and URL mismatch scenarios would go undetected because there is no proof to validate. This is exactly the gap that DPoP closes.

Conclusion

Bearer tokens follow a simple rule: whoever holds the token is authorized. DPoP changes this by binding each token to a cryptographic key pair and requiring a fresh, signed proof on every request. A stolen token alone is no longer sufficient.

The IAM ecosystem is moving in this direction. Identity providers like Keycloak and frameworks like Quarkus already offer built-in DPoP support, making adoption straightforward. Bearer tokens are not going away, but for access to sensitive resources, adopting DPoP is becoming less of a choice and more of a necessity.

Gatherers is a powerful extension of the Stream API that introduces support for customized intermediate operations. Initially introduced as a preview feature in JDK 22, it became a standard feature in JDK 24.

What are Gatherers?

Gatherers were developed to model intermediate operations in the Stream API. Just as a collector models a terminal operation, a gatherer is an object that models an intermediate operation. Gatherers support the characteristics of intermediate operations — they can push any number of elements to the stream they produce, maintain an internal mutable state, interrupt a stream, delay consumption, be chained, and execute in parallel.

For this reason, as stated in JEP 485

In fact every stream pipeline is, conceptually, equivalent to
source.gather(…).gather(…).gather(…).collect(…)

The java.util.stream.Gatherer interface, which models a gatherer, has three type parameters.

public interface Gatherer<T, A, R> { … }

T represents the input element.
A represents the potential mutable state object.
R represents the output that will be pushed downstream.

A gatherer is built upon four key elements:

Supplier<A> initializer();
Integrator<A, T, R> integrator();
BinaryOperator<A> combiner();
BiConsumer<A, Downstream<? super R>> finisher();

Initializer – A function that produces an instance of the internal intermediate state.
Integrator – Integrates a new element into the stream produced by the Gatherer.
Combiner – A function that accepts two intermediate states and merges them into one. Supporting parallel execution.
Finisher – A function that allows performing a final action at the end of input elements.

Among these four elements, only the integrator is mandatory because it has the role of integrating a new element into the stream produced by the Gatherer. The other elements may or may not be required, depending on the operation you intend to model, making them optional.

Creating a Gatherer

Gatherers are created using factory methods, or you can implement the Gatherer interface. Depending on the operation you want to model, you can use the overloaded variants of Gatherer.of and Gatherer.ofSequential.

var uppercaseGatherer = Gatherer.<String, String>of((state, element, downstream) 
-> downstream.push(element.toUpperCase()));

The example gatherer above calls toUpperCase on an input element of type String and pushes the result downstream. This gatherer is equivalent to the following map operation.

Stream.of("a", "b", "c", "d", "e", "f", "g")
   .map(String::toUpperCase)
   .forEach(System.out::print);

The Stream interface now includes a method called gather(), which accepts a Gatherer parameter. We can use it by passing the gatherer we created.

Stream.of("a", "b", "c", "d", "e", "f", "g")
    .gather(uppercaseGatherer) 
    .forEach(System.out::print);

Built-in Gatherers

The java.util.stream.Gatherers class is a factory class that contains predefined implementations of the java.util.stream.Gatherer interface, defining five different gatherers.

• windowFixed
  It is a many-to-many gatherer which groups input elements into lists of a supplied size, emitting the windows downstream when they are full.
• windowSliding
  It is a many-to-many gatherer which groups input elements into lists of a supplied size. After the first window, each subsequent window is created from a copy of its predecessor by dropping the first element and appending the next element from the input stream.
• fold
  It is a many-to-one gatherer which constructs an aggregate incrementally and emits that aggregate when no more input elements exist.
• scan
  It is a one-to-one gatherer which applies a supplied function to the current state and the current element to produce the next element, which it passes downstream.
• mapConcurrent
  It is a one-to-one gatherer which invokes a supplied function for each input element concurrently, up to a supplied limit. The function executes in Virtual Thread.

All of the above gatherers are stateful. Fold and Scan are very similar to the Stream reduce operation. The key difference is that both can take an input of type T and produce an output of type R, and their identity element is mandatory, not optional.

Create your own Gatherer

Let’s see how we can write our custom gatherer using a real-world scenario. Imagine you are processing a system’s log stream. Each log entry represents an event, and it is evaluated based on certain rules to determine whether it is anomalous. The rule and scenario are as follows.

• Rule: An event (log entry) is considered anomalous if it exceeds a certain threshold or contains an error.
• Scenario: If an error occurs and is immediately followed by several anomalous events (three in a row, e.g), they might be part of a failure chain. However, if a “normal” event appears in between, the chain is broken.

In this case, we can write a gatherer that processes a log stream and returns only the uninterrupted anomalous events.

INFO, ERROR, ERROR, INFO, WARNING, ERROR, ERROR, ERROR, INFO, DEBUG

Let’s assume that the object in our log stream is structured as follows.

class LogWrapper { 

    enum Level{ 
         INFO, 
         DEBUG, 
         WARNING, 
         ERROR 
    } 

   private Level level; 
   private String details;
}

The object has a level field representing the log level. The details field represents the content of the log entry.

We need a stateful gatherer because we must retain information about past events to determine whether failures occur consecutively. To achieve this, the internal state of our gatherer can be a List<LogWrapper>

static Supplier<List<LogWrapper>> initializer() { 
   return ArrayList::new; 
}

The object returned by the initializer() corresponds to the second parameter explained earlier in the type parameters of the Gatherer interface.

static Integrator<List<LogWrapper>, LogWrapper, String> integrator(final int threshold) { 

    return ((internalState, element, downstream) -> { 
        if(downstream.isRejecting()){ 
            return false; 
        } 

        if(element.getLevel().equals(LogWrapper.Level.ERROR)){ 
            internalState.add(element); 
        } else {
 
            if(internalState.size() >= threshold){ 
                internalState.stream().map(LogWrapper::getDetails).forEach(downstream::push); 
            } 
            
            internalState.clear(); 
        } 

        return true; 
    }); 
}

The integrator will be responsible for integrating elements into the produced stream. The third parameter of the integrator represents the downstream object.

We check whether more elements are needed by calling the isRejecting(), which determines if the next stage no longer wants to receive elements. If this condition is met, we return false.

If the integrator returns false, it performs a short-circuit operation similar to intermediate operations like allMatch, anyMatch, and noneMatch in the Stream API, indicating that no more elements will be integrated into the stream.

If isRejecting() returns false, we check whether the level value of our stream element, LogWrapper, is ERROR. If the level is ERROR, we add the object to our internal state. If the level is not ERROR, we then check the size of our internal state.

If the size exceeds or is equal to the threshold, we push the LogWrapper objects stored in the internal state downstream. If not, we don’t.

I want you to pay attention to two things here. Pushing an element downstream or not, as per the business rule, is similar to what filter() does. Accepting an input of type LogWrapper and producing an output of type String is similar to what map() does.

After that, according to our business rule, we clear the internal state and return true to allow new elements to be integrated into the stream.

static BinaryOperator<List<LogWrapper>> combiner() { 
    return (_, _) -> { 
        throw new UnsupportedOperationException("Cannot be parallelized"); 
    }; 
}

To prevent our gatherer from being used in a parallel stream, we define a combiner, even though it is not strictly required. This is because our gatherer is inherently designed to work as expected only in a sequential stream.

static BiConsumer<List<LogWrapper>, Downstream<? super String>> finisher(final int threshold) { 
    return (state, downstream) -> { 
        if(!downstream.isRejecting() && state.size() >= threshold){ 
            state.stream().map(LogWrapper::getDetails).forEach(downstream::push); 
        } 
    }; 
}

Finally, we define a finisher to push any remaining stream elements that have not yet been emitted downstream.

If isRejecting() returns false and the size of the internal state is greater than or equal to the threshold, we push the LogWrapper objects stored in the internal state downstream.

When we use this gatherer on data

ERROR,   Process ID: 191, event details ...
INFO,    Process ID: 216, event details ...
DEBUG,   Process ID: 279, event details ...
ERROR,   Process ID: 312, event details ...
WARNING, Process ID: 340, event details ...
ERROR,   Process ID: 367, event details ...
ERROR,   Process ID: 389, event details ...
INFO,    Process ID: 401, event details ...
ERROR,   Process ID: 416, event details ...
ERROR,   Process ID: 417, event details ...
ERROR,   Process ID: 418, event details ...
WARNING, Process ID: 432, event details ...
ERROR,   Process ID: 444, event details ...
ERROR,   Process ID: 445, event details ...
ERROR,   Process ID: 446, event details ...
ERROR,   Process ID: 447, event details ...

similar to the one above, we get the following result.

Process ID: 416, event details …
Process ID: 417, event details …
Process ID: 418, event details …
Process ID: 444, event details …
Process ID: 445, event details …
Process ID: 446, event details …
Process ID: 447, event details …

The code example is accessible in the GitHub repository.

Conclusion

Gatherers is a new and powerful API that enhances the Stream API by modeling intermediate operations and allowing the definition of custom intermediate operations. A gatherer supports the features that intermediate operations have, it can push any number of elements to the resulting stream, maintain an internal mutable state, short-circuit a stream, delay consumption, be chained, and execute in parallel.

References

• JEP 485
• cr.openjdk.org

Virtual threads were first introduced as a preview API in JDK 19, delivered to the second preview round in JDK 20, and are expected to become standard with JDK 21. Until now, you may have read many articles and listened to many presentations about virtual threads.

So, assuming you are familiar with the basic concepts, I would like to give a brief summary instead of repeating in detail what you’re known in this article and then turn the spotlight on the Continuations that allow the Java platform to achieve a more fine-grained concurrency model.

A brief summary

With Loom we now have two types of threads: Platform thread and virtual thread. While a platform thread is an instance of java.lang.Thread that’s implemented in the traditional way, as a thin wrapper around an OS thread, a virtual thread is an alternative implementation of java.lang.Thread that’s not tied to a particular OS thread.

The fact that platform threads are a thin wrapper around OS threads means that each traditional Java thread opens a new native thread on the OS level, thus establishing a one-to-one relationship(1:1 scheduling) with the OS threads.

By contrast, a virtual thread is mounted to a platform thread(therefore it is called a carrier thread) by the JVM, thus establishing a many-to-one relationship(M:N scheduling) between virtual threads and platform threads.

A virtual thread can remain mounted to the carrier thread until it encounters a blocking operation, and is unmounted by the JVM when a blocking operation occurs.

This means that the blocking code running in the virtual thread is not blocking the kernel thread. In this way, many virtual threads can run on the same OS thread. Because they are managed by the JVM instead of OS, the overhead of task-switching of virtual threads is close to zero.

There are two cases where a blocking operation doesn’t unmount the virtual thread from the carrier thread: 1) When the virtual thread executes a synchronized block or method code. 2) When it calls a native method or a foreign function. In these cases, the virtual thread is pinned to the carrier thread.

In addition, platform threads carry megabyte-scale chunks of memory to manage the Java call stack, while the memory footprint for virtual threads starts at just a few hundred bytes, and their stack frames are stored in the Java heap rather than in memory allocated by the OS.

All of these are what make virtual threads cheap. Therefore, a concurrent application can use hundreds of thousands or even millions of virtual threads.

Continuations

In Project Loom, the word continuation will mean a delimited continuation also sometimes called a coroutine. It can be thought of as sequential code that may suspend or yield execution at some point by itself and can be resumed by a caller.

I mentioned above that the virtual threads are mounted and unmounted by the JVM, now let’s make this behavior observable.

class Task implements Runnable
{
   private final int taskNumber;


   public Task(int taskNumber) {
       this.taskNumber = taskNumber;
   }


   @Override
   public void run() {
       if(taskNumber == 1) {
           System.out.println(Thread.currentThread());
       }
       try {
           Thread.sleep(Duration.ofMillis(20));
       } catch (InterruptedException e) {
           throw new RuntimeException(e);
       }
       if(taskNumber == 1) {
           System.out.println(Thread.currentThread());
       }
   }
}

The Task object is seen above responsible for both putting the task to sleep for 20ms and if the variable taskNumber has a value of 1 printing the name of the current thread before and after this operation.

var virtualThreads = IntStream.rangeClosed(1, 10)
       .mapToObj(taskNumber ->
               Thread.ofVirtual().unstarted(new Task(taskNumber)))
       .toList();


virtualThreads.forEach(Thread::start);
for(Thread t :virtualThreads){
   t.join();
}

When the Task object is passed to virtual threads for execution, we will get an output similar to the following.

VirtualThread[#21]/runnable@ForkJoinPool-1-worker-1

VirtualThread[#21]/runnable@ForkJoinPool-1-worker-7

From the output, we understand that the same virtual thread jumps from one platform thread it was running in at the beginning to another when it comes back from sleeping.

This is what happens in the mount and unmount process and at the core of this, there is a Continuation object.

// JDK core code

public Continuation(ContinuationScope scope, Runnable target) {
   this.scope = scope;
   this.target = target;
}

When we examine the VirtualThread class, we see that a virtual thread is implemented as a continuation that is wrapped as a task and scheduled by a java.util.concurrent.Executor.

// JDK core code

private static final ContinuationScope VTHREAD_SCOPE = new ContinuationScope("VirtualThreads");

// scheduler and continuation
private final Executor scheduler;
private final Continuation cont;
private final Runnable runContinuation;

    … 

VirtualThread(Executor scheduler, String name, int characteristics, Runnable task) {
    super(name, characteristics, /*bound*/ false);
    Objects.requireNonNull(task);

    // choose scheduler if not specified
    if (scheduler == null) {
        Thread parent = Thread.currentThread();
        if (parent instanceof VirtualThread vparent) {
                scheduler = vparent.scheduler;
            } else {
                scheduler = DEFAULT_SCHEDULER;
            }
        }

        this.scheduler = scheduler;
        this.cont = new VThreadContinuation(this, task);
        this.runContinuation = this::runContinuation;
}

private static class VThreadContinuation extends Continuation {
    VThreadContinuation(VirtualThread vthread, Runnable task) {
        super(VTHREAD_SCOPE, () -> vthread.run(task));
    }

    ...        
}

private void runContinuation() {
        
    ...
    
    try {
        cont.run();
    } finally {
        if (cont.isDone()) {
            afterTerminate(/*executed*/ true);
        } else {
            afterYield();
        }
    }
}

As can you see above, when a virtual thread is created, a continuation object is also created to represent its execution state. This object allows a virtual thread to save its current execution state and later resume from that state, typically on a different thread.

Let’s look at a pure continuation example for a better grasp.

public class ContinuationExample
{
   public static void main(String[] args) {


       var scope = new ContinuationScope("MyScope");


       var continuation = new Continuation(scope, () -> {
           System.out.println("Continuation running");
           Continuation.yield(scope);
           System.out.println("Continuation still running");
       });


       continuation.run();
   }
}

Notice that continuations aren’t exposed as a public API because it is a low-level primitive. They should only be used by library authors to build higher-level APIs such as virtual threads, the builder API to run virtual threads, etc.

When executing the above example, we will get the following output.

Continuation running

When we change the continuation.run(); line as below and run the code again, we get a different output.

while (!continuation.isDone()){
   continuation.run();
}

Continuation running

Continuation still running

As can be seen from the output and mentioned above, a continuation is an object which may suspend or yield execution at some point by itself and, when resumed or invoked, carries out the rest of some computation.

When a continuation suspends, control is passed outside of the continuation, and when it is resumed, control returns to the last yield point, with the execution context up to the entry point intact.

That is what happens when a virtual thread was suspended and later resumed. Parking (blocking) virtual thread results in yielding its continuation, and unparking it results in the continuation being resubmitted to the scheduler.

To provide this behavior, nearly all blocking points in the JDK have been refactored.

The needed stack frames of the virtual thread are temporarily copied from the heap to the stack of the carrier thread during the process of mounting and they are moved back to the heap during the process of unmounting.

Thanks to this behavior, the ability to capture, store and resume call stacks that are not part of kernel threads has been added to the JVM.

Moving the stack frames from the heap to the stack of the carrier thread(i.e to main memory) and vice-versa is the cost of blocking a virtual thread. This cost is pretty cheap compared to the cost of blocking platform threads.

Because the Java runtime can explicitly control when a virtual thread is suspended and resumed and can schedule other virtual threads to run in the meantime, this structure built on Continuations allows a more fine-grained concurrency model.

Conclusion

With virtual threads, Project Loom promise that Java developers could write highly scalable applications that made utilize the hardware optimally, without changing their habits.

This promise is fulfilled by the cheap nature of virtual threads, each associated with carrier threads rather than an OS thread. A virtual thread has a continuation object that represents its execution state.

Blocking a virtual thread results in yielding its continuation and unparking it results in the continuation being resubmitted to the scheduler. Because the Java runtime can explicitly control when a virtual thread is suspended and resumed, that structure allows a more fine-grained concurrency model for Java.

References

• Loom Proposal
• JEP 444: Virtual Threads
• Loom Wiki

After moving to the six-month release cadence, the Java language has entered a rapid development process.

While the process introduces many new features, these new features sometimes cause updates to existing APIs and sometimes result in the development of new APIs.

An example of the second is Scoped Values which has been included in the JDK since Java 20 as an incubator API.

Why were Scoped Values proposed?

Virtual threads became a part of JDK as a preview feature in Java 19.

They are a lightweight implementation of Java threads and promise dramatically reduce the effort of writing, maintaining, and observing high-throughput concurrent applications.

Virtual threads are cheap by nature. This means that thousands or even millions of virtual threads can be used.

On the other hand, ThreadLocal API has been widely used since Java 1.2 for object sharing between application components without resorting to method arguments.

At this point, given the aforementioned nature of virtual threads, some problems arise.

What is the problem?

The ThreadLocal API supports a fully general model of communication that allows any code to mutate the data by calling related methods(eg set(), remove()) at any time, so these variables are mutable.

In many scenarios, however, Java developers need to work with immutable objects to be passed throughout a process.

The mentioned communication model of ThreadLocal API isn’t conducive to such transmission, i.e., the simple one-way transmission of immutable data from one application component to another.

In addition, when a thread-local variable is written via the set() method it is retained for the lifetime of the thread, or until code in the thread calls the remove() method.

This means that per-thread data is often retained for longer than necessary.

Hence when using large numbers of threads, or when there is an inheritance relationship between the threads the overhead of thread-local variables may be even higher.

Considering this described design flaws of thread-local variables, the drawbacks of using them with tens of thousands or even millions of virtual threads are obvious.

The Scoped Values API proposed to overcome the aforementioned potential problems. They should be preferred to thread-local variables, especially when using large numbers of virtual threads.

What are Scoped Values and how to use them?

The Scoped Values API allows us to store and share immutable data for a bounded lifetime and only the thread that wrote the data can read it.

A scoped value is a variable of type ScopedValue and is typically declared as a static final field like a thread-local variable so it can easily be reached from many components.

public class PaymentGateway
{
    public static final ScopedValue<PaymentRequest> PAYMENT_REQUEST = ScopedValue.newInstance();
   
    //...
}

Once declared, a scoped value is used as shown below.

import static org.jugistanbul.PaymentGateway.PAYMENT_REQUEST;

public class PaymentProcessor
{
   public static void createPaymentTask(final PaymentRequest request){
       ScopedValue.where(PAYMENT_REQUEST, request)
                   .run(() -> PaymentService.getPaidByCreditCard());
   }
}

In the code snippet above, a scoped value and the object to which it is to be bound are passed to the where() method as a key and a value argument.

The run() call binds the scoped value to the current thread by providing a specific incarnation of it. That makes the scoped value accessible in getPaidByCreditCard() method.

In this way, notice that the where() and run() methods together provide a one-way sharing of data from one component to another.

The where() is a method of the Carrier class which is one of the inner classes of ScopedValues. It maps scoped values as keys, to values and returns a new Carrier hence the where() method can be chained.

public class PaymentService
{
   public static void getPaidByCreditCard(){
       ValidationService.checkValidity();
}

public class ValidationService
{
   public static void checkValidity(){
       PaymentRequest paymentRequest = PaymentGateway.PAYMENT_REQUEST.get();
       checkNumber(paymentRequest.cardNumber());
   }
}

The bound scoped value can be read via the value’s get() method during the lifetime of the run() method, the lambda expression, or any method called directly or indirectly from that expression.

After the run() method finishes, the binding is destroyed or reverts to its previous value when previously bound, in the current thread. That is where the question of “What is the meaning of scoped?” is answered.

The value’s get() call after destroyed bindings will throw an exception. You can use ScopedValue.isBound() to check if it has a binding for the current thread.

When a scoped value is written once, then is immutable, which means a caller using a scoped value can reliably pass it as a constant value to its callees in the same thread.

However, this does not mean that one callee can’t share the same scoped value with a different value with its own callees in the thread. In such cases the ScopedValue API allows a new binding to be established for nested calls, this is called rebinding.

Let’s say we have a service where we print the payment information after charging the payment.

We can use the current PaymentRequest instance bound to the current thread for the print process but we don’t want to share sensitive information without masking it such as card number, cardholder name, etc, with the service and any method called directly or indirectly from it. This is where rebinding comes to our help.

public class PaymentService
{
   public static void getPaidByCreditCard(){
       ValidationService.checkValidity();
       getPaid();
       ScopedValue.where(PaymentGateway.PAYMENT_REQUEST, maskedPaymentRequest)
       .run(() -> PrintService.printPaymentInfo());
   }
}

The return type of the run() method is void. If the printPaymentInfo() method was returning a value, we can prefer the call() method which calls a value-returned operation to handle the returned value.

In the above code snippet, the scoped value that was initially bound in createPaymentTask() method, rebinding to a new instance of PaymentRequest in getPaidByCreditCard() method. Hence, during the lifetime of the run method, the accessible object is only this new PaymentRequest instance.

In short, the Scoped Values API doesn’t allow a method body to change the binding seen by the method itself(it has no method like set()) but allows it to change the binding seen by its callees. This guarantees a bounded lifetime for sharing of the new value.

As soon as the run() call finishes in the getPaidByCreditCard() method, the binding reverts to its previous value.

How to enable cross-thread sharing?

Java developers can create their own threads for many reasons. In such a case, if the code running in a child thread needs to access the scoped value how can access it?

The answer is that use Structured Concurrency which enables cross-thread sharing.

Structured Concurrency has been included in the JDK since Java 19 as an incubator API. It treats multiple tasks running in different threads as a single unit of work.

The principal class of the API is StructuredTaskScope and scoped values are automatically inherited by all child threads created via it.

public static void getPaidByCreditCard() throws InterruptedException, ExecutionException {

    PaymentRequest request = PaymentGateway.PAYMENT_REQUEST.get();

    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
        Future<Boolean> validation  = scope.fork(() -> ValidationService.checkValidity());
        Future<Boolean> account = scope.fork(() -> UserService.accountChecker());
            
        scope.join();
        scope.throwIfFailed();

        if(validation.resultNow() && account.resultNow()){
            getPaid();
            ScopedValue.where(PaymentGateway.PAYMENT_REQUEST, request.copyOf())
                       .run(() -> PrintService.printPaymentInfo());
        }
    }
}

The fork() method of StructuredTaskScope starts a new thread to run the given task. In the above code snippet it is called to run the ValidationService.checkValidity() and UserService.accountChecker() methods concurrently, in their own virtual threads.

StructuredTaskScope.fork() ensures that the binding of the scoped value made in the parent thread code is automatically visible to the child thread. This is an example of scoped value inheritance and it provides enables cross-thread sharing.

Because, unlike thread-local variables, there is no copying of a parent thread’s scoped value bindings to the child thread, cross-thread sharing occurs with minimal overhead.

I created a repository for the scenario discussed in this article, which you can examine.

Conclusion

The Scoped Values API allows storing and sharing immutable data for a bounded lifetime.

It is recommended to be used to overcome potential problems that may arise when using thread-local variables, especially with large numbers of virtual threads.

Scoped Values must be used with Structured Concurrency to enable cross-thread sharing.

Cross-thread sharing occurs with minimal overhead because no copying of a parent thread’s scoped value bindings to the child thread.

Note that Scoped Values and Structured Concurrency are still incubator APIs, so they may still be subject to fundamental changes.

References

• Scoped Values
• Structured Concurrency
• Virtual Threads

After the decision to use Azure Cloud Storage for the shared resources at the project I was involved in, by reviewing the SDK, I explored how clients can have limited access to resources. We develop the project with Spring Boot and during my research, I found that the resources are not up-to-date for the current Java SDK and Spring Boot version and the tutorials/examples contain many ceremonies and boilerplates.

I wrote this article to share my experience and show how to use Azure Storage Blob SDK with more concise and readable code.

What is Azure Blob Storage?

Azure Blob Storage is Microsoft’s object storage solution that allows you to store a massive amount of unstructured data. Azure Storage Service is a good solution for needs such as streaming video and audio, serving images or documents directly to a browser, etc, as they are accessible using REST APIs.

How to Access Blobs and Serve with Spring Boot?

Since the target audience of this article is users with the service, I will not talk about some prerequisites such as how to create an Azure Storage account and blob containers, etc. In addition, we usually write the access URLs of the stored resources to the database in production but to avoid complexity, I will not include these steps in my example.

As a first step, let’s examine the dependencies we will add to our project to configure and manage the Azure Blob service.

Dependencies

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>azure-spring-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>azure-spring-boot-starter-storage</artifactId>
</dependency>

The first artifact is for Spring Boot Starters of Azure services and helps Spring Boot developers to adopt Azure services. It supports Spring Boot 2.1.x, 2.2.x, and 2.3.x.

The second provides a starter to auto-configure Azure Blob Storage in your Spring project and allows you to interact with Azure Blob Storage using Spring programming model.

Configuration

The azure-spring-boot-starter-storage dependency requires us to provide values of storage account name and key. In addition to these two values, since we will be using the storage blob resources, we will also provide the endpoint value, which is optional, and connection string value, to be able to inject it at runtime when creating a blob client. You can be found the account key and connection string under Azure Portal ==> Storage Account page ==> Access keys and blob service endpoint URL Azure Portal ==> Storage Account page ==> Endpoints.

azure.storage.accountName=${yourAccontName}
azure.storage.accountKey=${yourAccontKey}
azure.storage.blob-endpoint=${yourAccountBlobEndpoint}
azure.storage.connection-string=${yourAccontConnectionString}

Code

For the service we will create, we define a default method that returns a BlobClient in the interface that must be implemented by classes that want to access the Storage Account. In order to obtain the client, we need the connection string, the container name, and the name of the resource to be accessed. Let's explain for readers who are not storage service users. Our blobs are stored in containers, a container can think like a directory on the filesystem holding a set of files.

default BlobClient getBlobClient(final String connectionString, final String containerName, final String blobName){

    return new BlobClientBuilder()
            .connectionString(connectionString)
            .containerName(containerName)
            .blobName(blobName)
            .buildClient();
}

We will call this method in the implementer class for operations such as access and upload to blobs.

public String generateAccessUrlWithSAS(final String containerName, final String blobName,
               final int amount, final ChronoUnit chronoUnit) {
    var blobContainerSasPermission = 
           new BlobContainerSasPermission().setReadPermission(true);
    var builder = 
           new BlobServiceSasSignatureValues(OffsetDateTime.now()
.plus(amount, chronoUnit),
            blobContainerSasPermission).setProtocol(SasProtocol.HTTPS_ONLY);

    var client = getBlobClient(connectionString, containerName, blobName);

    return client.exists()?String.format("https://%s.blob.core.windows.net/%s/%s?%s", client.getAccountName(),
            client.getContainerName(), blobName, client.generateSas(builder)):"Resource not found";
}

In the generateAccessUrlWithSAS method, we will return access URLs of our resources with the shared access signature(SAS) token to our clients. SAS is a URI that grants restricted access rights to Azure Storage resources. We will distribute that URI to our clients to grant them access to our resources for a specified period of time, with a specified set of permissions. For that, we first configure the BlobContainerSasPermission object. The new BlobContainerSasPermission() initializes a BlobContainerSasPermission object with all fields set to false. We give our clients read permission by setReadPermission(true) on the object.

Then we configure the BlobServiceSasSignatureValues object with its constructor that accepts two parameters of type OffsetDateTime and BlobContainerSasPermission. The first parameter defines the expiry time for access and the second permissions.

Notice that the generateAccessUrlWithSAS method has a ChronoUnit type parameter. By passing the ChronoUnit type as the second argument to the plus method of OffsetDateTime, we allowed the user to define declaratively the time specified by the amount parameter in seconds, hours, day, or another type of their choice. We pass the BlobContainerSasPermission object that we just configured as the second argument to theBlobServiceSasSignatureValues object.

In the final step, we obtain the blob client and return the access URL to be valid for the time defined in the parameters passed to the method if the resource exists, if not, we notify the client that the resource is not found.

That is all.

Along with the above method, I have created a repository including the scenario of uploading the specified resource into the storage account, you can examine it.

Conclusion

Azure Blob Storage is Microsoft’s object storage solution that allows you to store a massive amount of unstructured data. It is a good solution for needs such as streaming video and audio, serving images or documents directly to a browser, etc, as they are accessible using REST APIs. Under the com.azure.storage.blob.sas package, there are suitable objects to generate SAS tokens with more concise and readable coding without boilerplate and to meet the grant limited access need.

This article was published in Java Advent Calendar on December 6, 2020

Many businesses are looking to take advantage of Elasticsearch’s powerful search capabilities using it in close relationship with existing relational databases. In this context, it’s not rare to use Elasticsearch as a caching layer. At this point, a basic and important need arises which is synchronizing Elasticsearch with the database.

Roughly, the steps below are followed for synchronization:

• A field is added that contains the update or insertion time to the table that will be kept synchronized with Elasticsearch
• A field is added that contains a boolean for marking record deletion to the table that will be kept synchronized with Elasticsearch
• Both the two fields are used in a query that is periodically executed on the table by a scheduler to request the only records that have been modified, inserted, or deleted since the last execution of the scheduler
• If there are newly added, updated, and deleted records, the business logic is invoked to perform CRUD operations both on Elasticsearch and Database(when there are records deleted)
• Scheduler runtime is stored for use in the next execution period

This pattern has some assumptions and disadvantages. Firstly, it has an estimate of how often the database is updated and runs the scheduler accordingly. The Database may be updating more frequently than assumed. In this case, users are likely to view stale data. When it’s the opposite we waste resources because one of the main purposes of using the cache layer is to reduce I/O operations on the database.

Another additional overhead for situations where you’re not returning results from the cache is that database queries should be written to exclude records marked as “deleted“.

HIBERNATE SEARCH

Hibernate Search is a library that allows keeping your local Apache Lucene indexes or ElasticSearch cluster in sync with your data that extracts from Hibernate ORM based on your domain model. You can get this ability for your application by a few settings and annotations.

BASE COMPONENTS

Hibernate Search is based on two key components. Since these key components are directly related to the efficient use of the library, let’s take a closer look at them now.

MAPPER

The mapper component maps your entities to a Lucene index and provides some APIs to perform indexing and searching. The mapper is configured both through annotations on the entities and through configuration properties which are key-value based.

BACKEND

The backend is the abstraction over the full-text engines. It implements generic indexing and searching interfaces for use by the mapper and delegates to the engine you chose to use in your application for instance Lucene library or a remote Elasticsearch cluster. The mapper configures the backend partly by telling which indexes must exist and what fields they must have. In addition, the backend is configured partly also through configuration properties.

For providing the following main features, the mapper and backend work together.

• Mass indexing to import data from a database
• Automatic indexing to keeping indexes in sync with a database
• Searching to query an index

DEPENDENCIES

In order to use Hibernate Search, you will need at least two direct dependencies. One of these dependencies is related to the mapper component.

<dependency>
   <groupId>org.hibernate.search</groupId>
   <artifactId>hibernate-search-mapper-orm</artifactId>
   <version>6.0.0.CR2</version>
</dependency>

The other one is related to the backend component and depends on your single or multiple node choice. For Lucene:

<dependency>
   <groupId>org.hibernate.search</groupId>
   <artifactId>hibernate-search-backend-lucene</artifactId>
   <version>6.0.0.CR2</version>
</dependency>

The Lucene backend allows indexing of the entities in a single node and storing these indexes on the local filesystem. The indexes are accessed through direct calls to the Lucene library, without going through the network. Hence, the Lucene backend is only relevant to single-node applications. So if you have a single-node application you can prefer the Lucene backend.

For Elasticsearch:

<dependency>
   <groupId>org.hibernate.search</groupId>
   <artifactId>hibernate-search-backend-elasticsearch</artifactId>
   <version>6.0.0.CR2</version>
</dependency>

The Elasticsearch backend allows indexing of the entities on multiple nodes and storing these indexes on a remote Elasticsearch cluster. These indexes are not tied to the application, therefore, accessed through calls to REST APIs.

Note that you can use both Lucene and Elasticsearch backends at the same time.

CONFIGURATION

The configuration properties of Hibernate Search can be added to any file from which Hibernate ORM takes its configuration because they are sourced from Hibernate ORM.

These files can be

• hibernate.properties
• hibernate.cfg.xml
• persistence.xml

In addition to these files, application properties files of Java runtimes such as Quarkus and Spring can also be used for configuration when you use them.

Hibernate Search provides sensible defaults for all configuration properties but there are few basic configuration parameters that you cannot avoid explicitly setting for your application in some cases.

hibernate.search.backend.directory.root This setting is about where indexes will be stored in the file system. It works when you use the Lucene backend. It will store indexes in the current working directory by default

• hibernate.search.backend.hosts This setting is about defining the Elasticsearch host URL, so it works when you use the Elasticsearch backend. By default, the backend will attempt to connect to localhost:9200
• hibernate.search.backend.protocol This setting is about defining the protocol. You use this setting explicitly when you need to use https because its default value is http
• hibernate.search.backend.username and hibernate.search.backend.password These settings are about defining the username and password for basic HTTP authentication
• hibernate.search.backend.analysis.configurer This setting is about defining a bean reference pointing to the analyzer implementation. You use this setting when you need to custom analysis

CODING TIME

Let’s assume that JUG Istanbul uses a meetup app for meetings organized by itself and the data is stored in a relational database. Their domain models contain an event and host entity.

Adding a few settings to the application and a few annotations to the entities will be sufficient to take advantage of Elasticsearch’s powerful search capabilities via Hibernate Search. The entities are seen as follows.

Note: As the reader is assumed to be familiar with the basic concepts of Elasticsearch, these concepts will not be explained in detail.

@Entity
@Indexed //(1)
public class Host
{
    @Id
    @GeneratedValue
    @GenericField //(2)
    private int id;

    @KeywordField //(3)
    private String firstname;

    @KeywordField
    private String lastname;

    @FullTextField(analyzer = "english") //(4)
    private String title;

    @OneToMany(mappedBy = "host", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
    @IndexedEmbedded //(5)
    private List<Event> events;

1) @Indexed annotation registers the Host entity for indexing by the full-text search engine i.e Elasticsearch.

2) @GenericField annotation maps the id field to an index field.

3) @KeywordField annotation maps the firstname and lastname fields as a non-analyzed index field, which means that the fields are not tokenized.

4) @FullTextField annotation maps the title field as a specifically full-text search field to an index field. In addition, it defines an analyzer named “english” to gain capabilities like make matches implicitly on words (“tokens“) instead of the full string and return documents consultant while searching for consultation by tokenizing and filtering the string.

5) @IndexedEmbedded annotation includes the associated Event entities into the Host index. The main benefit of this annotation is that it can automatically re-index Host if one of its events is updated, thanks to the bidirectional relation.

@Entity
@Indexed
public class Event
{
    @Id
    @GeneratedValue
    @GenericField
    private int id;

    @FullTextField(analyzer = "english")
    private String name;

    @ManyToOne
    @JsonIgnore
    private Host host;
}

These are our entities, so let’s look at how to perform search and CRUD operations on these entities.

@GetMapping(path = "/search/event/{name}", produces = "application/json")
    public List<Event> searchEventsByName(@PathVariable("name") String name){
        SearchResult<Event> result = searchSession.search(Event.class)
                .where( f -> f.simpleQueryString()
                        .field("name")
                        .matching(name))
                .fetch(20);

        logger.info("Hit count is {}", result.total().hitCount());
        return result.hits();
    }

    @GetMapping(path = "/search/host/name/{name}", produces = "application/json")
    public List<Host> searchHostsByName(@PathVariable("name") String name){
        SearchResult<Host> result = searchSession.search(Host.class)
                .where( f -> f.simpleQueryString()
                        .fields("firstname", "lastname")
                        .matching(name))
                .fetch(20);

        logger.info("Hit count is {}", result.total().hitCount());
        return result.hits();
    }

    @GetMapping(path = "/search/host/title/{title}", produces = "application/json")
    public List<Host> searchHostsByTitle(@PathVariable("title") String title){
        SearchResult<Host> result = searchSession.search(Host.class)
                .where( f -> f.simpleQueryString()
                        .fields("title")
                        .matching(title))
                .fetch(20);

        logger.info("Hit count is {}", result.total().hitCount());
        return result.hits();
    }

    @GetMapping(path = "/search/events", produces = "application/json")
    public List<Event> allEvents(){
        SearchResult<Event> result = searchSession.search(Event.class)
                .where( f -> f.matchAll())
                .fetch(20);

        logger.info("Hit count is {}", result.total().hitCount());
        return result.hits();
    }

    @GetMapping(path = "/search/hosts", produces = "application/json")
    public List<Host> allHosts(){
        SearchResult<Host> result = searchSession.search(Host.class)
                .where( f -> f.matchAll())
                .fetch(20);

        logger.info("Hit count is {}", result.total().hitCount());
        return result.hits();
    }

    @Transactional
    @PostMapping(path = "/event/add", consumes = "application/json", produces = "application/json")
    public Event addEvent(@RequestBody Event event){
        entityManager.persist(event);
        return event;
    }

    @Transactional
    @PostMapping(path = "/event/update", consumes = "application/json", produces = "application/json")
    public Event updateEvent(@RequestBody Event event){
        entityManager.merge(event);
        return event;
    }

    @Transactional
    @PostMapping(path = "/host/add", consumes = "application/json", produces = "application/json")
    public Host addHost(@RequestBody Host host){
        entityManager.persist(host);
        return host;
    }

    @Transactional
    @PostMapping(path = "/host/update", consumes = "application/json", produces = "application/json")
    public Host updateHost(@RequestBody Host host){
        entityManager.merge(host);
        return host;
    }

    @Transactional
    @DeleteMapping(path = "/event/delete/{id}", produces = "text/plain")
    public String deleteEventById(@PathVariable("id") int id){
        Event event = entityManager.find(Event.class, id);
        entityManager.remove(event);
        return String.join(" : ", "Removed", event.toString());
    }

When you look at the addEvent, updateEvent, and deleteEvent methods, you won’t notice any difference from the standard JPA usage. The difference is seen in methods such as searchEventsByName and searchHostsByName. In these methods, indices are queried over the Hibernate Search session which is obtained from the injected entity manager by setting the “WHERE” clause.

In this GitHub repository that shows you how to use Hibernate Search with Spring and Quarkus Java runtimes, you can find other details of this example such as configuration, mass indexing, and custom analyzer usage.

CONCLUSION

Today, the use of full-text search engines such as Elasticsearch as a cache is widespread. In that case, it is essential to keep Elasticsearch synchronized with the database. Hibernate Search meets this requirement elegantly. It indexes your domain model with the help of a few annotations and keeps your local Apache Lucene indexes or ElasticSearch cluster in sync with your data that extracts from Hibernate ORM based on your domain model. While it provides these facilities, it does not distract the developer from the familiar syntax.

REFERENCES

Hibernate Search Reference

GraalVM is a high-performance runtime that supports additional programming languages and execution modes but the main thing that makes it popular is a technology to ahead-of-time compile Java code to a standalone executable called native image.

Why are Native Image Configuration Files Needed?

As every rose has it’s a thorn, although the native image is an exciting technology, it has some limitations due to the nature of ahead-of-time compilation. The native image builder statically analyzes all classes of the application and their dependencies to determine which classes and methods are reachable during the application execution. This is an optimization process and it's executed according to the closed-world assumption that all application classes need to be known at native image generation time so that the static analysis can process them.

On the other hand, in the open-world approach, Java developers can look up classes, methods, and fields with their names and access/invoke them by Java Reflection. At this point, a clear conflict arises between the closed-world assumption and the open-world approach. However, the native image builder tries to resolve the target elements in the static analysis time mentioned above to detects calls to the Reflection API but in all cases, it cannot be successful.

This is the reason GraalVM needs configuration files to use at native image build time for features that follow the open-world approach, such as Dynamic Class Loading, Dynamic Proxy, Reflection, etc.

Tracing Agent

It could be so easy to prepare the configuration files from scratch for the above-mentioned features when we do not use 3rd party libraries in our application. However, it is an undeniable fact that we needed and used 3rd party libraries widely in real-world applications.

Let’s think about the difficulty of manual providing configuration files from scratch when using 3rd party libraries with an example. Suppose we have an application that consumes a Kafka topic. The application uses explicitly some classes of the Kafka client depending on record types due to Deserializing need and we know these classes must be defined in the configuration file for the native image generation process. However, other classes can also be accessed via reflection by the client under the hood for consumption and the same need. It is not easy to detect these classes always that are used implicitly from our point of view and this difficulty makes manual preparing the configuration troublesome and error-prone when you want to generate a native image from the application.

Fortunately, thanks to the tracing agent, preparing these configuration files becomes easier and more convenient. The agent tracks all usages of dynamic features of execution on a regular Java VM and creates configuration files in the directory you defined at the command-line.

How Can I Use?

You can enable the agent on the command line of the GraalVM java command.

$GRAAL_HOME/bin/java -agentlib:native-image-agent=config-output-dir=/path/to/config-dir/ -jar /path/to/jar-dir/

Notice that, -agentlib option must be specified before the -jar option(similarly before the class name) and any other application parameters in the java command line.

During execution, the agent intercepts all calls related to the limitations mentioned earlier, and after the JVM process terminates, it generates the configuration files based on the calls it interrupts in the specified output directory. You will have the following files after execution.

• jni-config.json
• reflect-config.json
• proxy-config.json
• resource-config.json

These files are standalone configuration files in JSON format which contain all intercepted dynamic accesses. For our hypothetical example mentioned above, the contents of the reflect-config.json file would be as follows.

{
 "name":"org.apache.kafka.clients.consumer.RangeAssignor",
 "methods":[{"name":"<init>","parameterTypes":[] }]
},
{
 "name":"org.apache.kafka.common.serialization.StringDeserializer"
},
{
 "name":"org.apache.kafka.common.utils.AppInfoParser$AppInfo",
 "allPublicConstructors":true
},
{
 "name":"org.apache.kafka.common.utils.AppInfoParser$AppInfoMBean",
 "allPublicMethods":true
}

Lines unrelated to our 3rd party library have been omitted to reduce the length of the file.

In most cases, to get the most better coverage of dynamic accesses, you want to run the target application more than once with different inputs to trigger separate execution paths. In this case, you can use config-merge-dir option which augments the configuration files by adding the intercepted accesses to existing files.

Manually Inspection The Configuration Files

The developers of GraalVM suggest manual inspection of the generated configuration files because the agent observes only code that was executed. Depending on your usage scenario, it's always possible was missed some elements in the resulting configuration files. In addition, the agent isn't perfect, so it can generate non-compatible entries with the runtime environment hence you shouldn't hesitate to make changes manually on the files when the need arises.

Conclusion

GraalVM executes the native image build process according to the closed-world assumption that means all application classes need to be known at native image generation time. Hence, it needs configuration files to use at native image build time for supporting some features that follow the open-world approach, such as Dynamic Class Loading, Dynamic Proxy, Reflection, etc.

It is difficult and error-prone to manual provide configuration files from scratch when using 3rd party libraries. The tracing agent is a facilitating solution at this point. It intercepts all dynamic calls and then generates the configuration files based on the calls. Because the agent observes only code that was executed, it is most important to run the target application more than once with different inputs to trigger separate execution paths for getting better coverage of dynamic accesses.

References

GraalVM Documentation

The end-to-end testing in enterprise applications is important as long as it covers the real use cases. Therefore, even although companies focus more on integration tests, end-to-end tests are not neglected. Another common need, called System Integration Testing, present-day is that perform to verify the interactions between the modules of a software system.

To be honest, outside the dev environment(for example in CI/CD pipelines), meet all these needs is a little harder at JakartaEE(previously Java EE) compared to Spring Framework. You must provide additional dependencies and configurations because by naturally there is no built-in embedded server support.

In this article, I will try to introduce Arquillian and MicroShed test frameworks and explain how you can use them to meet the mentioned needs. You can find the example that we will discuss in this article on GitHub.

Before Started

To embody the mentioned needs we will consider a microservices example consisting of two services.

• Order Service
• Validation Service

The Order Service is responsible for the persisting of the Order Demand object from the client request body to the Database after the credit card number inside the object is verified by the Validation Service. The Validation Service is responsible for validating the credit card number that passed by the Order Service. It returns a flag about whether the number is validated or not with short info.

It can be noticed immediately, that the Validation Service does not depend on any other service or system component due to its mission. Conversely, the Order Service depends on the Validation Service and it must persist the validated object to the Database.

So we need an integration test to evaluate the compliance of the Validation Service with the specified functional requirement. As for the Order Service, we can't just do integration testing because it is dependent on other system components. We need an end-to-end test to detect defects within all layers.

For these reasons, we will use Arquillian for integration testing and MicroShed Testing for end-to-end testing.

How to Write Embedded Tests with Arquillian?

Arquillian is a testing framework for Java applications. Its main benefit is to handles the application server lifecycle for you. This facility provided by container adapters. Arquillian has many container adapters. Because the adapter depends on the application server you want to use so the details of these adapters and how to configure these are out of scope this article. You can be found more details about Arquillian Container Adapters here.

I used Liberty Managed Container Adapter with Liberty Maven plug-in in this example for managing Arquillian dependencies and the setup to Arquillian Managed Container. All these configuration details can be found on the repository.

Let’s now focus on how to write tests with Arquillian. We’ll develop test to verify the Validation Service as an endpoint and the functions of the OrderController class. The test looks like below:

@RunWith(Arquillian.class) //(1)
public class ValidationServiceIT 
{

private final Client client;
   private static final String PATH = "api/validation/{cardNumber}";

public ValidationServiceIT() {
       this.client = ClientBuilder.newClient();
       client.register(JsrJsonpProvider.class);
   }

@ArquillianResource //(2)
   private URL baseURL;

@Deployment //(3)
   public static WebArchive createDeployment() {
       final WebArchive archive = ShrinkWrap.create(WebArchive.class,
               "arquillian-validation-service.war") //(4)
               .addClasses(ValidationController.class, ValidationService.class); //(5)
       return archive;
   }

@Test
   @RunAsClient //(6)
   @InSequence(1) //(7)
   public void invalidCardNumberTest() {

final WebTarget webTarget = client.target(baseURL.toString()).path(PATH)
               .resolveTemplate("cardNumber", "hello");

final Response response = webTarget.request().get();
       final JsonObject result = response.readEntity(JsonObject.class);
       Assert.assertFalse(result.getBoolean("approval"));
   }

@Test
   @RunAsClient
   @InSequence(2)
   public void validCardNumberTest() {

final WebTarget webTarget = client.target(baseURL.toString()).path(PATH)
               .resolveTemplate("cardNumber", "12345");

final Response response = webTarget.request().get();
       final JsonObject result = response.readEntity(JsonObject.class);
       Assert.assertTrue(result.getBoolean("approval"));
   }

}

Let’s examine how this works in detail by explaining all the marked pieces.

1) Firstly, with the @RunWith annotation, we tell JUnit to run the tests using Arquillian, so JUnit runs the tests with Arquillian runner instead of the JUnit runner.

2) To avoid hardcoding define of hostname, port number, and web archive information we use the @ArquillianResource annotation and in this way retrieve the base URL(http://localhost:9090/arquillian-validation-service/, in our example).

3) We must define a method that returns a web archive to deploy our application onto the server we use(Open Liberty, in this example). The method should be annotated with @Deployment annotation(it has an attribute of testable which enables the deployment to run the tests in the managed container, use in here is redundant because its default value is true) and have public static access modifiers with no arguments. The createDeployment method fulfills these responsibilities.

4) Notice the arquillian-validation-service.war name passed as the second parameter of the ShrinkWrap.create method. You should provide a name if you don’t want a randomly generated web archive name.

5) To avoid injection failures, we must add the dependencies that our test needs because Arquillian does not simply tap the entire classpath, unlike unit tests. We can add what we need to use by addClass, addClassess, addPackages, addAsResource, addAsWebInfResourc, etc methods.

6) We use @RunAsClient annotation in invalidCardNumberTest and validCardNumberTest methods because we want to verify the Validation Service as an endpoint. The annotation indicates that test cases are to be run on the client-side, so these tests are run against the managed container.

7) To guarantee the test sequence we use @InSequence annotation.

In both invalidCardNumberTest and validCardNumberTest methods, we send card numbers by calls the baseURL + api/validation/{cardNumber} endpoint to verify card number. The test checks the validity of the numbers by the approval field of the object returned from the endpoint.

That is all. The test cases are ready to run. After execute mvn verfy command, in the console output, you can see that the tests are passed.

How to Write E2E Tests with MicroShed Testing?

Another testing framework is MicroShed for Java microservice applications. It uses Testcontainers under the hood hence your application runs inside a Docker container. The main benefit of MicroShed emerges at this point, it allows you to use your containerized application from outside the container, so it offers running true-to-production tests.

Remember that, in our example, the Order service was dependent on the Validation Service and a Database. This is exactly why we chose MicroShed for this example because it enables us to access the Validation Service and the Database in the test environment by running these components in Docker containers.

Minimum requirements for a MicroShed test are a class with @MicroShedTest annotation and an ApplicationContainer object in which access modifiers are public static.

Let’s examine our configuration and test classes.

public class AppContainerConfig implements SharedContainerConfiguration // (1)
{

private static final String IMAGE_NAME = "hakdogan/validation-service:01"; 
   private static final String SERVICE_NAME = "validation-service"; 
   private static final String POSTGRES_NETWORK_ALIASES = "postgres";
   private static final String POSTGRES_USER = "testUser";
   private static final String POSTGRES_PASSWORD = "testPassword";
   private static final String POSTGRES_DB = "orderDB";

private static final int VALIDATION_SERVICE_HTTP_PORT = 9080;
   private static final int VALIDATION_SERVICE_HTTPS_PORT = 9443;
   private static final int APPLICATION_SERVICE_HTTP_PORT = 9082;
   private static final int APPLICATION_SERVICE_HTTPS_PORT = 9445;
   private static final int POSTGRES_DEFAULT_PORT = 5432;

private static Network network = Network.newNetwork();

@Container //(2)
   public static GenericContainer validationService = new GenericContainer(IMAGE_NAME) //(3)
                   .withNetwork(network) //(4)
                   .withNetworkAliases(SERVICE_NAME) //(5)
                   .withEnv("HTTP_PORT", String.valueOf(VALIDATION_SERVICE_HTTP_PORT)) //(6)
                   .withEnv("HTTPS_PORT", String.valueOf(VALIDATION_SERVICE_HTTPS_PORT)) //(7)
                   .withExposedPorts(VALIDATION_SERVICE_HTTP_PORT) //(8)
                   .waitingFor(Wait.forListeningPort()); //(9)

@Container
   public static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>() //(10)
           .withNetwork(network)
           .withNetworkAliases(POSTGRES_NETWORK_ALIASES)
           .withUsername(POSTGRES_USER)
           .withPassword(POSTGRES_PASSWORD)
           .withDatabaseName(POSTGRES_DB)
           .withExposedPorts(POSTGRES_DEFAULT_PORT);

@Container
   public static ApplicationContainer app = new ApplicationContainer() //(11)
           .withNetwork(network)
           .withEnv("POSTGRES_HOSTNAME", POSTGRES_NETWORK_ALIASES)
           .withEnv("POSTGRES_PORT", String.valueOf(POSTGRES_DEFAULT_PORT))
           .withEnv("POSTGRES_USER", POSTGRES_USER)
           .withEnv("POSTGRES_PASSWORD", POSTGRES_PASSWORD)
           .withEnv("POSTGRES_DB", POSTGRES_DB)
           .withEnv("VALIDATION_SERVICE_HOSTNAME", SERVICE_NAME)
           .withEnv("HTTP_PORT", String.valueOf(APPLICATION_SERVICE_HTTP_PORT))
           .withEnv("HTTPS_PORT", String.valueOf(APPLICATION_SERVICE_HTTPS_PORT))
           .withExposedPorts(APPLICATION_SERVICE_HTTP_PORT)
           .withAppContextRoot("/")
           .waitingFor(Wait.forListeningPort())
           .dependsOn(validationService, postgres); //(12)
}

Let’s examine how this works in detail by explaining all the marked pieces.

1) To avoid started a new container for each class we implement SharedContainerConfiguration. In this way, multiple test classes can share the same container instances.

2) The @Container annotation is used to mark containers that should be managed by the Testcontainers. Apart from Application Container, we have defined two containers in this common configuration class for the components the Order service is dependent on, these are Validation Service and Postgresql database. Notice that the annotation used in all.

3) The IMAGE_NAME variable contains the Docker image name of the Validation Service that dockerized before.

4) We use the Network object to create custom networks because we need to communicate between the Validation Service and its dependent components. There fore, we place these components on the same network with the Application Container.

5) The SERVICE_NAME variable contains the alias name for accessing the Validation Service in the Application Container.

6–7) The HTTP_PORT and HTTPS_PORT environment variables tell the application server(Open Liberty, in this example) which ports to use. These are included before as placeholders in the server.xml file.

8) We tell the Testcontainers to expose the HTTP Port of Validation Service.

9) We tell the Testcontainers to listen to the exposed port to check whether the container is ready for use as a wait strategy.

10) We define a Postgres container with bootstrap parameters.

11) We define the application’s container. You can define it in several ways. Putting a Dockerfile in your repository or passing image name to the constructor of ApplicationContainer object as an argument or using vendor-specific adapters as a runtime option that will provide the default logic for building an application container. In this example, we use the last option by added microshed-testing-liberty dependency in pom.xml to automatically producing a testable container image. You can be found other runtime options here.

12) With that setting, we tell that the application’s container depends on the Validation Service and Postgres containers.

Let’s examine our test class. It looks like below.

@MicroShedTest //(1)
@SharedContainerConfig(AppContainerConfig.class) //(2)
@TestMethodOrder(MethodOrderer.OrderAnnotation.class) //(3)
public class SystemTest
{
   @RESTClient //(4)
   public static OrderController orderController;

@Test
   @Order(1)
   public void invalidCardNumberTest(){
       final OrderDemand order = new OrderDemand(1, 1, "", "hello");
       final Response response = orderController.saveOrder(order);
       Assert.assertEquals(false, response.readEntity(JsonObject.class).getBoolean("approval"));
   }

@Test
   @Order(2)
   public void validCardNumberTest(){
       final OrderDemand order = new OrderDemand(1, 1, "", "1234567");
       final Response response = orderController.saveOrder(order);
       Assert.assertNotNull(response.readEntity(OrderDemand.class).getId());
   }
  
   @Test
   @Order(3)
   public void getAllOrderTest(){
       final Response response = orderController.getAllOrders();
       final List<OrderDemand> list = response.readEntity(List.class);
       Assert.assertFalse(list.isEmpty());
   }

@Test
   @Order(4)
   public void getAllOrderByProductIdTest(){
       final Response response = orderController.getAllOrdersByProductId(1);
       final List<OrderDemand> list = response.readEntity(List.class);
       Assert.assertFalse(list.isEmpty());
    }
}

Let’s examine how this works in detail by explaining all the marked pieces.

1) We indicate with the annotation that the test class uses MicroShed Testing.

2) We define our shared configuration to use by the test class.

3) MicroShed Testing runs with JUnit Jupiter. We define ordering method with the TestMethodOrder annotation to guarantee the test sequence.

4) The annotation identifies an injection point for a JAX-RS REST Client. Any method calls to the injected object will be translated to an equivalent REST request via HTTP. The annotated field must be public static and non-final.

In both invalidCardNumberTest and validCardNumberTest methods we call api/order/save endpoint via orderController reference that annotated with @RESTClient. This endpoint triggers the validation process by calling the Validation Service then persists the object transmitted to it to the Database with request body if the card number is valid.

In both getAllOrderTest and getAllOrderByProductIdTest methods, after the test case which contains the valid credit card number, we check whether the object persisted or not in the Database.

In this way, we have done an end-to-end test. After execute mvn verfy command, in the console output, you can see that the tests are passed.

Conclusion

Embedded tests are almost indispensable in today’s microservices and multitier architectures world, especially in the CI/CD pipelines/environments. Test frameworks like Arquillian and MicroShed(of course also Testcontainers) responds to this important need for JakartaEE applications. If we compare the two frameworks, we can tell quickly go through some of the differences.

Arquillian allows you to inject all objects managed by the CDI container into your test class. MicroShed, on the other hand, only allows JAX-RS resources classes injection to the test class. Arquillian has ceremony and verbosity for XML configuration. MicroShed does not require XML configuration. Arquillian does not give you an option to test the system components that your application depends on, but MicroShed offers. We can say that Arquillian has a strong community, but we cannot say the same for MicroShed.

References

Arquillian Guides

MicroShed Testing

JDK 1.5 ve üstü bir sürümle geliştirim yapmış her seviyeden Java geliştiricisi notasyon kullanmıştır. @Inject, @Entity, @Autowired, hiç olmadıysa @Override notasyonunu görmemiş, kullanmamış herhalde yoktur. Java dilinin güçlü yanlarından biri olan notasyonlar, birer dekoratör gibi çalışarak; sınıf, yapılandırıcı, metot, alan gibi program yapılarına meta verisi eklememizi sağlar. Geliştiriciye belirli bir eylem/davranışı adeta markalayıp, uygulamanın ihtiyaç duyulan noktalarına enjekte etme olanağı sağlayan notasyonlar, mükerrer kod yazımını azaltıp, kod okunurluğunu artırırlar.

Notasyonların gücünden, Java geliştiricileri kendi özel notasyonlarını oluşturarak yeterince yararlanmakta mıdır? Başta kendi geliştirim tecrübem olmak üzere kişisel gözlemim ve çeşitli yazı, makale, yayınlanmış anketlerden anladığım; Javacılar notasyon kullanmayı yazmaktan daha çok seviyor. Bu yazıyla amacım, notasyonları daha yakından tanımanıza yardımcı olmak, çalışma mantıklarını göstermek ve basit bir örnek aracılığıyla kendi notasyonunuzu nasıl yazıp kullanabileceğinizi örneklendirerek, özel notasyonların sağladığı avantajlara dikkatinizi çekmek.

Nasıl Çalışıyor?

An annotation is a marker which associates information with a program construct, but has no effect at run time. JLS Section 9.7

Java dil belirtiminde ifade edildiği gibi, notasyonlar kendi başlarına çalışma zamanında herhangi bir etkiye sahip değildir. Daha açık bir ifadeyle, bir notasyon tek başına eklendiği programın çalışma zamanı davranışını değiştirmez. Aslında bir notasyon, uygulandığı noktada elde edilmek istenen davranışı bildiren bir işaretçi(an annotation is a marker - JSL) gibi davranır. Bu sebeple, notasyonların geliştirici tarafından belirlenmiş davranış/eylemi gerçekleştirmesi için çalışma zamanı çerçeveleri(runtime frameworks) veya derleyici tarafından işlenmesi gerekir. Notasyonlar, derleme zamanında Java derleyicisinin bir tür eklentisi sayılabilecek notasyon işleyiciler(annotation processors), çalışma zamanında ise Java Reflection API tarafından işlenir. Bu yazıda, çalışma zamanında Reflection API ile işlenecek bir notasyon örneğini inceleyeceğiz.

Nasıl Tanımlanır?

Bir notasyon tanımlamak, arayüz tanımlamaya benzer. Sözdizimsel fark, interface anahtarı başına @ sembolünün getirilmesinden ibarettir.

public @interface Monitor {}

Bir notasyon oluşturmak için temelde iki bilgiyi sağlamak gerekmektedir. Bunlardan biri Retention politikası, diğeri Target. Retention politikası, notasyona erişim zamanını tanımlarken, target hangi yapıya(sınıf, method, alan) uygulanacağını tanımlamaktadır.

Retention politikası, RetentionPolicy ile tanımlanır. RetentionPolicy enum tipinde bir veri yapısıdır ve java.lang.annotation paketi altında bulunmaktadır.

package java.lang.annotation;

/**
* Annotation retention policy.  The constants of this enumerated type
* describe the various policies for retaining annotations.  They are used
* in conjunction with the {@link Retention} meta-annotation type to specify
* how long annotations are to be retained.
*
* @author  Joshua Bloch
* @since 1.5
*/

public enum RetentionPolicy {
/**
* Annotations are to be discarded by the compiler.
*/
SOURCE,

/**
* Annotations are to be recorded in the class file by the compiler
* but need not be retained by the VM at run time.  This is the default
* behavior.
*/
CLASS,

/**
* Annotations are to be recorded in the class file by the compiler and
* retained by the VM at run time, so they may be read reflectively.
*
* @see java.lang.reflect.AnnotatedElement
*/
RUNTIME
}

Görüldüğü üzere 3 retention politikası vardır.

• SOURCE: Notasyon derleyici tarafından atılır.
• CLASS: Notasyon derleyici tarafından oluşturulan sınıf dosyasına kaydedilir ve JVM tarafından saklanması gerekmez. Varsayılan davranış biçimidir.
• RUNTIME: Notasyon sınıf dosyasına derleyici tarafından kaydedilir ve çalışma zamanında JVM tarafından saklanır, böylece reflection ile okunabilir.

Runtime, uygulamaların notasyonlara ve ilişkili verilerine reflection ile erişip kod yürütülmesine izin verdiği için en bilinen ve yaygın olarak kullanılan retention politikasıdır.

Java 9 sonrası, 11 target vardır; bir başka deyişle 11 yapıya notasyon uygulayabiliriz.

• TYPE: Sınıf, arayüz, notasyon, enum gibi tipleri hedefler
• FIELD: Sınıf değişkenleri, enum sabitleri gibi alan tiplerini hedefler
• METHOD: Sınıf metotlarını hedefler
• MODULE: Java 9 ile gelmiştir, modülleri hedefler
• PARAMETER: Metot, yapılandırıcı parametrelerini hedefler
• CONSTRUCTOR: Yapılandırıcıları hedefler
• LOCAL_VARIABLE: Yerel değişkenleri hedefler
• ANNOTATION_TYPE: Notasyonları hedefler ve başka bir notasyon ekler
• PACKAGE: Paketleri hedefler
• TYPE_PARAMETER: Java 1.8 ile gelmiştir, MyClass<T>’deki T gibi jenerik parametreleri hedefler
• TYPE_USE: Java 1.8 ile gelmiştir, herhangi bir türün kullanımını(örneğin new ile oluşturulma, arayüz implementasyonu, cast işlemi vb) hedefler

Notasyon Parametreleri ve Notasyon Tipleri

Notasyonlar program yapılarına meta verisini, parametreleri aracılığıyla ekler. Bir notasyonun parametreye sahip olup olmaması tipini belirler. Parametre bildirimi içermeyen notasyonlar işaretçi notasyon(marker annotation type) türünü, tek bir parametre bildirimi içeren notasyonlar tek elemanlı(single element annotation type), birden fazla parametre bildirimi içeren notasyonlar ise kompleks notasyon(complex annotation type) türünü oluşturur. Primitif tipler, String, Class, Enum, bir başka notasyon ve bu anılan tiplerin dizi tipi, bir notasyon parametresi olarak bildirilebilir.

Senaryomuz

Profiling için kodumuzda çalışma sürelerini ölçmek istediğimiz metotlara sahip olduğumuzu düşünelim. Her metodun değil, bazı metotların çalışma süresini ölçmek istiyoruz; üstelik bu metotlara ilerde yenileri eklenebilir. Bunun için bir notasyon yazmak iyi bir fikirdir çünkü en başta belirttiğimiz üzere kod okunurluğunu bozmadan ek olarak aynı davranışı tekrar tekrar dilediğimiz noktalarda(örneğin kodumuza eklenecek yeni metotlarda) elde etmek için notasyonlar biçilmiş kaftandır.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Monitor
{
MonitorPolicy value();
}

Retention policy ve Target’tan daha önce bahsettiğimiz için, yukarıda görülen notasyonun çalışma zamanında Reflection API ile işlenebileceğini ve ancak metotlara(başka bir yapıya uygulanırsa derleme zamanında hata alınır) uygulanabileceğini kestirmeniz zor değil. Bu noktada Target ile ilgili şu detayı da paylaşalım, birden fazla hedef tanımlayabilirsiniz.

@Target({ElementType.FIELD, ElementType.METHOD})

Notasyonumuzun gövdesinde ise enum tipinde MonitorPolicy parametresinin deklare edildiğini görüyorsunuz. İlgili enum değerine çalışma zamanında value() metodu üzerinden erişeceğimiz gibi, notasyonumuza değer geçirmek için value’yu anahtar olarak da kullanabiliriz.

@Monitor(value = MonitorPolicy.SHORT)

Fakat değer geçirmek için value anahtarını kullanmak zorunlu değildir. Aşağıdaki kullanım ile yukarıdaki eşdeğerdir.

@Monitor(MonitorPolicy.SHORT)

Value dışında farklı bir ismi kullansaydık bunu belirtmemiz gerekirdi çünkü value, notasyonlarda varsayılan anahtar ismidir. MonitorPolicy SHORT ve DETAILED değerlerine sahiptir. Bu değerlerle, çalışma süresini ölçeceğimiz metotlara dair döndürülecek bilginin biçimini belirliyoruz, ayrıntılı veya kısa.

enum MonitorPolicy 
{
SHORT,DETAILED
}

Tanımladığımız parametreye varsayılan bir değer atamak istediğimizde ise default anahtarını kullanırız.

MonitorPolicy value() default MonitorPolicy.SHORT;

Bu durumda aşağıdaki gibi bir kullanımda, monitor policy short olacaktır.

@Monitor
public String getUserInfo(){
   //Make HTTP request
}

İşleyicimiz

Daha önce ifade ettiğimiz gibi, notasyonlar kendi başlarına herhangi bir kod çalıştırmazlar. Monitor notasyonunda Retention policy olarak RUNTIME tanımlandığı için, çalışma zamanında Java Reflection API kullanılarak işlenmesi gerekir. Aşağıdaki metot bu vazifeyi gerçekleştirir.

public static String executor(final Object object, final Object... passedParameters) {
    checkObjectReference(object);
    final StringBuilder result = new StringBuilder();
    final Method[] methods = object.getClass().getDeclaredMethods();
    for(Method method :methods){
        if(method.isAnnotationPresent(Monitor.class)){
            if(passedParameters.length > 0){
                result.append(invoker(method, object, passedParameters));
            } else {
                result.append(invoker(method, object));
            }
        }
    }
    return result.toString();
}

Executor metodu, biri Monitor notasyonunu kullanan sınıf referansı, diğeri varargs tipinde; ölçüm yapılacak metotların parametreleri olmak üzere 2 argüman alıyor.

Önce object referansı üzerinden, ilgili nesnenin deklare edilmiş metotlarını çekip ardından bir döngü yardımıyla gezilen metotlarda Monitor notasyonunun uygulanıp uygulanmadığını Reflection API’ye ait isAnnotationPresent() metoduyla(metoda notasyon nesnesini geçirdiğimize dikkat edin) kontrol ediyoruz. Monitor notasyonunu uygulayan metod varsa, koşturulması için invoker metodunu çağırıyoruz.

private static String invoker(final Method method, Object object, Object... passedParameters) {

    method.setAccessible(true);
    final StringBuilder result = new StringBuilder();
    final MonitorPolicy policy = method.getAnnotation(Monitor.class).value();
    long start = System.currentTimeMillis();

    try {
        if (passedParameters.length > 0) {
            checkTypeMismatch(method.getName(), method.getParameters(), passedParameters);
            method.invoke(object, passedParameters);
        } else if(method.getGenericParameterTypes().length > 0){
            throw new MissingArgumentException("The parameter(s) of the " + method.getName() + " method are missing");
        } else {
            method.invoke(object);
        }

        final long end = System.currentTimeMillis();
        if(policy.equals(MonitorPolicy.SHORT)){
            result.append(end - start).append(" ms");
            logger.info( "{} ms", (end - start));
        } else {
            result.append("Total execution time of ")
                    .append(method.getName())
                    .append(" method is ")
                    .append(end - start)
                    .append(" ms");
            logger.info("Total execution time of {} method is {} ms",  method.getName(), (end - start));
        }

    } catch ...

Public olarak deklare edilmemiş metotlara da erişebilmek için, invoker metodunda ilk olarak method.setAccessible(true); ile erişim kontrolünü yapılandırıyoruz; aksi halde private metotlar için IllegalAccessException istisnasıyla karşılaşırız. Sonraki adımda, çağırıldığı yapıyla(bizim örneğimizde metot) ilişkilendirilmiş, belirtilen tipteki(metoda notasyon nesnesini geçirdiğimize dikkat edin) notasyonu döndüren Reflection API’ye ait getAnnotation metodunu kullanarak, notasyonumuzda tanımlanmış değeri çekiyoruz. Bu değeri, çalışma süresine dair bilgiyi çıktılama biçimizi belirlemede kullanacağız. Bu aşamadan sonra, o anki zaman mührünü milisaniye cinsinden start değişkeninde depoluyoruz; Monitor notasyonunu uygulamış metodu, Reflection API’nin invoke metoduyla koşturduktan sonra elde edilen zaman mührünü ise end değişkeninde. Son aşamada ise, MonitorPolicy’ye bağlı olarak çalışma süresini çıktılıyoruz.

Aşağıda, paylaşılan örnekteki gibi bir kullanımda alacağımız muhtemel çıktıyı görüyorsunuz.

@Monitor(MonitorPolicy.DETAILED)
public String getUserInfo(){
   //Make HTTP request
}

Profiler.executor(new User());

Total execution time of getUserInfo method is 1459 ms

Monitor notasyonunu içeren uygulamaya buradan ulaşabilirsiniz.

Sonuç

Java notasyonları sınıf, yapılandırıcı, metot, alan gibi Java program yapılarına meta verisi eklememizi sağlayan, bu şekilde mükerrer kod yazımını azaltıp, kod okunurluğunu artıran Java dilinin güçlü yanlarından biridir. Notasyonlar kendi başlarına herhangi bir kod çalıştırmazlar, bunun yerine derleyici veya ait oldukları çerçeve(framework) için, uygulandığı noktada elde edilmek istenen davranışı bildiren bir işaretçi gibi davranıp, derleme zamanında Java Annotation Processors’ler, çalışma zamanında ise Java Reflection API tarafından işlenirler.

Let’s assume we want to control and limit the amount of incoming and outgoing network traffic. For example, let’s say we provide a service that is configured to allow 10 requests/second. Similarly, let’s assume we use a circuit breaker for fault detection related to the service that the incoming request wants to access. In this case, If the incoming requests exceed the defined limit, or the service is unavailable, it will be necessary to refuse the request.

Calling the next handler offers us a useful way to manage the kind of need that’s requiring different controls for the same purpose.

Calling the Next Handler

@Override
public void start(Future<Void> future) {

    final ConfigStoreOptions rateOptions = new ConfigStoreOptions()
            .setType("file")
            .setOptional(true)
            .setConfig(new JsonObject().put("path", System.getProperty("user.dir") + "/Routing/src/main/resources/config.json"));

    final ConfigRetrieverOptions options = new ConfigRetrieverOptions().addStore(rateOptions);

    final Router router = RouterHelper.createRouter(vertx, "Hello from routing example!");
    router.get("/limiting").handler(new CircuitBreakerHandler(options));
    router.get("/limiting").handler(new RateLimiterHandler(options));
    HttpServerHelper.createAnHttpServer(vertx, router, config(), future);
}

In the above code, we created two routes for the same path and bounded different handlers. When a GET /limiting request arrives the CircuitBreakerHandler will work first.

@Override
public void handle(RoutingContext context) {

    final ConfigRetriever retriever = ConfigRetriever.create(context.vertx(), options);

    retriever.getConfig(ar -> {
        if (ar.failed()) {
            log.error("Failed to retrieve the configuration");
        } else {

            final JsonObject config = ar.result();
            final boolean circuitbreaker = config.getBoolean("circuitbreaker");

            if (!circuitbreaker) {
                context.next();
            } else {
                context.response()
                        .putHeader(CONTENT_TYPE, HTML_PRODUCE)
                        .setStatusCode(HTTP_SERVICE_UNAVAILABLE)
                        .end("Service unavailable!");
            }
        }
    });

}

In the handler, we are checking firstly to CircuitBreaker and if it’s closed we call next method of the RoutingContext. The next method tell the router to route this context to the next matching route (if any). In our example, this will provide calling RateLimiterHandler. I created a repository for this example, you can examine.

Conclusion

Vert.x allows multiple handlers binding to a route. This provides routing the handled context to the next matching route and so encapsulates your handlers for different logic by linking together such as a chain.

References

• Vert.x-Web for Java
• RoutingContext