public final class ContextBuilder
extends java.lang.Object
LDContext
.
Use this type if you need to construct a context that has only a single kind. To define a
multi-kind context, use LDContext.createMulti(LDContext...)
or
LDContext.multiBuilder()
.
Obtain an instance of ContextBuilder by calling LDContext.builder(String)
or
LDContext.builder(ContextKind, String)
. Then, call setter methods such as
name(String)
or set(String, String)
to specify any additional attributes.
Then, call build()
to create the context. ContextBuilder setters return a reference
to the same builder, so calls can be
chained:
LDContext context = LDContext.builder("context-key-123abc")
.name("my-name)
.set("country", "us")
.build();
A ContextBuilder should not be accessed by multiple threads at once. Once you have called
build()
, the resulting LDContext is immutable and is safe to use from multiple
threads. Instances created with build()
are not affected by subsequent actions
taken on the builder.
Modifier and Type | Method and Description |
---|---|
ContextBuilder |
anonymous(boolean anonymous)
Sets whether the context is only intended for flag evaluations and should not be
indexed by LaunchDarkly.
|
LDContext |
build()
Creates an
LDContext from the current builder properties. |
ContextBuilder |
key(java.lang.String key)
Sets the context's key attribute.
|
ContextBuilder |
kind(ContextKind kind)
Sets the context's kind attribute.
|
ContextBuilder |
kind(java.lang.String kindString)
Sets the context's kind attribute, as a string.
|
ContextBuilder |
name(java.lang.String name)
Sets the context's name attribute.
|
ContextBuilder |
privateAttributes(AttributeRef... attributeRefs)
Equivalent to
privateAttributes(String...) , but uses the AttributeRef
type. |
ContextBuilder |
privateAttributes(java.lang.String... attributeRefs)
Designates any number of context attributes, or properties within them, as private:
that is, their values will not be recorded by LaunchDarkly.
|
ContextBuilder |
set(java.lang.String attributeName,
boolean value)
Same as
set(String, LDValue) for a boolean value. |
ContextBuilder |
set(java.lang.String attributeName,
double value)
Same as
set(String, LDValue) for a double-precision numeric value. |
ContextBuilder |
set(java.lang.String attributeName,
int value)
Same as
set(String, LDValue) for an integer numeric value. |
ContextBuilder |
set(java.lang.String attributeName,
LDValue value)
Sets the value of any attribute for the context.
|
ContextBuilder |
set(java.lang.String attributeName,
java.lang.String value)
Same as
set(String, LDValue) for a string value. |
boolean |
trySet(java.lang.String attributeName,
LDValue value)
Same as
set(String, LDValue) , but returns a boolean indicating whether
the attribute was successfully set. |
public LDContext build()
LDContext
from the current builder properties.
The LDContext is immutable and will not be affected by any subsequent actions on the ContextBuilder.
It is possible to specify invalid attributes for a ContextBuilder, such as an empty key.
Instead of throwing an exception, the ContextBuilder always returns an LDContext and
you can check LDContext.isValid()
or LDContext.getError()
to see if it
has an error. See LDContext.isValid()
for more information about invalid
conditions. If you pass an invalid LDContext to an SDK method, the SDK will detect this
and will log a description of the error.
LDContext
public ContextBuilder kind(ContextKind kind)
Every LDContext has a kind. Setting it to an empty string or null is equivalent to
ContextKind.DEFAULT
("user"). This value is case-sensitive. For validation
rules, see ContextKind
.
kind
- the context kindLDContext.getKind()
public ContextBuilder kind(java.lang.String kindString)
This method is a shortcut for calling kind(ContextKind.of(kindName))
, since the
method name already prevents ambiguity about the intended type
kindString
- the context kindLDContext.getKind()
public ContextBuilder key(java.lang.String key)
Every Context has a key, which is always a string. It cannot be an empty string, but there are no other restrictions on its value.
The key attribute can be referenced by flag rules, flag target lists, and segments.
key
- the context keyLDContext.getKey()
public ContextBuilder name(java.lang.String name)
This attribute is optional. It has the following special rules:
name
- the name attribute (null to unset the attribute)LDContext.getName()
public ContextBuilder anonymous(boolean anonymous)
The default value is false. False means that this LDContext represents an entity such as a user that you want to be able to see on the LaunchDarkly dashboard.
Setting anonymous
to true excludes this context from the database that is
used by the dashboard. It does not exclude it from analytics event data, so it is
not the same as making attributes private; all non-private attributes will still be
included in events and data export. There is no limitation on what other attributes
may be included (so, for instance, anonymous
does not mean there is no
name
), and the context will still have whatever key
you have given it.
This value is also addressable in evaluations as the attribute name "anonymous". It is always treated as a boolean true or false in evaluations.
anonymous
- true if the context should be excluded from the LaunchDarkly databaseLDContext.isAnonymous()
public ContextBuilder set(java.lang.String attributeName, LDValue value)
This includes only attributes that are addressable in evaluations-- not metadata
such as privateAttributes(String...)
. If attributeName
is
"privateAttributes", you will be setting an attribute with that name which you can
use in evaluations or to record data for your own purposes, but it will be unrelated
to privateAttributes(String...)
.
This method uses the LDValue
type to represent a value of any JSON type:
null, boolean, number, string, array, or object. For all attribute names that do
not have special meaning to LaunchDarkly, you may use any of those types. Values of
different JSON types are always treated as different values: for instance, null,
false, and the empty string "" are not the the same, and the number 1 is not the
same as the string "1".
The following attribute names have special restrictions on their value types, and any value of an unsupported type will be ignored (leaving the attribute unchanged):
kind(ContextKind)
and
key(String)
. name(String)
. anonymous(boolean)
. The attribute name "_meta" is not allowed, because it has special meaning in the JSON schema for contexts; any attempt to set an attribute with this name has no effect. Also, any attempt to set an attribute with an empty or null name has no effect.
Values that are JSON arrays or objects have special behavior when referenced in flag/segment rules.
A value of null
or LDValue.ofNull()
is equivalent to removing any
current non-default value of the attribute. Null is not a valid attribute value in
the LaunchDarkly model; any expressions in feature flags that reference an attribute
with a null value will behave as if the attribute did not exist.
attributeName
- the attribute name to setvalue
- the value to setset(String, boolean)
,
set(String, int)
,
set(String, double)
,
set(String, String)
,
trySet(String, LDValue)
public ContextBuilder set(java.lang.String attributeName, boolean value)
set(String, LDValue)
for a boolean value.attributeName
- the attribute name to setvalue
- the value to setset(String, LDValue)
public ContextBuilder set(java.lang.String attributeName, int value)
set(String, LDValue)
for an integer numeric value.attributeName
- the attribute name to setvalue
- the value to setset(String, LDValue)
public ContextBuilder set(java.lang.String attributeName, double value)
set(String, LDValue)
for a double-precision numeric value.attributeName
- the attribute name to setvalue
- the value to setset(String, LDValue)
public ContextBuilder set(java.lang.String attributeName, java.lang.String value)
set(String, LDValue)
for a string value.attributeName
- the attribute name to setvalue
- the value to setset(String, LDValue)
public boolean trySet(java.lang.String attributeName, LDValue value)
set(String, LDValue)
, but returns a boolean indicating whether
the attribute was successfully set.attributeName
- the attribute name to setvalue
- the value to setpublic ContextBuilder privateAttributes(java.lang.String... attributeRefs)
Each parameter can be either a simple attribute name (like "email"), or an attribute
reference in the syntax described for AttributeRef
(like "/address/street").
attributeRefs
- attribute references to mark as privatepublic ContextBuilder privateAttributes(AttributeRef... attributeRefs)
privateAttributes(String...)
, but uses the AttributeRef
type.
Application code is unlikely to need to use the AttributeRef
type directly;
however, in cases where you are constructing LDContexts constructed repeatedly with
the same set of private attributes, if you are also using complex private attribute
path references such as "/address/street", converting this to an AttributeRef once
and reusing it in many privateAttribute
calls is slightly more efficient
than passing a string (since it does not need to parse the path repeatedly).
attributeRefs
- attribute references to mark as private