com.unboundid.ldap.sdk.forgerockds.controls

Class W3CTraceContextRequestControl

java.lang.Object

com.unboundid.ldap.sdk.Control

com.unboundid.ldap.sdk.forgerockds.controls.W3CTraceContextRequestControl

All Implemented Interfaces:

java.io.Serializable

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class W3CTraceContextRequestControl
extends Control

This class provides support for an implementation of a request control that may be used to convey a W3C trace context to the Directory Server in support of distributed tracing.
This control is based on an implementation originally created for use in the ForgeRock OpenDJ Directory Server, now known as PingDS. It may be included in any kind of request. It has an OID of 1.3.6.1.4.1.36733.2.1.5.7, and it must have a value with the following encoding:

   W3CTraceContextRequestValue ::= SEQUENCE {
        traceParent     OCTET STRING,
        traceState      OCTET STRING OPTIONAL
   }
 

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	W3C_TRACE_CONTEXT_REQUEST_OID The OID (1.3.6.1.4.1.36733.2.1.5.7) for the W3C trace context request control.

Constructor Summary

Constructors

Constructor and Description
W3CTraceContextRequestControl(Control control) Creates a new W3C trace context request control that has been decoded from the provided generic control.
W3CTraceContextRequestControl(java.lang.String traceParent, java.lang.String traceState) Creates a new instance of this W3C trace context request control with the provided information.
W3CTraceContextRequestControl(java.lang.String traceParent, java.lang.String traceState, boolean isCritical) Creates a new instance of this W3C trace context request control with the provided information.

Method Summary

Modifier and Type	Method and Description
static W3CTraceContextRequestControl	decodeJSONControl(JSONObject controlObject, boolean strict) Attempts to decode the provided object as a JSON representation of a W3C trace context request control.
java.lang.String	getControlName() Retrieves the user-friendly name for this control, if available.
java.lang.String	getTraceParent() Retrieves the value of the "traceparent" header for this control.
java.lang.String	getTraceState() Retrieves the value of the "tracestate" header for this control, if provided.
JSONObject	toJSONControl() Retrieves a representation of this W3C trace context request control as a JSON object.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this LDAP control to the provided buffer.

Methods inherited from class com.unboundid.ldap.sdk.Control

decode, decode, decodeControls, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toString, writeTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

W3C_TRACE_CONTEXT_REQUEST_OID

@NotNull
public static final java.lang.String W3C_TRACE_CONTEXT_REQUEST_OID

The OID (1.3.6.1.4.1.36733.2.1.5.7) for the W3C trace context request control.

See Also:

Constant Field Values

Constructor Detail

W3CTraceContextRequestControl

public W3CTraceContextRequestControl(@NotNull
                                     java.lang.String traceParent,
                                     @Nullable
                                     java.lang.String traceState)

Creates a new instance of this W3C trace context request control with the provided information. It will not be considered critical.

Parameters:

traceParent - The value of the "traceparent" header, as defined in the W3C specification. It must not be null or empty.

traceState - The value of the "tracestate" header. It may be null if no additional vendor-specific state information is needed.

W3CTraceContextRequestControl

public W3CTraceContextRequestControl(@NotNull
                                     java.lang.String traceParent,
                                     @Nullable
                                     java.lang.String traceState,
                                     boolean isCritical)

Creates a new instance of this W3C trace context request control with the provided information. It will not be considered critical.

Parameters:

traceParent - The value of the "traceparent" header, as defined in the W3C specification. It must not be null or empty.

traceState - The value of the "tracestate" header. It may be null if no additional vendor-specific state information is needed.

isCritical - Indicates whether this control should be considered critical.

W3CTraceContextRequestControl

public W3CTraceContextRequestControl(@NotNull
                                     Control control)
                              throws LDAPException

Creates a new W3C trace context request control that has been decoded from the provided generic control.

Parameters:

control - The generic control to decode as a W3C trace context request control. It must not be null.

Throws:

LDAPException - If the provided generic control cannot be decoded as a valid W3C trace context request control.

Method Detail

getTraceParent

@NotNull
public java.lang.String getTraceParent()

Retrieves the value of the "traceparent" header for this control.

Returns:

The value of the "traceparent" header for this control.

getTraceState

@NotNull
public java.lang.String getTraceState()

Retrieves the value of the "tracestate" header for this control, if provided.

Returns:

The value of the "tracestate" header for this control, or null if no such value was provided.

getControlName

@NotNull
public java.lang.String getControlName()

Retrieves the user-friendly name for this control, if available. If no user-friendly name has been defined, then the OID will be returned.

Overrides:

getControlName in class Control

Returns:

The user-friendly name for this control, or the OID if no user-friendly name is available.

toJSONControl

@NotNull
public JSONObject toJSONControl()

Retrieves a representation of this W3C trace context request control as a JSON object. The JSON object uses the following fields:

• oid -- A mandatory string field whose value is the object identifier for this control. For the W3C trace context request control, the OID is "1.3.6.1.4.1.36733.2.1.5.7".
• control-name -- An optional string field whose value is a human-readable name for this control. This field is only intended for descriptive purposes, and when decoding a control, the oid field should be used to identify the type of control.
• criticality -- A mandatory Boolean field used to indicate whether this control is considered critical.
• value-base64 -- An optional string field whose value is a base64-encoded representation of the raw value for this W3C trace context request control. Exactly one of the value-base64 and value-json fields must be present.
• value-json -- An optional JSON object field whose value is a user-friendly representation of the value for this uniqueness request control. Exactly one of the value-base64 and value-json fields must be present, and if the value-json field is used, then it will use the following fields:
  • trace-parent -- A mandatory string field that holds the value of the "traceparent" header for this control.
  • trace-state -- An optional string field that holds the value of the "tracestate" header for this control.

Overrides:

toJSONControl in class Control

Returns:

A JSON object that contains a representation of this control.

decodeJSONControl

@NotNull
public static W3CTraceContextRequestControl decodeJSONControl(@NotNull
                                                                       JSONObject controlObject,
                                                                       boolean strict)
                                                                throws LDAPException

Attempts to decode the provided object as a JSON representation of a W3C trace context request control.

Parameters:

controlObject - The JSON object to be decoded. It must not be null.

strict - Indicates whether to use strict mode when decoding the provided JSON object. If this is true, then this method will throw an exception if the provided JSON object contains any unrecognized fields. If this is false, then unrecognized fields will be ignored.

Returns:

The W3C trace cotnext request control that was decoded from the provided JSON object.

Throws:

LDAPException - If the provided JSON object cannot be parsed as a valid W3C trace context request control.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer)

Appends a string representation of this LDAP control to the provided buffer.

Overrides:

toString in class Control

Parameters:

buffer - The buffer to which to append the string representation of this buffer.