From 384f4c401d3cb2554dda2347812de3a8df5ffe80 Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Tue, 13 Apr 2021 12:24:34 -0700 Subject: [PATCH] context: Add docs describing common Key usage This recently came up in https://stackoverflow.com/a/67062503/4690866, but it has come up multiple times before. These docs aren't ideal, as they may be missed by a reader and so references in other parts of the API would probably be appropriate. There could also be something about "Context is not a general purpose map." But this is an improvement, and I didn't want to let the perfect be the enemy of the good. --- context/src/main/java/io/grpc/Context.java | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/context/src/main/java/io/grpc/Context.java b/context/src/main/java/io/grpc/Context.java index 530052d7478..142cd3cadbb 100644 --- a/context/src/main/java/io/grpc/Context.java +++ b/context/src/main/java/io/grpc/Context.java @@ -955,7 +955,12 @@ public interface CancellationListener { } /** - * Key for indexing values stored in a context. + * Key for indexing values stored in a context. Keys use reference equality and Context does not + * provide a mechanism to loop over Keys. This means there is no way to access a Key's value from + * a Context without having access to the Key instance itself. This allows strong control over + * what code can get/set a key in the Context. For example, you might manage access to Key similar + * to a ThreadLocal using Java visibility (private/protected). Generally Keys are stored in static + * fields. */ public static final class Key { private final String name;