com.netflix.spectator.api

Class TagListBuilder

java.lang.Object

com.netflix.spectator.api.TagListBuilder

public final class TagListBuilder
extends Object

Builder for creating TagList instances efficiently. This builder can be reused multiple times and provides optimizations for sorted tag insertion to avoid unnecessary sorting operations later. A builder instance is not thread safe and should only be used from a single thread at a time. The user is responsible for managing how to reuse builder instances to avoid initial allocation of the builder each time.

The builder tracks whether tags are added in sorted order and passes this information to the underlying TagList implementation to optimize performance. For best performance, add tags in lexicographically sorted order by key.

Example usage:

 TagListBuilder builder = TagListBuilder.create();
 TagList tags = builder
     .add("app", "myapp")
     .add("env", "prod")
     .add("region", "us-east-1")
     .buildAndReset();
 

The builder can be reused after calling buildAndReset():

 TagList tags1 = builder.add("key1", "value1").buildAndReset();
 TagList tags2 = builder.add("key2", "value2").buildAndReset();
 

Method Summary

Modifier and Type	Method and Description
TagListBuilder	add(String key, String value) Adds a key-value pair to the builder.
TagListBuilder	add(Tag tag) Adds a Tag object to the builder.
TagListBuilder	add(TagList tags) Adds all tags from the provided TagList to this builder.
TagList	buildAndReset() Builds a TagList from the accumulated tags and resets the builder for reuse.
static TagListBuilder	create() Creates a new TagListBuilder instance.
static TagListBuilder	create(TagList baseTags) Creates a new TagListBuilder instance with a set of base tags that will be included in all TagLists built by this builder.
void	reset() Resets the builder to its initial empty state, allowing it to be reused.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static TagListBuilder create()

Creates a new TagListBuilder instance.

Returns:

a new builder instance

create

public static TagListBuilder create(TagList baseTags)

Creates a new TagListBuilder instance with a set of base tags that will be included in all TagLists built by this builder. The base tags are automatically added when the builder is created and after each buildAndReset() call.

Parameters:

baseTags - the base tags to include in all built TagLists, must not be null

Returns:

a new builder instance with the specified base tags

add

public TagListBuilder add(TagList tags)

Adds all tags from the provided TagList to this builder.

Parameters:

tags - the TagList containing tags to add, must not be null

Returns:

this builder for method chaining

add

public TagListBuilder add(String key,
                          String value)

Adds a key-value pair to the builder. Null keys or values are ignored.

For optimal performance, add tags in lexicographically sorted order by key. The builder tracks sort order and passes this information to the underlying TagList implementation to avoid unnecessary sorting operations.

Parameters:

key - the tag key, must not be null

value - the tag value, must not be null

Returns:

this builder for method chaining

add

public TagListBuilder add(Tag tag)

Adds a Tag object to the builder. Null keys or values are ignored.

Parameters:

tag - the tag to add, must not be null and must have non-null key and value

Returns:

this builder for method chaining

reset

public void reset()

Resets the builder to its initial empty state, allowing it to be reused.

buildAndReset

public TagList buildAndReset()

Builds a TagList from the accumulated tags and resets the builder for reuse.

Returns:

a new TagList containing all the added tags