public final class LDContext extends java.lang.Object implements JsonSerializable
LDContext is the newer replacement for the previous, less flexible LDUser
type.
The current SDK still supports LDUser, but LDContext is now the preferred model and may
entirely replace LDUser in the future.
To create an LDContext of a single kind, such as a user, you may use create(String)
or create(ContextKind, String)
when only the key matters; or, to specify other
attributes, use builder(String)
.
To create an LDContext with multiple kinds, use createMulti(LDContext...)
or
multiBuilder()
.
An LDContext can be in an error state if it was built with invalid attributes. See
isValid()
and getError()
.
LaunchDarkly defines a standard JSON encoding for contexts, used by the JavaScript SDK
and also in analytics events. LDContext
can be converted to and from JSON in any of
these ways:
JsonSerialization
.
Gson
instance with
LDGson
.
ObjectMapper
instance with
LDJackson
.
To learn more about contexts, read the documentation.
Modifier and Type | Method and Description |
---|---|
static ContextBuilder |
builder(ContextKind kind,
java.lang.String key)
|
static ContextBuilder |
builder(java.lang.String key)
Creates a
ContextBuilder for building an LDContext, initializing its key and setting
kind to ContextKind.DEFAULT . |
static ContextBuilder |
builderFromContext(LDContext context)
Creates a builder whose properties are the same as an existing single-kind LDContext.
|
static LDContext |
create(ContextKind kind,
java.lang.String key)
Creates a single-kind LDContext with only the kind and keys specified.
|
static LDContext |
create(java.lang.String key)
Creates a single-kind LDContext with a kind of
ContextKind.DEFAULT } and the specified key. |
static LDContext |
createMulti(LDContext... contexts)
Creates a multi-kind LDContext out of the specified single-kind LDContexts.
|
boolean |
equals(java.lang.Object other) |
static LDContext |
fromUser(LDUser user)
Deprecated.
use
LDContext directly instead. |
java.lang.Iterable<java.lang.String> |
getCustomAttributeNames()
Returns the names of all non-built-in attributes that have been set in this context.
|
java.lang.String |
getError()
Returns null for a valid LDContext, or an error message for an invalid one.
|
java.lang.String |
getFullyQualifiedKey()
Returns a string that describes the LDContext uniquely based on
kind and
key values. |
LDContext |
getIndividualContext(ContextKind kind)
Returns the single-kind LDContext corresponding to one of the kinds in this context.
|
LDContext |
getIndividualContext(int index)
Returns the single-kind LDContext corresponding to one of the kinds in this context.
|
LDContext |
getIndividualContext(java.lang.String kind)
Same as
getIndividualContext(ContextKind) , but specifies the kind as a
plain string. |
int |
getIndividualContextCount()
Returns the number of context kinds in this context.
|
java.lang.String |
getKey()
Returns the context's
key attribute. |
ContextKind |
getKind()
Returns the context's
kind attribute. |
java.lang.String |
getName()
Returns the context's
name attribute. |
AttributeRef |
getPrivateAttribute(int index)
Retrieves one of the private attribute references that were specified for this context.
|
int |
getPrivateAttributeCount()
Returns the number of private attribute references that were specified for this context.
|
LDValue |
getValue(AttributeRef attributeRef)
Looks up the value of any attribute of the context, or a value contained within an
attribute, based on an
AttributeRef . |
LDValue |
getValue(java.lang.String attributeName)
Looks up the value of any attribute of the context by name.
|
int |
hashCode() |
boolean |
isAnonymous()
Returns true if this context is only intended for flag evaluations and will not be
indexed by LaunchDarkly.
|
boolean |
isMultiple()
Returns true if this is a multi-kind context.
|
boolean |
isValid()
Returns
true for a valid LDContext, false for an invalid one. |
static ContextMultiBuilder |
multiBuilder()
Creates a
ContextMultiBuilder for building a multi-kind context. |
java.lang.String |
toString()
Returns a string representation of the context.
|
public static LDContext create(java.lang.String key)
ContextKind.DEFAULT
} and the specified key.
To specify additional properties, use builder(String)
. To create a multi-kind
LDContext, use createMulti(LDContext...)
or multiBuilder()
. To create a
single-kind LDContext of a different kind than "user", use create(ContextKind, String)
.
key
- the context keycreate(ContextKind, String)
,
builder(String)
public static LDContext create(ContextKind kind, java.lang.String key)
To specify additional properties, use builder(ContextKind, String)
. To create a multi-kind
LDContext, use createMulti(LDContext...)
or multiBuilder()
.
kind
- the context kind; if null, ContextKind.DEFAULT
will be usedkey
- the context keycreate(String)
,
builder(ContextKind, String)
public static LDContext createMulti(LDContext... contexts)
To create a single-kind Context, use create(String)
, create(ContextKind, String)
,
or builder(String)
.
For the returned LDContext to be valid, the contexts list must not be empty, and all of its
elements must be valid LDContexts. Otherwise, the returned LDContext will be invalid as
reported by getError()
.
If only one context parameter is given, the method returns that same context.
If the nested context is multi-kind, this is exactly equivalent to adding each of the individual kinds from it separately. For instance, in the following example, "multi1" and "multi2" end up being exactly the same:
LDContext c1 = LDContext.create(ContextKind.of("kind1"), "key1");
LDContext c2 = LDContext.create(ContextKind.of("kind2"), "key2");
LDContext c3 = LDContext.create(ContextKind.of("kind3"), "key3");
LDContext multi1 = LDContext.createMulti(c1, c2, c3);
LDContext c1plus2 = LDContext.createMulti(c1, c2);
LDContext multi2 = LDContext.createMulti(c1plus2, c3);
contexts
- a list of contextsmultiBuilder()
@Deprecated public static LDContext fromUser(LDUser user)
LDContext
directly instead.LDContext
instance.
This method is used by the SDK whenever an application passes a LDUser
instance
to methods such as identify
. The SDK operates internally on the LDContext
model, which is more flexible than the older LDUser model: an L User can always be converted
to an LDContext, but not vice versa. The ContextKind
of the resulting Context is
ContextKind.DEFAULT
("user").
Because there is some overhead to this conversion, it is more efficient for applications to construct an LDContext and pass that to the SDK, rather than an LDUser. This is also recommended because the LDUser type may be removed in a future version of the SDK.
If the user
parameter is null, or if the user has a null key, the method returns an
LDContext in an invalid state (see isValid()
).
user
- an LDUser objectpublic static ContextBuilder builder(java.lang.String key)
ContextBuilder
for building an LDContext, initializing its key
and setting
kind
to ContextKind.DEFAULT
.
You may use ContextBuilder
methods to set additional attributes and/or change the
ContextBuilder.kind(ContextKind)
before calling ContextBuilder.build()
.
If you do not change any values, the defaults for the LDContext are that its kind
is
ContextKind.DEFAULT
("user"), its key
is set to the key parameter passed here,
anonymous
is false
, and it has no values for any other attributes.
This method is for building an LDContext that has only a single Kind. To define a multi-kind
LDContext, use multiBuilder()
.
if key
is an empty string, there is no default. An LDContext must have a non-empty
key, so if you call ContextBuilder.build()
in this state without using
ContextBuilder.key(String)
to set the key, you will get an invalid LDContext.
key
- the context keybuilder(ContextKind, String)
,
multiBuilder()
,
create(String)
public static ContextBuilder builder(ContextKind kind, java.lang.String key)
ContextBuilder
for building an LDContext, initializing its key
and
kind
.
You may use ContextBuilder
methods to set additional attributes and/or change the
ContextBuilder.kind(ContextKind)
before calling ContextBuilder.build()
.
If you do not change any values, the defaults for the LDContext are that its kind
and
key
is set to the parameters passed here, anonymous
is false
, and it has
no values for any other attributes.
This method is for building an LDContext that has only a single Kind. To define a multi-kind
LDContext, use multiBuilder()
.
if key
is an empty string, there is no default. An LDContext must have a non-empty
key, so if you call ContextBuilder.build()
in this state without using
ContextBuilder.key(String)
to set the key, you will get an invalid LDContext.
kind
- the context kind; if null, ContextKind.DEFAULT
is usedkey
- the context keybuilder(String)
,
multiBuilder()
,
create(ContextKind, String)
public static ContextBuilder builderFromContext(LDContext context)
You may then change the builder's state in any way and call ContextBuilder.build()
to create a new independent LDContext.
context
- the context to copy frombuilder(String)
public static ContextMultiBuilder multiBuilder()
ContextMultiBuilder
for building a multi-kind context.
This method is for building a Context that has multiple ContextKind
values,
each with its own nested LDContext. To define a single-kind context, use
builder(String)
instead.
createMulti(LDContext...)
public boolean isValid()
true
for a valid LDContext, false
for an invalid one.
A valid context is one that can be used in SDK operations. An invalid context is one that is missing necessary attributes or has invalid attributes, indicating an incorrect usage of the SDK API. The only ways for a context to be invalid are:
kind
property. See ContextKind
. key
is empty. createMulti(LDContext...)
. fromUser(LDUser)
from a null LDUser reference, or from an
LDUser that had a null key.
In any of these cases, isValid()
will return false, and getError()
will return a description of the error.
Since in normal usage it is easy for applications to be sure they are using context kinds
correctly, and because throwing an exception is undesirable in application code that uses
LaunchDarkly, the SDK stores the error state in the LDContext itself and checks for such
errors at the time the Context is used, such as in a flag evaluation. At that point, if
the context is invalid, the operation will fail in some well-defined way as described in
the documentation for that method, and the SDK will generally log a warning as well. But
in any situation where you are not sure if you have a valid LDContext, you can check
isValid()
or getError()
.
getError()
public java.lang.String getError()
If this is null, then isValid()
is true. If it is non-null, then isValid()
is false.
isValid()
public ContextKind getKind()
kind
attribute.
Every valid context has a non-empty ContextKind
. For multi-kind contexts, this value
is ContextKind.MULTI
and the kinds within the context can be inspected with
getIndividualContext(int)
or getIndividualContext(String)
.
ContextBuilder.kind(ContextKind)
public boolean isMultiple()
If this value is true, then getKind()
is guaranteed to be
ContextKind.MULTI
, and you can inspect the individual contexts for each kind
with getIndividualContext(int)
or getIndividualContext(ContextKind)
.
If this value is false, then getKind()
is guaranteed to return a value that
is not ContextKind.MULTI
.
public java.lang.String getKey()
key
attribute.
For a single-kind context, this value is set by one of the LDContext factory methods
or builders (create(String)
, create(ContextKind, String)
,
builder(String)
, builder(ContextKind, String)
).
For a multi-kind context, there is no single value and getKey()
returns an
empty string. Use getIndividualContext(int)
or getIndividualContext(String)
to inspect the LDContext for a particular kind, then call getKey()
on it.
This value is never null.
ContextBuilder.key(String)
public java.lang.String getName()
name
attribute.
For a single-kind context, this value is set by ContextBuilder.name(String)
.
It is null if no value was set.
For a multi-kind context, there is no single value and getName()
returns null.
Use getIndividualContext(int)
or getIndividualContext(String)
to
inspect the LDContext for a particular kind, then call getName()
on it.
ContextBuilder.name(String)
public boolean isAnonymous()
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.
ContextBuilder.anonymous(boolean)
public LDValue getValue(java.lang.String attributeName)
This includes only attributes that are addressable in evaluations-- not metadata such
as getPrivateAttribute(int)
.
For a single-kind context, the attribute name can be any custom attribute that was set
by methods like ContextBuilder.set(String, boolean)
. It can also be one of the
built-in ones like "kind", "key", or "name"; in such cases, it is equivalent to
getKind()
, getKey()
, or getName()
, except that the value is
returned using the general-purpose LDValue
type.
For a multi-kind context, the only supported attribute name is "kind". Use
getIndividualContext(int)
or getIndividualContext(ContextKind)
to
inspect the LDContext for a particular kind and then get its attributes.
This method does not support complex expressions for getting individual values out of
JSON objects or arrays, such as "/address/street". Use getValue(AttributeRef)
with an AttributeRef
for that purpose.
If the value is found, the return value is the attribute value, using the type
LDValue
to represent a value of any JSON type.
If there is no such attribute, the return value is LDValue.ofNull()
(the method
never returns a Java null
). An attribute that actually exists cannot have a null
value.
attributeName
- the desired attribute nameLDValue.ofNull()
getValue(AttributeRef)
,
ContextBuilder.set(String, String)
public LDValue getValue(AttributeRef attributeRef)
AttributeRef
.
This includes only attributes that are addressable in evaluations-- not metadata such
as getPrivateAttribute(int)
.
This implements the same behavior that the SDK uses to resolve attribute references
during a flag evaluation. In a single-kind context, the AttributeRef
can
represent a simple attribute name-- either a built-in one like "name" or "key", or a
custom attribute that was set by methods like ContextBuilder.set(String, String)
--
or, it can be a slash-delimited path using a JSON-Pointer-like syntax. See
AttributeRef
for more details.
For a multi-kind context, the only supported attribute name is "kind". Use
getIndividualContext(int)
or getIndividualContext(ContextKind)
to
inspect the LDContext for a particular kind and then get its attributes.
This method does not support complex expressions for getting individual values out of
JSON objects or arrays, such as "/address/street". Use getValue(AttributeRef)
with an AttributeRef
for that purpose.
If the value is found, the return value is the attribute value, using the type
LDValue
to represent a value of any JSON type.
If there is no such attribute, the return value is LDValue.ofNull()
(the method
never returns a Java null
). An attribute that actually exists cannot have a null
value.
attributeRef
- an attribute referencepublic java.lang.Iterable<java.lang.String> getCustomAttributeNames()
For a single-kind context, this includes all the names that were passed to
any of the overloads of ContextBuilder.set(String, LDValue)
as long as the
values were not null (since a null value in LaunchDarkly is equivalent to the attribute
not being set).
For a multi-kind context, there are no such names.
public int getIndividualContextCount()
For a valid single-kind context, this returns 1. For a multi-kind context, it returns
the number of kinds that were added with createMulti(LDContext...)
or
multiBuilder()
. For an invalid context, it returns zero.
public LDContext getIndividualContext(int index)
If this method is called on a single-kind LDContext, then the only allowable value
for index
is zero, and the return value on success is the same LDContext. If
the method is called on a multi-kind context, then index must be non-negative and
less than the number of kinds (that is, less than the return value of
getIndividualContextCount()
), and the return value on success is one of the
individual LDContexts within.
index
- the zero-based index of the context to getLDContext
, or null if the index was out of rangepublic LDContext getIndividualContext(ContextKind kind)
If this method is called on a single-kind LDContext, then the only allowable value
for kind
is the same as getKind()
, and the return value on success
is the same LDContext. If the method is called on a multi-kind context, then
kind
should be match the kind of one of the contexts that was added with
createMulti(LDContext...)
or multiBuilder()
, and the return value on
success is the corresponding individual LDContext within.
kind
- the context kind to get; if null, defaults to ContextKind.DEFAULT
LDContext
, or null if that kind was not foundpublic LDContext getIndividualContext(java.lang.String kind)
getIndividualContext(ContextKind)
, but specifies the kind as a
plain string.kind
- the context kind to getLDContext
, or null if that kind was not foundpublic int getPrivateAttributeCount()
This is equal to the total number of values passed to ContextBuilder.privateAttributes(String...)
and/or its overload ContextBuilder.privateAttributes(AttributeRef...)
.
public AttributeRef getPrivateAttribute(int index)
index
- a non-negative index that must be less than getPrivateAttributeCount()
AttributeRef
, or null if the index was out of rangepublic java.lang.String getFullyQualifiedKey()
kind
and
key
values.
This value is used whenever LaunchDarkly needs a string identifier based on all of the
kind
and key
values in the context; the SDK may use this for caching
previously seen contexts, for instance.
public java.lang.String toString()
For a valid context, this is currently defined as being the same as the JSON representation,
since that is the simplest way to represent all of the LDContext properties. However,
application code should not rely on toString()
always being the same as the JSON
representation. If you specifically want the latter, use JsonSerialization.serialize(JsonSerializable)
.
For an invalid context, toString()
returns a description of why it is invalid.
toString
in class java.lang.Object
public boolean equals(java.lang.Object other)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object