IGNITE-26608

Author: petrov-mg

modules/commons/src/main/java/org/apache/ignite/internal/thread/context/Context.java

@@ -17,11 +17,20 @@
 
 package org.apache.ignite.internal.thread.context;
 
-/** Represents mapping of {@link ContextAttribute} to their corresponding values with the ability to be attached to the thread. */
+/**
+ * Represents a set of mappings from the {@link ContextAttribute} to its corresponding value. The Context can be attached
+ * to a thread, making the {@link ContextAttribute} values accessible through the {@link ContextAttribute#get()}
+ * method when invoked from the same thread.
+ *
+ * @see ContextAttribute
+ * @see ContextSnapshot
+ * @see AttributeValueHolder#attach()
+ */
 public final class Context {
     /**
-     * Creates a new {@link AttributeValueHolder} with a single mapping of the specified {@link AttributeValueHolder}
-     * to the specified value. The {@link AttributeValueHolder} can be used to accumulate mappings.
+     * Creates a new Context containing a single mapping from the specified {@link AttributeValueHolder} to its value.
+     * The returned {@link AttributeValueHolder} represents the added mapping and can be used to accumulate to Context
+     * more mappings form {@link ContextAttribute} to its value.
      *
      * @see AttributeValueHolder#with(ContextAttribute, Object)
      */
@@ -30,7 +39,7 @@ public static <T> AttributeValueHolder with(ContextAttribute<T> attr, T val) {
     }
 
     /** */
-    public static final class AttributeValueHolder extends ContextDataChain<AttributeValueHolder> {
+    public static final class AttributeValueHolder extends ContextDataChainNode<AttributeValueHolder> {
         /** */
         private static final AttributeValueHolder ROOT = new AttributeValueHolder();
 
@@ -54,7 +63,13 @@ private <T> AttributeValueHolder(ContextAttribute<T> attr, T val, AttributeValue
             this.val = val;
         }
 
-        /** Adds a new mapping of the specified attribute to its value to the current {@link ContextDataChain}. */
+        /**
+         * Expands Context by adding new mapping from the specified {@link ContextAttribute} to its value.
+         * After this operation, the Context contains all previously added mappings plus the new one.
+         *
+         * @return {@link AttributeValueHolder} instance that represents the added mapping and can be used to accumulate
+         * more mappings from {@link ContextAttribute} to its values.
+         */
         public <T> AttributeValueHolder with(ContextAttribute<T> attr, T val) {
             return attr.get() == val ? this : new AttributeValueHolder(attr, val, this);
         }
@@ -79,9 +94,9 @@ <T> T value() {
         }
 
         /**
-         * Attaches {@link ContextAttribute} values stored in current {@link ContextDataChain} to the thread
-         * this method is called from. If {@link ContextAttribute} value was already attached for the current thread,
-         * its value will be stashed and replaced by the new ones.
+         * Attaches {@link ContextAttribute} values stored in current Context to the thread from which this method is
+         * called. If {@link ContextAttribute} value was already attached for the current thread, its value will be
+         * stashed and replaced by the new one.
          *
          * @return {@link Scope} instance that, when closed, resets the values for all {@link ContextAttribute}s added
          * to the current Context and restores them to the previously attached values, if any.

…nal/thread/context/ContextDataChain.java …thread/context/ContextDataChainNode.javamodules/commons/src/main/java/org/apache/ignite/internal/thread/context/ContextDataChain.java renamed to modules/commons/src/main/java/org/apache/ignite/internal/thread/context/ContextDataChainNode.java modules/commons/src/main/java/org/apache/ignite/internal/thread/context/ContextDataChain.java renamed to modules/commons/src/main/java/org/apache/ignite/internal/thread/context/ContextDataChainNode.java

@@ -18,21 +18,21 @@
 package org.apache.ignite.internal.thread.context;
 
 /** */
-public abstract class ContextDataChain<T> {
+public abstract class ContextDataChainNode<T> {
     /** */
     private final int storedAttrIdBits;
 
     /** */
     private final T prev;
 
     /** */
-    protected ContextDataChain() {
+    protected ContextDataChainNode() {
         storedAttrIdBits = 0;
         prev = null;
     }
 
     /** */
-    protected ContextDataChain(int storedAttrIdBits, T prev) {
+    protected ContextDataChainNode(int storedAttrIdBits, T prev) {
         this.storedAttrIdBits = storedAttrIdBits;
         this.prev = prev;
     }

modules/commons/src/main/java/org/apache/ignite/internal/thread/context/ContextSnapshot.java

@@ -17,8 +17,11 @@
 
 package org.apache.ignite.internal.thread.context;
 
-/** */
-public class ContextSnapshot extends ContextDataChain<ContextSnapshot> {
+/**
+ * Represents Snapshot of all {@link ContextAttribute}s and their corresponding values. Note that Snapshot also stores
+ * the states of {@link ContextAttribute}s for which value are note explicitly specified.
+ */
+public class ContextSnapshot extends ContextDataChainNode<ContextSnapshot> {
     /** */
     static final ContextSnapshot ROOT = new ContextSnapshot();
 
@@ -37,7 +40,13 @@ private ContextSnapshot(Context.AttributeValueHolder data, ContextSnapshot prev)
         this.data = data;
     }
 
-    /** */
+    /**
+     * Stashes all {@link ContextAttribute} values attached to the thread from which this method is called and replaces
+     * them with ones stored in the current Snapshot.
+     *
+     * @return {@link Scope} instance that, when closed, restores the values of all {@link ContextAttribute}s to the
+     * state they were in before the current method was called.
+     */
     public Scope restore() {
         ThreadLocalContextStorage threadData = ThreadLocalContextStorage.get();
 
@@ -71,7 +80,10 @@ Context.AttributeValueHolder data() {
         return this == ROOT;
     }
 
-    /** */
+    /**
+     * Captures Snapshot of all {@link ContextAttribute}s and their corresponding values attached to the thread from which
+     * this method is called.
+     */
     public static ContextSnapshot capture() {
         return ThreadLocalContextStorage.get().snapshot();
     }