Module io.smallrye.common.vertx
Package io.smallrye.common.vertx

Class VertxContext

java.lang.Object
io.smallrye.common.vertx.VertxContext
public class VertxContext extends Object
Utility classes allowing to create duplicated and nested contexts.

The rationale for this class is to avoid end-users to use the Vert.x internal API, and avoids common mistakes when dealing with Contexts and duplicated Contexts.

With this class, Vert.x contexts can be categorized into three types:

1. Root Context

The original context associated with a Vert.x thread (usually an event loop context). This context is long-lived and shared across multiple asynchronous operations. Because the data stored in this context is shared across operations, it is not safe for storing transient or request-scoped data. 
 +---------------------------+
 |       Event Loop          |
 |       (Root Context)      |
 +---------------------------+

2. Duplicated Context

A lightweight, short-lived copy of a root context used for isolating state.

Duplicated contexts provide a safe space for request or task-scoped data. 

 +---------------------------+
 |       Event Loop          |
 |       (Root Context)      |
 +---------------------------+
            |
            v
 +---------------------------+
 |    Duplicated Context     |
 |   (copy of root context)  |
 +---------------------------+

3. Nested Context

A duplicated context that is derived from another duplicated context, forming a parent-child relationship.

Nested contexts copy the local state of their parent on creation but maintain isolation afterward. A reference to the parent context is retained, enabling access to shared data when necessary. 

  +---------------------------+
  |       Event Loop          |
  |       (Root Context)      |
  +---------------------------+
          |
          V
 +---------------------------+
 |    Duplicated Context     |  --- parent
 |    (e.g., request scope)  |
 +---------------------------+
            |
            v
 +---------------------------+
 |     Nested Context        |
 |  (e.g., REST call scope)  |
 +---------------------------+

Summary of Behavior:

  • Root to Duplicated: isolates state, safe for short-lived operations
  • Duplicated to️ Nested: adds parent-awareness and controlled inheritance
  • Root Shared Locals: discouraged due to data leakage risk

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    PARENT_CONTEXT
    The key used to store the parent context in a nested context.

  • Method Summary

    Modifier and Type
    Method
    Description
    static io.vertx.core.Context
    createNewDuplicatedContext()
    Creates a new duplicated context, even if the current one is already a duplicated context.
    static io.vertx.core.Context
    createNewDuplicatedContext(io.vertx.core.Context context)
    Creates a new duplicated context, even if the passed one is already a duplicated context.
    static io.vertx.core.Context
    getOrCreateDuplicatedContext()
    Gets or creates a duplicated context.
    static io.vertx.core.Context
    getOrCreateDuplicatedContext(io.vertx.core.Context context)
    Gets or creates a duplicated context.
    static io.vertx.core.Context
    getOrCreateDuplicatedContext(io.vertx.core.Vertx vertx)
    Gets or creates a duplicated context.
    static io.vertx.core.Context
    getRootContext(io.vertx.core.Context context)
    Returns the parent context from a given Vert.x context.
    static boolean
    isDuplicatedContext(io.vertx.core.Context context)
    Checks if the given context is a duplicated context.
    static boolean
    isOnDuplicatedContext()
    Checks if the current context is a duplicated context.
    static io.vertx.core.Context
    newNestedContext()
    Creates a new nested context from the current context.
    static io.vertx.core.Context
    newNestedContext(io.vertx.core.Context context)
    Creates a new nested context from the given context.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • PARENT_CONTEXT

      public static final String PARENT_CONTEXT
      The key used to store the parent context in a nested context.
      See Also:

  • Method Details

    • getOrCreateDuplicatedContext

      public static io.vertx.core.Context getOrCreateDuplicatedContext(io.vertx.core.Context context)
      Gets or creates a duplicated context. If the given context is already a duplicated context, it returns this duplicated context. Otherwise, it creates a new duplicated context, using the given context as root context.
      Parameters:
      context - the context, must not be null
      Returns:
      the given context if it's a duplicated context, or a new duplicated context using the given one as root.

    • getOrCreateDuplicatedContext

      public static io.vertx.core.Context getOrCreateDuplicatedContext(io.vertx.core.Vertx vertx)
      Gets or creates a duplicated context.

      If this method is called from a non-Vert.x thread (so, there is no current context), it creates a new (event loop) context and a duplicated context (and returns the duplicated context).

      If this method is called from a Vert.x thread (so, there is a current context), and if the current context is already a duplicated context, it returns the current duplicated context.

      It this method is called from a Vert.x thread (so, there is a current context), and if the current context is not a duplicated context, it creates a new duplicated context, using the current context as root context.

      Parameters:
      vertx - the Vert.x instance to use to create the context if needed. Must not be null
      Returns:
      the current context if it's a duplicated context, or a new duplicated context.
      See Also:

    • getOrCreateDuplicatedContext

      @Nullable public static io.vertx.core.Context getOrCreateDuplicatedContext()
      Gets or creates a duplicated context.

      If the method is not called from a Vert.x thread, it returns null. If the caller context is already a duplicated context, it returns this duplicated context. Otherwise, it creates a new duplicated context, using current context as root context.

      Returns:
      the current context if it's a duplicated context, a new duplicated context using the given one as root, null if not called from a Vert.x thread.
      See Also:

    • createNewDuplicatedContext

      @Nullable public static io.vertx.core.Context createNewDuplicatedContext()
      Creates a new duplicated context, even if the current one is already a duplicated context. If the method is not called from a Vert.x thread, it returns null.
      Returns:
      a new duplicated context if called from a Vert.x thread, null otherwise.

    • createNewDuplicatedContext

      @Nullable public static io.vertx.core.Context createNewDuplicatedContext(io.vertx.core.Context context)
      Creates a new duplicated context, even if the passed one is already a duplicated context. If the passed context is null, it returns null
      Parameters:
      context - the context
      Returns:
      a new duplicated context created from the given context, null is the passed context is null

    • isDuplicatedContext

      public static boolean isDuplicatedContext(io.vertx.core.Context context)
      Checks if the given context is a duplicated context.
      Parameters:
      context - the context, must not be null
      Returns:
      true if the given context is a duplicated context, false otherwise.

    • isOnDuplicatedContext

      public static boolean isOnDuplicatedContext()
      Checks if the current context is a duplicated context. If the method is called from a Vert.x thread, it retrieves the current context and checks if it's a duplicated context. Otherwise, it returns false.
      Returns:
      true if the method is called from a duplicated context, false otherwise.

    • getRootContext

      public static io.vertx.core.Context getRootContext(io.vertx.core.Context context)
      Returns the parent context from a given Vert.x context.

      A duplicate context returns the wrapped context otherwise the given context is returned.

      Parameters:
      context - the context, must not be null
      Returns:
      the root context if the given context is a duplicated context, returns the given context otherwise.

    • newNestedContext

      public static io.vertx.core.Context newNestedContext(io.vertx.core.Context context)
      Creates a new nested context from the given context.

      A nested context is a duplicated context that has a reference to the parent context. It's an artificial way to create a hierarchy of contexts.

      If the given context is a root context, it creates a new (regulaR) duplicated context. If the given context is a duplicated context, it creates a new duplicated context and copies the context locals.

      When creating a nested context, the locals from the parent context are copied to the nested context. In this way, the nested context can access the parent context locals, but writes are not propagated to the parent (unless made explicitly).

      Nested contexts keep a reference to the parent context, so, it's possible to navigate the context hierarchy.

      Parameters:
      context - the context, must not be null
      Returns:
      a new nested context from the given context.

    • newNestedContext

      public static io.vertx.core.Context newNestedContext()
      Creates a new nested context from the current context.
      Returns:
      a new nested context from the current context.
      See Also: