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.
This commit is contained in:
Eric Anderson 2021-04-13 12:24:34 -07:00 committed by Eric Anderson
parent 4ad49266ec
commit 384f4c401d
1 changed files with 6 additions and 1 deletions

View File

@ -955,7 +955,12 @@ public class Context {
}
/**
* 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<T> {
private final String name;