IGNITE-26608

Author: petrov-mg

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

@@ -17,11 +17,19 @@
 
 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 of the {@link ContextAttribute} to its corresponding value. Context provides an ability
+ * to be attached to the thread, which makes {@link ContextAttribute} values accessible via {@link ContextAttribute#get()}
+ * method called from the same thread.
+ *
+ * @see ContextAttribute
+ * @see ContextSnapshot
+ */
 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 with a single mapping of the specified {@link AttributeValueHolder} to its value.
+     * The returned {@link AttributeValueHolder} represents the last added to the Context mapping and can be used to
+     * accumulate more mappings of {@link ContextAttribute}s to their values.
      *
      * @see AttributeValueHolder#with(ContextAttribute, Object)
      */
@@ -54,7 +62,12 @@ 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}. */
+        /**
+         * Adds to the Context a new mapping of the specified attribute to its value.
+         *
+         * @return {@link AttributeValueHolder} instance that represents the last added to the Context mapping and can be
+         * used to accumulate more mappings of {@link ContextAttribute}s to their values.
+         */
         public <T> AttributeValueHolder with(ContextAttribute<T> attr, T val) {
             return attr.get() == val ? this : new AttributeValueHolder(attr, val, this);
         }
@@ -79,9 +92,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 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.
          *
          * @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.

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

@@ -17,7 +17,10 @@
 
 package org.apache.ignite.internal.thread.context;
 
-/** */
+/**
+ * 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 ContextDataChain<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 this method is called from 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 this
+     * method is called from.
+     */
     public static ContextSnapshot capture() {
         return ThreadLocalContextStorage.get().snapshot();
     }