From 80ec0c120bb133b3d3747406be7e4c543b9e0446 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 6 Jun 2017 13:56:55 -0700 Subject: Move internal & common & trace to the new package io.opencensus (#339) --- api/src/main/java/io/opencensus/tags/TagKey.java | 104 +++++++++++++++++ api/src/main/java/io/opencensus/tags/TagMap.java | 141 +++++++++++++++++++++++ 2 files changed, 245 insertions(+) create mode 100644 api/src/main/java/io/opencensus/tags/TagKey.java create mode 100644 api/src/main/java/io/opencensus/tags/TagMap.java (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java new file mode 100644 index 00000000..970ee925 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -0,0 +1,104 @@ +/* + * Copyright 2017, Google Inc. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * http://www.apache.org/licenses/LICENSE-2.0 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import static com.google.common.base.Preconditions.checkArgument; +import static io.opencensus.tags.TagKey.TagType.TAG_BOOLEAN; +import static io.opencensus.tags.TagKey.TagType.TAG_LONG; +import static io.opencensus.tags.TagKey.TagType.TAG_STRING; + +import com.google.auto.value.AutoValue; +import io.opencensus.internal.StringUtil; +import javax.annotation.concurrent.Immutable; + +/** + * A key to a value stored in a {@link TagMap}. + * + * @param The type of value that can be paired with this {@code TagKey}. {@code TagKey}s + * can only be instantiated with types {@code String}, {@code Long}, and {@code Boolean}. + */ +@Immutable +@AutoValue +public abstract class TagKey { + /** The maximum length for a tag key name. */ + public static final int MAX_LENGTH = StringUtil.MAX_LENGTH; + + enum TagType { + TAG_STRING, + TAG_LONG, + TAG_BOOLEAN + } + + TagKey() {} + + /** + * Constructs a {@code TagKey} with the given name. + * + *

The name must meet the following requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
+ * + * @param name the name of the key. + * @throws IllegalArgumentException if the name is not valid. + */ + public static TagKey createStringKey(String name) { + checkArgument(StringUtil.isValid(name)); + return new AutoValue_TagKey(name, TAG_STRING); + } + + /** + * Constructs a {@code TagKey} with the given name. + * + *

The name must meet the following requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
+ * + * @param name the name of the key. + * @throws IllegalArgumentException if the name is not valid. + */ + // TODO(sebright): Make this public once we support types other than String. + static TagKey createLongKey(String name) { + checkArgument(StringUtil.isValid(name)); + return new AutoValue_TagKey(name, TAG_LONG); + } + + /** + * Constructs a {@code TagKey} with the given name. + * + *

The name must meet the following requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
+ * + * @param name the name of the key. + * @throws IllegalArgumentException if the name is not valid. + */ + // TODO(sebright): Make this public once we support types other than String. + static TagKey createBooleanKey(String name) { + checkArgument(StringUtil.isValid(name)); + return new AutoValue_TagKey(name, TAG_BOOLEAN); + } + + abstract String getName(); + + abstract TagType getTagType(); +} diff --git a/api/src/main/java/io/opencensus/tags/TagMap.java b/api/src/main/java/io/opencensus/tags/TagMap.java new file mode 100644 index 00000000..8edbda0d --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TagMap.java @@ -0,0 +1,141 @@ +/* + * Copyright 2017, Google Inc. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * http://www.apache.org/licenses/LICENSE-2.0 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import static com.google.common.base.Preconditions.checkArgument; + +import io.opencensus.internal.StringUtil; +import io.opencensus.tags.TagKey.TagType; +import java.util.Collections; +import java.util.HashMap; +import java.util.Map; +import javax.annotation.concurrent.Immutable; + +/** + * A map from keys to values that can be used to label anything that is associated with a specific + * operation. + * + *

For example, {@code TagMap}s can be used to label stats, log messages, or debugging + * information. + */ +@Immutable +public final class TagMap { + /** The maximum length for a string tag value. */ + public static final int MAX_STRING_LENGTH = StringUtil.MAX_LENGTH; + + // The types of the TagKey and value must match for each entry. + private final Map, Object> tags; + + TagMap(Map, Object> tags) { + this.tags = Collections.unmodifiableMap(new HashMap, Object>(tags)); + } + + Map, Object> getTags() { + return tags; + } + + /** + * Returns a builder based on this {@code TagMap}. + * + * @return a builder based on this {@code TagMap}. + */ + public Builder toBuilder() { + return new Builder(getTags()); + } + + /** Builder for the {@link TagMap} class. */ + public static final class Builder { + private final Map, Object> tags; + + private Builder(Map, Object> tags) { + this.tags = new HashMap, Object>(tags); + } + + Builder() { + this.tags = new HashMap, Object>(); + } + + /** + * Adds the key/value pair regardless of whether the key is present. + * + * @param key the {@code TagKey} which will be set. + * @param value the value to set for the given key. + * @return this + * @throws IllegalArgumentException if either argument is null, the key is the wrong type, or + * the value contains unprintable characters or is longer than {@link + * TagMap#MAX_STRING_LENGTH}. + */ + public Builder set(TagKey key, String value) { + checkArgument(key.getTagType() == TagType.TAG_STRING); + + // TODO(sebright): Consider adding a TagValue class to avoid validating the String every time + // it is set. + checkArgument(StringUtil.isValid(value)); + return setInternal(key, value); + } + + /** + * Adds the key/value pair regardless of whether the key is present. + * + * @param key the {@code TagKey} which will be set. + * @param value the value to set for the given key. + * @return this + * @throws IllegalArgumentException if the key is null or the key is the wrong type. + */ + // TODO(sebright): Make this public once we support types other than String. + Builder set(TagKey key, long value) { + checkArgument(key.getTagType() == TagType.TAG_LONG); + return setInternal(key, value); + } + + /** + * Adds the key/value pair regardless of whether the key is present. + * + * @param key the {@code TagKey} which will be set. + * @param value the value to set for the given key. + * @return this + * @throws IllegalArgumentException if the key is null or the key is the wrong type. + */ + // TODO(sebright): Make this public once we support types other than String. + Builder set(TagKey key, boolean value) { + checkArgument(key.getTagType() == TagType.TAG_BOOLEAN); + return setInternal(key, value); + } + + private Builder setInternal(TagKey key, TagValueT value) { + tags.put(key, value); + return this; + } + + /** + * Removes the key if it exists. + * + * @param key the {@code TagKey} which will be cleared. + * @return this + */ + public Builder clear(TagKey key) { + tags.remove(key); + return this; + } + + /** + * Creates a {@code TagMap} from this builder. + * + * @return a {@code TagMap} with the same tags as this builder. + */ + public TagMap build() { + return new TagMap(new HashMap, Object>(tags)); + } + } +} -- cgit v1.2.3 From 95870ac86d5e2164b7872b1f17a1ba748fa619e0 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Wed, 7 Jun 2017 18:41:15 -0700 Subject: Fix all javadocs warnings and errors and re-enable javadoc for api module. (#344) --- api/src/main/java/io/opencensus/tags/TagKey.java | 1 + 1 file changed, 1 insertion(+) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index 970ee925..efd3e6e9 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -53,6 +53,7 @@ public abstract class TagKey { * * * @param name the name of the key. + * @return a {@code TagKey} with the given name. * @throws IllegalArgumentException if the name is not valid. */ public static TagKey createStringKey(String name) { -- cgit v1.2.3 From 453f93217f3561aeb9fc95984274bdc26751fbb7 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Fri, 9 Jun 2017 08:50:10 -0700 Subject: Temporarily move "tags" package back to "core" directory. The tags API isn't ready to be released, so it should be moved out of the "api" directory. --- api/src/main/java/io/opencensus/tags/TagKey.java | 105 ----------------- api/src/main/java/io/opencensus/tags/TagMap.java | 141 ----------------------- 2 files changed, 246 deletions(-) delete mode 100644 api/src/main/java/io/opencensus/tags/TagKey.java delete mode 100644 api/src/main/java/io/opencensus/tags/TagMap.java (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java deleted file mode 100644 index efd3e6e9..00000000 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ /dev/null @@ -1,105 +0,0 @@ -/* - * Copyright 2017, Google Inc. - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * http://www.apache.org/licenses/LICENSE-2.0 - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package io.opencensus.tags; - -import static com.google.common.base.Preconditions.checkArgument; -import static io.opencensus.tags.TagKey.TagType.TAG_BOOLEAN; -import static io.opencensus.tags.TagKey.TagType.TAG_LONG; -import static io.opencensus.tags.TagKey.TagType.TAG_STRING; - -import com.google.auto.value.AutoValue; -import io.opencensus.internal.StringUtil; -import javax.annotation.concurrent.Immutable; - -/** - * A key to a value stored in a {@link TagMap}. - * - * @param The type of value that can be paired with this {@code TagKey}. {@code TagKey}s - * can only be instantiated with types {@code String}, {@code Long}, and {@code Boolean}. - */ -@Immutable -@AutoValue -public abstract class TagKey { - /** The maximum length for a tag key name. */ - public static final int MAX_LENGTH = StringUtil.MAX_LENGTH; - - enum TagType { - TAG_STRING, - TAG_LONG, - TAG_BOOLEAN - } - - TagKey() {} - - /** - * Constructs a {@code TagKey} with the given name. - * - *

The name must meet the following requirements: - * - *

    - *
  1. It cannot be longer than {@link #MAX_LENGTH}. - *
  2. It can only contain printable ASCII characters. - *
- * - * @param name the name of the key. - * @return a {@code TagKey} with the given name. - * @throws IllegalArgumentException if the name is not valid. - */ - public static TagKey createStringKey(String name) { - checkArgument(StringUtil.isValid(name)); - return new AutoValue_TagKey(name, TAG_STRING); - } - - /** - * Constructs a {@code TagKey} with the given name. - * - *

The name must meet the following requirements: - * - *

    - *
  1. It cannot be longer than {@link #MAX_LENGTH}. - *
  2. It can only contain printable ASCII characters. - *
- * - * @param name the name of the key. - * @throws IllegalArgumentException if the name is not valid. - */ - // TODO(sebright): Make this public once we support types other than String. - static TagKey createLongKey(String name) { - checkArgument(StringUtil.isValid(name)); - return new AutoValue_TagKey(name, TAG_LONG); - } - - /** - * Constructs a {@code TagKey} with the given name. - * - *

The name must meet the following requirements: - * - *

    - *
  1. It cannot be longer than {@link #MAX_LENGTH}. - *
  2. It can only contain printable ASCII characters. - *
- * - * @param name the name of the key. - * @throws IllegalArgumentException if the name is not valid. - */ - // TODO(sebright): Make this public once we support types other than String. - static TagKey createBooleanKey(String name) { - checkArgument(StringUtil.isValid(name)); - return new AutoValue_TagKey(name, TAG_BOOLEAN); - } - - abstract String getName(); - - abstract TagType getTagType(); -} diff --git a/api/src/main/java/io/opencensus/tags/TagMap.java b/api/src/main/java/io/opencensus/tags/TagMap.java deleted file mode 100644 index 8edbda0d..00000000 --- a/api/src/main/java/io/opencensus/tags/TagMap.java +++ /dev/null @@ -1,141 +0,0 @@ -/* - * Copyright 2017, Google Inc. - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * http://www.apache.org/licenses/LICENSE-2.0 - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package io.opencensus.tags; - -import static com.google.common.base.Preconditions.checkArgument; - -import io.opencensus.internal.StringUtil; -import io.opencensus.tags.TagKey.TagType; -import java.util.Collections; -import java.util.HashMap; -import java.util.Map; -import javax.annotation.concurrent.Immutable; - -/** - * A map from keys to values that can be used to label anything that is associated with a specific - * operation. - * - *

For example, {@code TagMap}s can be used to label stats, log messages, or debugging - * information. - */ -@Immutable -public final class TagMap { - /** The maximum length for a string tag value. */ - public static final int MAX_STRING_LENGTH = StringUtil.MAX_LENGTH; - - // The types of the TagKey and value must match for each entry. - private final Map, Object> tags; - - TagMap(Map, Object> tags) { - this.tags = Collections.unmodifiableMap(new HashMap, Object>(tags)); - } - - Map, Object> getTags() { - return tags; - } - - /** - * Returns a builder based on this {@code TagMap}. - * - * @return a builder based on this {@code TagMap}. - */ - public Builder toBuilder() { - return new Builder(getTags()); - } - - /** Builder for the {@link TagMap} class. */ - public static final class Builder { - private final Map, Object> tags; - - private Builder(Map, Object> tags) { - this.tags = new HashMap, Object>(tags); - } - - Builder() { - this.tags = new HashMap, Object>(); - } - - /** - * Adds the key/value pair regardless of whether the key is present. - * - * @param key the {@code TagKey} which will be set. - * @param value the value to set for the given key. - * @return this - * @throws IllegalArgumentException if either argument is null, the key is the wrong type, or - * the value contains unprintable characters or is longer than {@link - * TagMap#MAX_STRING_LENGTH}. - */ - public Builder set(TagKey key, String value) { - checkArgument(key.getTagType() == TagType.TAG_STRING); - - // TODO(sebright): Consider adding a TagValue class to avoid validating the String every time - // it is set. - checkArgument(StringUtil.isValid(value)); - return setInternal(key, value); - } - - /** - * Adds the key/value pair regardless of whether the key is present. - * - * @param key the {@code TagKey} which will be set. - * @param value the value to set for the given key. - * @return this - * @throws IllegalArgumentException if the key is null or the key is the wrong type. - */ - // TODO(sebright): Make this public once we support types other than String. - Builder set(TagKey key, long value) { - checkArgument(key.getTagType() == TagType.TAG_LONG); - return setInternal(key, value); - } - - /** - * Adds the key/value pair regardless of whether the key is present. - * - * @param key the {@code TagKey} which will be set. - * @param value the value to set for the given key. - * @return this - * @throws IllegalArgumentException if the key is null or the key is the wrong type. - */ - // TODO(sebright): Make this public once we support types other than String. - Builder set(TagKey key, boolean value) { - checkArgument(key.getTagType() == TagType.TAG_BOOLEAN); - return setInternal(key, value); - } - - private Builder setInternal(TagKey key, TagValueT value) { - tags.put(key, value); - return this; - } - - /** - * Removes the key if it exists. - * - * @param key the {@code TagKey} which will be cleared. - * @return this - */ - public Builder clear(TagKey key) { - tags.remove(key); - return this; - } - - /** - * Creates a {@code TagMap} from this builder. - * - * @return a {@code TagMap} with the same tags as this builder. - */ - public TagMap build() { - return new TagMap(new HashMap, Object>(tags)); - } - } -} -- cgit v1.2.3 From 92e363fb2daa1a8aee308d3bd5fc20c9e83eeab2 Mon Sep 17 00:00:00 2001 From: sebright Date: Mon, 23 Oct 2017 17:13:14 -0700 Subject: Move stats and tags packages to opencensus-api to prepare for release. (#723) --- .../java/io/opencensus/tags/InternalUtils.java | 31 +++ api/src/main/java/io/opencensus/tags/NoopTags.java | 232 ++++++++++++++++++++ api/src/main/java/io/opencensus/tags/Tag.java | 208 ++++++++++++++++++ .../main/java/io/opencensus/tags/TagContext.java | 99 +++++++++ .../java/io/opencensus/tags/TagContextBuilder.java | 83 +++++++ api/src/main/java/io/opencensus/tags/TagKey.java | 244 +++++++++++++++++++++ api/src/main/java/io/opencensus/tags/TagValue.java | 182 +++++++++++++++ api/src/main/java/io/opencensus/tags/Tagger.java | 78 +++++++ .../main/java/io/opencensus/tags/TaggingState.java | 40 ++++ api/src/main/java/io/opencensus/tags/Tags.java | 104 +++++++++ .../java/io/opencensus/tags/TagsComponent.java | 52 +++++ .../main/java/io/opencensus/tags/package-info.java | 33 +++ .../propagation/TagContextBinarySerializer.java | 51 +++++ .../tags/propagation/TagContextParseException.java | 43 ++++ .../tags/propagation/TagPropagationComponent.java | 31 +++ .../io/opencensus/tags/unsafe/ContextUtils.java | 52 +++++ 16 files changed, 1563 insertions(+) create mode 100644 api/src/main/java/io/opencensus/tags/InternalUtils.java create mode 100644 api/src/main/java/io/opencensus/tags/NoopTags.java create mode 100644 api/src/main/java/io/opencensus/tags/Tag.java create mode 100644 api/src/main/java/io/opencensus/tags/TagContext.java create mode 100644 api/src/main/java/io/opencensus/tags/TagContextBuilder.java create mode 100644 api/src/main/java/io/opencensus/tags/TagKey.java create mode 100644 api/src/main/java/io/opencensus/tags/TagValue.java create mode 100644 api/src/main/java/io/opencensus/tags/Tagger.java create mode 100644 api/src/main/java/io/opencensus/tags/TaggingState.java create mode 100644 api/src/main/java/io/opencensus/tags/Tags.java create mode 100644 api/src/main/java/io/opencensus/tags/TagsComponent.java create mode 100644 api/src/main/java/io/opencensus/tags/package-info.java create mode 100644 api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java create mode 100644 api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java create mode 100644 api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java create mode 100644 api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/InternalUtils.java b/api/src/main/java/io/opencensus/tags/InternalUtils.java new file mode 100644 index 00000000..c55ca7d4 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/InternalUtils.java @@ -0,0 +1,31 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import java.util.Iterator; + +/** + * Internal tagging utilities. + */ +@io.opencensus.common.Internal +public final class InternalUtils { + private InternalUtils() {} + + public static Iterator getTags(TagContext tags) { + return tags.getIterator(); + } +} diff --git a/api/src/main/java/io/opencensus/tags/NoopTags.java b/api/src/main/java/io/opencensus/tags/NoopTags.java new file mode 100644 index 00000000..2267edb0 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/NoopTags.java @@ -0,0 +1,232 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import static com.google.common.base.Preconditions.checkNotNull; + +import com.google.common.base.Preconditions; +import io.opencensus.common.Scope; +import io.opencensus.internal.NoopScope; +import io.opencensus.tags.TagKey.TagKeyBoolean; +import io.opencensus.tags.TagKey.TagKeyLong; +import io.opencensus.tags.TagKey.TagKeyString; +import io.opencensus.tags.TagValue.TagValueBoolean; +import io.opencensus.tags.TagValue.TagValueLong; +import io.opencensus.tags.TagValue.TagValueString; +import io.opencensus.tags.propagation.TagContextBinarySerializer; +import io.opencensus.tags.propagation.TagPropagationComponent; +import java.util.Collections; +import java.util.Iterator; +import javax.annotation.concurrent.Immutable; + +/** No-op implementations of tagging classes. */ +final class NoopTags { + + private NoopTags() {} + + /** + * Returns a {@code TagsComponent} that has a no-op implementation for {@link Tagger}. + * + * @return a {@code TagsComponent} that has a no-op implementation for {@code Tagger}. + */ + static TagsComponent getNoopTagsComponent() { + return NoopTagsComponent.INSTANCE; + } + + /** + * Returns a {@code Tagger} that only produces {@link TagContext}s with no tags. + * + * @return a {@code Tagger} that only produces {@code TagContext}s with no tags. + */ + static Tagger getNoopTagger() { + return NoopTagger.INSTANCE; + } + + /** + * Returns a {@code TagContextBuilder} that ignores all calls to {@link TagContextBuilder#put}. + * + * @return a {@code TagContextBuilder} that ignores all calls to {@link TagContextBuilder#put}. + */ + static TagContextBuilder getNoopTagContextBuilder() { + return NoopTagContextBuilder.INSTANCE; + } + + /** + * Returns a {@code TagContext} that does not contain any tags. + * + * @return a {@code TagContext} that does not contain any tags. + */ + static TagContext getNoopTagContext() { + return NoopTagContext.INSTANCE; + } + + /** Returns a {@code TagPropagationComponent} that contains no-op serializers. */ + static TagPropagationComponent getNoopTagPropagationComponent() { + return NoopTagPropagationComponent.INSTANCE; + } + + /** + * Returns a {@code TagContextBinarySerializer} that serializes all {@code TagContext}s to zero + * bytes and deserializes all inputs to empty {@code TagContext}s. + */ + static TagContextBinarySerializer getNoopTagContextBinarySerializer() { + return NoopTagContextBinarySerializer.INSTANCE; + } + + @Immutable + private static final class NoopTagsComponent extends TagsComponent { + static final TagsComponent INSTANCE = new NoopTagsComponent(); + + @Override + public Tagger getTagger() { + return getNoopTagger(); + } + + @Override + public TagPropagationComponent getTagPropagationComponent() { + return getNoopTagPropagationComponent(); + } + + @Override + public TaggingState getState() { + return TaggingState.DISABLED; + } + + @Override + public void setState(TaggingState state) { + Preconditions.checkNotNull(state, "state"); + } + } + + @Immutable + private static final class NoopTagger extends Tagger { + static final Tagger INSTANCE = new NoopTagger(); + + @Override + public TagContext empty() { + return getNoopTagContext(); + } + + @Override + public TagContext getCurrentTagContext() { + return getNoopTagContext(); + } + + @Override + public TagContextBuilder emptyBuilder() { + return getNoopTagContextBuilder(); + } + + @Override + public TagContextBuilder toBuilder(TagContext tags) { + checkNotNull(tags, "tags"); + return getNoopTagContextBuilder(); + } + + @Override + public TagContextBuilder currentBuilder() { + return getNoopTagContextBuilder(); + } + + @Override + public Scope withTagContext(TagContext tags) { + checkNotNull(tags, "tags"); + return NoopScope.getInstance(); + } + } + + @Immutable + private static final class NoopTagContextBuilder extends TagContextBuilder { + static final TagContextBuilder INSTANCE = new NoopTagContextBuilder(); + + @Override + public TagContextBuilder put(TagKeyString key, TagValueString value) { + checkNotNull(key, "key"); + checkNotNull(value, "value"); + return this; + } + + @Override + public TagContextBuilder put(TagKeyLong key, TagValueLong value) { + checkNotNull(key, "key"); + checkNotNull(value, "value"); + return this; + } + + @Override + public TagContextBuilder put(TagKeyBoolean key, TagValueBoolean value) { + checkNotNull(key, "key"); + checkNotNull(value, "value"); + return this; + } + + @Override + public TagContextBuilder remove(TagKey key) { + checkNotNull(key, "key"); + return this; + } + + @Override + public TagContext build() { + return getNoopTagContext(); + } + + @Override + public Scope buildScoped() { + return NoopScope.getInstance(); + } + } + + @Immutable + private static final class NoopTagContext extends TagContext { + static final TagContext INSTANCE = new NoopTagContext(); + + // TODO(sebright): Is there any way to let the user know that their tags were ignored? + @Override + protected Iterator getIterator() { + return Collections.emptySet().iterator(); + } + } + + @Immutable + private static final class NoopTagPropagationComponent extends TagPropagationComponent { + static final TagPropagationComponent INSTANCE = new NoopTagPropagationComponent(); + + @Override + public TagContextBinarySerializer getBinarySerializer() { + return getNoopTagContextBinarySerializer(); + } + } + + @Immutable + private static final class NoopTagContextBinarySerializer extends TagContextBinarySerializer { + static final TagContextBinarySerializer INSTANCE = new NoopTagContextBinarySerializer(); + static final byte[] EMPTY_BYTE_ARRAY = {}; + + @Override + public byte[] toByteArray(TagContext tags) { + checkNotNull(tags, "tags"); + return EMPTY_BYTE_ARRAY; + } + + @Override + public TagContext fromByteArray(byte[] bytes) { + checkNotNull(bytes, "bytes"); + return getNoopTagContext(); + } + } +} diff --git a/api/src/main/java/io/opencensus/tags/Tag.java b/api/src/main/java/io/opencensus/tags/Tag.java new file mode 100644 index 00000000..a53cd838 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/Tag.java @@ -0,0 +1,208 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import com.google.auto.value.AutoValue; +import io.opencensus.common.Function; +import io.opencensus.tags.TagKey.TagKeyBoolean; +import io.opencensus.tags.TagKey.TagKeyLong; +import io.opencensus.tags.TagKey.TagKeyString; +import io.opencensus.tags.TagValue.TagValueBoolean; +import io.opencensus.tags.TagValue.TagValueLong; +import io.opencensus.tags.TagValue.TagValueString; +import javax.annotation.concurrent.Immutable; + +/** {@link TagKey} paired with a value. */ +@Immutable +public abstract class Tag { + + /** + * Returns the tag's key. + * + * @return the tag's key. + */ + public abstract TagKey getKey(); + + /** + * Returns the associated tag value. + * + * @return the associated tag value. + */ + public abstract TagValue getValue(); + + Tag() {} + + /** + * Applies a function to the tag's key and value. The function that is called depends on the type + * of the tag. This is similar to the visitor pattern. {@code match} also takes a function to + * handle the default case, for backwards compatibility when tag types are added. For example, + * this code serializes a {@code Tag} and tries to handle new tag types by calling {@code + * toString()}. + * + * 

{@code
+   * byte[] serializedValue =
+   *     tag.match(
+   *         stringTag -> serializeString(stringTag.getValue().asString()),
+   *         longTag -> serializeLong(longTag.getValue()),
+   *         booleanTag -> serializeBoolean(booleanTag.getValue()),
+   *         unknownTag -> serializeString(unknownTag.toString()));
+   * }
+ * + *

Without lambdas: + * + * 


+   *   byte[] serializedValue =
+   *       tag.match(
+   *           new Function<TagString, String>() {
+   *            {@literal @}Override
+   *             public String apply(TagString stringTag) {
+   *               return serializeString(stringTag.getValue().asString());
+   *             }
+   *           },
+   *           new Function<TagLong, String>() {
+   *            {@literal @}Override
+   *             public String apply(TagLong longTag) {
+   *               serializeLong(longTag.getValue());
+   *             }
+   *           },
+   *           new Function<TagBoolean, String>() {
+   *            {@literal @}Override
+   *             public String apply(TagBoolean booleanTag) {
+   *               serializeBoolean(booleanTag.getValue());
+   *             }
+   *           },
+   *           new Function<Tag, String>() {
+   *            {@literal @}Override
+   *             public String apply(TagBoolean unknownTag) {
+   *               serializeString(unknownTag.toString());
+   *             }
+   *           });
+   *
+ * + * @param stringFunction the function to call when the tag has a {@code String} value. + * @param longFunction the function to call when the tag has a {@code long} value. + * @param booleanFunction the function to call when the tag has a {@code boolean} value. + * @param defaultFunction the function to call when the tag has a value other than {@code String}, + * {@code long}, or {@code boolean}. + * @param The result type of the function. + * @return The result of calling the function that matches the tag's type. + */ + public abstract T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction); + + /** A tag with a {@code String} key and value. */ + @Immutable + @AutoValue + public abstract static class TagString extends Tag { + TagString() {} + + /** + * Creates a {@code TagString} from the given {@code String} key and value. + * + * @param key the tag key. + * @param value the tag value. + * @return a {@code TagString} with the given key and value. + */ + public static TagString create(TagKeyString key, TagValueString value) { + return new AutoValue_Tag_TagString(key, value); + } + + @Override + public abstract TagKeyString getKey(); + + @Override + public abstract TagValueString getValue(); + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return stringFunction.apply(this); + } + } + + /** A tag with a {@code long} key and value. */ + @Immutable + @AutoValue + public abstract static class TagLong extends Tag { + TagLong() {} + + /** + * Creates a {@code TagLong} from the given {@code long} key and value. + * + * @param key the tag key. + * @param value the tag value. + * @return a {@code TagLong} with the given key and value. + */ + public static TagLong create(TagKeyLong key, TagValueLong value) { + return new AutoValue_Tag_TagLong(key, value); + } + + @Override + public abstract TagKeyLong getKey(); + + @Override + public abstract TagValueLong getValue(); + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return longFunction.apply(this); + } + } + + /** A tag with a {@code boolean} key and value. */ + @Immutable + @AutoValue + public abstract static class TagBoolean extends Tag { + TagBoolean() {} + + /** + * Creates a {@code TagBoolean} from the given {@code boolean} key and value. + * + * @param key the tag key. + * @param value the tag value. + * @return a {@code TagBoolean} with the given key and value. + */ + public static TagBoolean create(TagKeyBoolean key, TagValueBoolean value) { + return new AutoValue_Tag_TagBoolean(key, value); + } + + @Override + public abstract TagKeyBoolean getKey(); + + @Override + public abstract TagValueBoolean getValue(); + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return booleanFunction.apply(this); + } + } +} diff --git a/api/src/main/java/io/opencensus/tags/TagContext.java b/api/src/main/java/io/opencensus/tags/TagContext.java new file mode 100644 index 00000000..be8f0dc1 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TagContext.java @@ -0,0 +1,99 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import com.google.common.collect.HashMultiset; +import com.google.common.collect.ImmutableMultiset; +import com.google.common.collect.Lists; +import com.google.common.collect.Multiset; +import io.opencensus.tags.TagValue.TagValueString; +import java.util.Iterator; +import javax.annotation.concurrent.Immutable; + +/** + * A map from keys to values that can be used to label anything that is associated with a specific + * operation. + * + *

For example, {@code TagContext}s can be used to label stats, log messages, or debugging + * information. + * + *

Keys have type {@link TagKey}. Values have type {@link TagValueString}, though the library + * will support more types in the future, including {@code long} and {@code boolean}. + */ +@Immutable +public abstract class TagContext { + + /** + * Returns an iterator over the tags in this {@code TagContext}. + * + * @return an iterator over the tags in this {@code TagContext}. + */ + // This method is protected to prevent client code from accessing the tags of any TagContext. We + // don't currently support efficient access to tags. However, every TagContext subclass needs to + // provide access to its tags to the stats and tagging implementations by implementing this + // method. If we decide to support access to tags in the future, we can add a public iterator() + // method and implement it for all subclasses by calling getIterator(). + // + // The stats and tagging implementations can access any TagContext's tags through + // io.opencensus.tags.InternalUtils.getTags, which calls this method. + protected abstract Iterator getIterator(); + + @Override + public String toString() { + return "TagContext"; + } + + /** + * Returns true iff the other object is an instance of {@code TagContext} and contains the same + * key-value pairs. Implementations are free to override this method to provide better + * performance. + */ + @Override + public boolean equals(Object other) { + if (!(other instanceof TagContext)) { + return false; + } + TagContext otherTags = (TagContext) other; + Iterator iter1 = getIterator(); + Iterator iter2 = otherTags.getIterator(); + Multiset tags1 = + iter1 == null + ? ImmutableMultiset.of() + : HashMultiset.create(Lists.newArrayList(iter1)); + Multiset tags2 = + iter2 == null + ? ImmutableMultiset.of() + : HashMultiset.create(Lists.newArrayList(iter2)); + return tags1.equals(tags2); + } + + @Override + public final int hashCode() { + int hashCode = 0; + Iterator i = getIterator(); + if (i == null) { + return hashCode; + } + while (i.hasNext()) { + Tag tag = i.next(); + if (tag != null) { + hashCode += tag.hashCode(); + } + } + return hashCode; + } +} diff --git a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java new file mode 100644 index 00000000..bbd6da7c --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java @@ -0,0 +1,83 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import io.opencensus.common.Scope; +import io.opencensus.tags.TagKey.TagKeyBoolean; +import io.opencensus.tags.TagKey.TagKeyLong; +import io.opencensus.tags.TagKey.TagKeyString; +import io.opencensus.tags.TagValue.TagValueBoolean; +import io.opencensus.tags.TagValue.TagValueLong; +import io.opencensus.tags.TagValue.TagValueString; + +/** Builder for the {@link TagContext} class. */ +// TODO(sebright): Decide what to do when 'put' is called with a key that has the same name as an +// existing key, but a different type. We currently keep both keys. +public abstract class TagContextBuilder { + + /** + * Adds the key/value pair regardless of whether the key is present. + * + * @param key the {@code TagKey} which will be set. + * @param value the value to set for the given key. + * @return this + */ + public abstract TagContextBuilder put(TagKeyString key, TagValueString value); + + /** + * Adds the key/value pair regardless of whether the key is present. + * + * @param key the {@code TagKey} which will be set. + * @param value the value to set for the given key. + * @return this + */ + public abstract TagContextBuilder put(TagKeyLong key, TagValueLong value); + + /** + * Adds the key/value pair regardless of whether the key is present. + * + * @param key the {@code TagKey} which will be set. + * @param value the value to set for the given key. + * @return this + */ + public abstract TagContextBuilder put(TagKeyBoolean key, TagValueBoolean value); + + /** + * Removes the key if it exists. + * + * @param key the {@code TagKey} which will be removed. + * @return this + */ + public abstract TagContextBuilder remove(TagKey key); + + /** + * Creates a {@code TagContext} from this builder. + * + * @return a {@code TagContext} with the same tags as this builder. + */ + public abstract TagContext build(); + + /** + * Enters the scope of code where the {@link TagContext} created from this builder is in the + * current context and returns an object that represents that scope. The scope is exited when the + * returned object is closed. + * + * @return an object that defines a scope where the {@code TagContext} created from this builder + * is set to the current context. + */ + public abstract Scope buildScoped(); +} diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java new file mode 100644 index 00000000..943f12d7 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -0,0 +1,244 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import static com.google.common.base.Preconditions.checkArgument; + +import com.google.auto.value.AutoValue; +import io.opencensus.common.Function; +import io.opencensus.internal.StringUtil; +import io.opencensus.tags.TagValue.TagValueString; +import javax.annotation.concurrent.Immutable; + +/** + * A key to a value stored in a {@link TagContext}. + * + *

There is one {@code TagKey} subclass corresponding to each tag value type, so that each key + * can only be paired with a single type of value. For example, {@link TagKeyString} can only be + * used to set {@link TagValueString} values in a {@code TagContext}. + * + *

Each {@code TagKey} has a {@code String} name. Names have a maximum length of {@link + * #MAX_LENGTH} and contain only printable ASCII characters. + * + *

{@code TagKey}s are designed to be used as constants. Declaring each key as a constant ensures + * that the keys have consistent value types and prevents key names from being validated multiple + * times. + */ +@Immutable +public abstract class TagKey { + /** The maximum length for a tag key name. The value is {@value #MAX_LENGTH}. */ + public static final int MAX_LENGTH = 255; + + TagKey() {} + + public abstract String getName(); + + /** + * Applies a function to the {@code TagKey} subclass. The function that is called depends on the + * type of the tag key. This is similar to the visitor pattern. {@code match} also takes a + * function to handle the default case, for backwards compatibility when tag types are added. For + * example, this code creates a {@code Tag} from a {@code TagKey}. It handles new tag types by + * logging an error and returning a {@code TagKeyString}. + * + * 

{@code
+   * Tag tag =
+   *     tagKey.match(
+   *         stringKey -> TagString.create(stringKey, TagValueString.create("string value")),
+   *         longKey -> TagLong.create(longKey, 100L),
+   *         booleanKey -> TagBoolean.create(booleanKey, true),
+   *         unknownKey -> {
+   *           logger.log(Level.WARNING, "Unknown tag key type: " + unknownKey.toString());
+   *           return TagString.create(
+   *               TagKeyString.create(unknownKey.getName()),
+   *               TagValueString.create("string value"));
+   *         });
+   * }
+ * + *

Without lambdas: + * + * 


+   *   Tag tag =
+   *       tagKey.match(
+   *           new Function<TagKeyString, Tag>() {
+   *            {@literal @}Override
+   *             public Tag apply(TagKeyString stringKey) {
+   *               return TagString.create(stringKey, TagValueString.create("string value"));
+   *             }
+   *           },
+   *           new Function<TagKeyLong, Tag>() {
+   *            {@literal @}Override
+   *             public Tag apply(TagKeyLong longKey) {
+   *               return TagLong.create(longKey, 100L);
+   *             }
+   *           },
+   *           new Function<TagKeyBoolean, Tag>() {
+   *            {@literal @}Override
+   *             public Tag apply(TagKeyBoolean booleanKey) {
+   *               return TagBoolean.create(booleanKey, true);
+   *             }
+   *           },
+   *           new Function<TagKey, Tag>() {
+   *            {@literal @}Override
+   *             public Tag apply(TagKey unknownKey) {
+   *               logger.log(Level.WARNING, "Unknown tag key type: " + unknownKey.toString());
+   *               return TagString.create(
+   *                   TagKeyString.create(unknownKey.getName()),
+   *                   TagValueString.create("string value"));
+   *             }
+   *           });
+   *
+ * + * @param stringFunction the function to call when the {@code TagKey} is a {@code TagKeyString}. + * @param longFunction the function to call when the {@code TagKey} is a {@code TagKeyLong}. + * @param booleanFunction the function to call when the {@code TagKey} is a {@code TagKeyBoolean}. + * @param defaultFunction the function to call when the tag key has a type other than {@code + * String}, {@code long}, or {@code boolean}. + * @param The result type of the function. + * @return The result of calling the function that matches the tag key's type. + */ + // TODO(sebright): Should we make this public in the first release? + public abstract T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction); + + /** + * Determines whether the given {@code String} is a valid tag key. + * + * @param name the tag key name to be validated. + * @return whether the name is valid. + */ + private static boolean isValid(String name) { + return name.length() <= MAX_LENGTH && StringUtil.isPrintableString(name); + } + + /** A {@code TagKey} for values of type {@code String}. */ + @Immutable + @AutoValue + public abstract static class TagKeyString extends TagKey { + + /** + * Constructs a {@code TagKeyString} with the given name. + * + *

The name must meet the following requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
+ * + * @param name the name of the key. + * @return a {@code TagKeyString} with the given name. + * @throws IllegalArgumentException if the name is not valid. + */ + public static TagKeyString create(String name) { + // TODO(sebright): Should we disallow an empty name? + checkArgument(isValid(name)); + return new AutoValue_TagKey_TagKeyString(name); + } + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return stringFunction.apply(this); + } + } + + /** + * A {@code TagKey} for values of type {@code long}. + * + *

Note that {@link TagKeyLong} isn't supported by the implementation yet, so the factory + * method isn't exposed. + */ + @Immutable + @AutoValue + public abstract static class TagKeyLong extends TagKey { + + /** + * Constructs a {@code TagKeyLong} with the given name. + * + *

The name must meet the following requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
+ * + * @param name the name of the key. + * @return a {@code TagKeyLong} with the given name. + * @throws IllegalArgumentException if the name is not valid. + */ + // TODO(sebright): Make this public once we support types other than String. + static TagKeyLong create(String name) { + checkArgument(isValid(name)); + return new AutoValue_TagKey_TagKeyLong(name); + } + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return longFunction.apply(this); + } + } + + /** + * A {@code TagKey} for values of type {@code boolean}. + * + *

Note that {@link TagKeyBoolean} isn't supported by the implementation yet, so the factory + * method isn't exposed. + */ + @Immutable + @AutoValue + public abstract static class TagKeyBoolean extends TagKey { + + /** + * Constructs a {@code TagKeyBoolean} with the given name. + * + *

The name must meet the following requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
+ * + * @param name the name of the key. + * @return a {@code TagKeyBoolean} with the given name. + * @throws IllegalArgumentException if the name is not valid. + */ + // TODO(sebright): Make this public once we support types other than String. + static TagKeyBoolean create(String name) { + checkArgument(isValid(name)); + return new AutoValue_TagKey_TagKeyBoolean(name); + } + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return booleanFunction.apply(this); + } + } +} diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java new file mode 100644 index 00000000..7da713c5 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -0,0 +1,182 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import com.google.auto.value.AutoValue; +import com.google.common.base.Preconditions; +import io.opencensus.common.Function; +import io.opencensus.internal.StringUtil; +import io.opencensus.tags.TagKey.TagKeyBoolean; +import io.opencensus.tags.TagKey.TagKeyLong; +import io.opencensus.tags.TagKey.TagKeyString; +import javax.annotation.concurrent.Immutable; + +/** A validated tag value. */ +@Immutable +public abstract class TagValue { + + TagValue() {} + + /** + * Applies a function to a tag value. The function that is called depends on the type of the + * value. This is similar to the visitor pattern. {@code match} also takes a function to handle + * the default case, for backwards compatibility when tag types are added. + * + * @param stringFunction the function to call when the tag value has type {@code String}. + * @param longFunction the function to call when the tag value has type {@code long}. + * @param booleanFunction the function to call when the tag value has type {@code boolean}. + * @param defaultFunction the function to call when the tag value has a type other than {@code + * String}, {@code long}, or {@code boolean}. + * @param The result type of the function. + * @return The result of calling the function that matches the tag value's type. + */ + public abstract T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction); + + /** + * A validated tag value associated with a {@link TagKeyString}. + * + *

Validation ensures that the {@code String} has a maximum length of {@link #MAX_LENGTH} and + * contains only printable ASCII characters. + */ + @Immutable + @AutoValue + public abstract static class TagValueString extends TagValue { + /** The maximum length for a {@code String} tag value. The value is {@value #MAX_LENGTH}. */ + public static final int MAX_LENGTH = 256; + + TagValueString() {} + + /** + * Constructs a {@code TagValueString} from the given string. The string must meet the following + * requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
+ * + * @param value the tag value. + * @throws IllegalArgumentException if the {@code String} is not valid. + */ + public static TagValueString create(String value) { + Preconditions.checkArgument(isValid(value)); + return new AutoValue_TagValue_TagValueString(value); + } + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return stringFunction.apply(this); + } + + /** + * Returns the tag value as a {@code String}. + * + * @return the tag value as a {@code String}. + */ + public abstract String asString(); + + /** + * Determines whether the given {@code String} is a valid tag value. + * + * @param value the tag value to be validated. + * @return whether the value is valid. + */ + private static boolean isValid(String value) { + return value.length() <= MAX_LENGTH && StringUtil.isPrintableString(value); + } + } + + /** A tag value associated with a {@link TagKeyLong}. */ + @Immutable + @AutoValue + public abstract static class TagValueLong extends TagValue { + + TagValueLong() {} + + /** + * Constructs a {@code TagValueLong} from the given {@code long}. + * + * @param value the tag value. + */ + public static TagValueLong create(long value) { + return new AutoValue_TagValue_TagValueLong(value); + } + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return longFunction.apply(this); + } + + /** + * Returns the tag value as a {@code long}. + * + * @return the tag value as a {@code long}. + */ + public abstract long asLong(); + } + + /** A tag value associated with a {@link TagKeyBoolean}. */ + @Immutable + @AutoValue + public abstract static class TagValueBoolean extends TagValue { + private static final TagValueBoolean TRUE_VALUE = createInternal(true); + private static final TagValueBoolean FALSE_VALUE = createInternal(false); + + TagValueBoolean() {} + + /** + * Constructs a {@code TagValueBoolean} from the given {@code boolean}. + * + * @param value the tag value. + */ + public static TagValueBoolean create(boolean value) { + return value ? TRUE_VALUE : FALSE_VALUE; + } + + private static TagValueBoolean createInternal(boolean value) { + return new AutoValue_TagValue_TagValueBoolean(value); + } + + @Override + public final T match( + Function stringFunction, + Function longFunction, + Function booleanFunction, + Function defaultFunction) { + return booleanFunction.apply(this); + } + + /** + * Returns the tag value as a {@code boolean}. + * + * @return the tag value as a {@code boolean}. + */ + public abstract boolean asBoolean(); + } +} diff --git a/api/src/main/java/io/opencensus/tags/Tagger.java b/api/src/main/java/io/opencensus/tags/Tagger.java new file mode 100644 index 00000000..1d786f71 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/Tagger.java @@ -0,0 +1,78 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import io.opencensus.common.Scope; + +/** + * Object for creating new {@link TagContext}s and {@code TagContext}s based on the current context. + * + *

This class returns {@link TagContextBuilder builders} that can be used to create the + * implementation-dependent {@link TagContext}s. + * + *

Implementations may have different constraints and are free to convert tag contexts to their + * own subtypes. This means callers cannot assume the {@link #getCurrentTagContext() current + * context} is the same instance as the one {@link #withTagContext(TagContext) placed into scope}. + */ +public abstract class Tagger { + + /** + * Returns an empty {@code TagContext}. + * + * @return an empty {@code TagContext}. + */ + public abstract TagContext empty(); + + /** + * Returns the current {@code TagContext}. + * + * @return the current {@code TagContext}. + */ + public abstract TagContext getCurrentTagContext(); + + /** + * Returns a new empty {@code Builder}. + * + * @return a new empty {@code Builder}. + */ + public abstract TagContextBuilder emptyBuilder(); + + /** + * Returns a builder based on this {@code TagContext}. + * + * @return a builder based on this {@code TagContext}. + */ + public abstract TagContextBuilder toBuilder(TagContext tags); + + /** + * Returns a new builder created from the current {@code TagContext}. + * + * @return a new builder created from the current {@code TagContext}. + */ + public abstract TagContextBuilder currentBuilder(); + + /** + * Enters the scope of code where the given {@code TagContext} is in the current context and + * returns an object that represents that scope. The scope is exited when the returned object is + * closed. + * + * @param tags the {@code TagContext} to be set to the current context. + * @return an object that defines a scope where the given {@code TagContext} is set to the current + * context. + */ + public abstract Scope withTagContext(TagContext tags); +} diff --git a/api/src/main/java/io/opencensus/tags/TaggingState.java b/api/src/main/java/io/opencensus/tags/TaggingState.java new file mode 100644 index 00000000..861aca74 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TaggingState.java @@ -0,0 +1,40 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +/** State of the {@link TagsComponent}. */ +public enum TaggingState { + // TODO(sebright): Should we add a state that propagates the tags, but doesn't allow + // modifications? + + /** + * State that fully enables tagging. + * + *

The {@link TagsComponent} can add tags to {@link TagContext}s, propagate {@code TagContext}s + * in the current context, and serialize {@code TagContext}s. + */ + ENABLED, + + /** + * State that disables tagging. + * + *

The {@link TagsComponent} may not add tags to {@link TagContext}s, propagate {@code + * TagContext}s in the current context, or serialize {@code TagContext}s. + */ + // TODO(sebright): Document how this interacts with stats collection. + DISABLED +} diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java new file mode 100644 index 00000000..5378fa5a --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -0,0 +1,104 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import com.google.common.annotations.VisibleForTesting; +import io.opencensus.internal.Provider; +import io.opencensus.tags.propagation.TagPropagationComponent; +import java.util.logging.Level; +import java.util.logging.Logger; + +/** Class for accessing the default {@link TagsComponent}. */ +public final class Tags { + private static final Logger logger = Logger.getLogger(Tags.class.getName()); + + private static final TagsComponent tagsComponent = + loadTagsComponent(TagsComponent.class.getClassLoader()); + + private Tags() {} + + /** + * Returns the default {@code Tagger}. + * + * @return the default {@code Tagger}. + */ + public static Tagger getTagger() { + return tagsComponent.getTagger(); + } + + /** + * Returns the default {@code TagPropagationComponent}. + * + * @return the default {@code TagPropagationComponent}. + */ + public static TagPropagationComponent getTagPropagationComponent() { + return tagsComponent.getTagPropagationComponent(); + } + + /** + * Returns the current {@code TaggingState}. + * + *

When no implementation is available, {@code getState} always returns {@link + * TaggingState#DISABLED}. + * + * @return the current {@code TaggingState}. + */ + public static TaggingState getState() { + return tagsComponent.getState(); + } + + /** + * Sets the current {@code TaggingState}. + * + *

When no implementation is available, {@code setState} has no effect. + * + * @param state the new {@code TaggingState}. + */ + public static void setState(TaggingState state) { + tagsComponent.setState(state); + } + + // Any provider that may be used for TagsComponent can be added here. + @VisibleForTesting + static TagsComponent loadTagsComponent(ClassLoader classLoader) { + try { + // Call Class.forName with literal string name of the class to help shading tools. + return Provider.createInstance( + Class.forName("io.opencensus.impl.tags.TagsComponentImpl", true, classLoader), + TagsComponent.class); + } catch (ClassNotFoundException e) { + logger.log( + Level.FINE, + "Couldn't load full implementation for TagsComponent, now trying to load lite " + + "implementation.", + e); + } + try { + // Call Class.forName with literal string name of the class to help shading tools. + return Provider.createInstance( + Class.forName("io.opencensus.impllite.tags.TagsComponentImplLite", true, classLoader), + TagsComponent.class); + } catch (ClassNotFoundException e) { + logger.log( + Level.FINE, + "Couldn't load lite implementation for TagsComponent, now using " + + "default implementation for TagsComponent.", + e); + } + return NoopTags.getNoopTagsComponent(); + } +} diff --git a/api/src/main/java/io/opencensus/tags/TagsComponent.java b/api/src/main/java/io/opencensus/tags/TagsComponent.java new file mode 100644 index 00000000..755173d8 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/TagsComponent.java @@ -0,0 +1,52 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags; + +import io.opencensus.tags.propagation.TagPropagationComponent; + +/** + * Class that holds the implementation for {@link Tagger} and {@link TagPropagationComponent}. + * + *

All objects returned by methods on {@code TagsComponent} are cacheable. + */ +public abstract class TagsComponent { + + /** Returns the {@link Tagger} for this implementation. */ + public abstract Tagger getTagger(); + + /** Returns the {@link TagPropagationComponent} for this implementation. */ + public abstract TagPropagationComponent getTagPropagationComponent(); + + /** + * Returns the current {@code TaggingState}. + * + *

When no implementation is available, {@code getState} always returns {@link + * TaggingState#DISABLED}. + * + * @return the current {@code TaggingState}. + */ + public abstract TaggingState getState(); + + /** + * Sets the current {@code TaggingState}. + * + *

When no implementation is available, {@code setState} has no effect. + * + * @param state the new {@code TaggingState}. + */ + public abstract void setState(TaggingState state); +} diff --git a/api/src/main/java/io/opencensus/tags/package-info.java b/api/src/main/java/io/opencensus/tags/package-info.java new file mode 100644 index 00000000..2a332f6d --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/package-info.java @@ -0,0 +1,33 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * API for associating tags with scoped operations. + * + *

This package manages a set of tags in the {@code io.grpc.Context}. The tags can be used to + * label anything that is associated with a specific operation. For example, the {@code + * io.opencensus.stats} package labels all stats with the current tags. + * + *

{@link io.opencensus.tags.Tag Tags} are key-value pairs. The {@link io.opencensus.tags.TagKey + * keys} are wrapped {@code String}s, but the values can have multiple types, such as {@code + * String}, {@code long}, and {@code boolean}. They are stored as a map in a {@link + * io.opencensus.tags.TagContext}. + * + *

Note that tags are independent of the tracing data that is propagated in the {@code + * io.grpc.Context}, such as trace ID. + */ +// TODO(sebright): Add code examples after the API is updated to use a TagContext factory. +package io.opencensus.tags; diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java new file mode 100644 index 00000000..e54e5d3d --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java @@ -0,0 +1,51 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags.propagation; + +import io.opencensus.tags.TagContext; + +/** + * Object for serializing and deserializing {@link TagContext}s with the binary format. + * + *

See opencensus-specs + * for the specification of the cross-language binary serialization format. + */ +public abstract class TagContextBinarySerializer { + + /** + * Serializes the {@code TagContext} into the on-the-wire representation. + * + *

This method should be the inverse of {@link #fromByteArray}. + * + * @param tags the {@code TagContext} to serialize. + * @return the on-the-wire representation of a {@code TagContext}. + */ + public abstract byte[] toByteArray(TagContext tags); + + /** + * Creates a {@code TagContext} from the given on-the-wire encoded representation. + * + *

This method should be the inverse of {@link #toByteArray}. + * + * @param bytes on-the-wire representation of a {@code TagContext}. + * @return a {@code TagContext} deserialized from {@code bytes}. + * @throws TagContextParseException if there is a parse error or the serialized {@code TagContext} + * contains invalid tags. + */ + public abstract TagContext fromByteArray(byte[] bytes) throws TagContextParseException; +} diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java new file mode 100644 index 00000000..0174c416 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java @@ -0,0 +1,43 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags.propagation; + +import io.opencensus.tags.TagContext; + +/** Exception thrown when a {@link TagContext} cannot be parsed. */ +public final class TagContextParseException extends Exception { + private static final long serialVersionUID = 0L; + + /** + * Constructs a new {@code TagContextParseException} with the given message. + * + * @param message a message describing the parse error. + */ + public TagContextParseException(String message) { + super(message); + } + + /** + * Constructs a new {@code TagContextParseException} with the given message and cause. + * + * @param message a message describing the parse error. + * @param cause the cause of the parse error. + */ + public TagContextParseException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java b/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java new file mode 100644 index 00000000..c51a845c --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java @@ -0,0 +1,31 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags.propagation; + +import io.opencensus.tags.TagContext; + +/** Object containing all supported {@link TagContext} propagation formats. */ +// TODO(sebright): Add an HTTP serializer. +public abstract class TagPropagationComponent { + + /** + * Returns the {@link TagContextBinarySerializer} for this implementation. + * + * @return the {@code TagContextBinarySerializer} for this implementation. + */ + public abstract TagContextBinarySerializer getBinarySerializer(); +} diff --git a/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java b/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java new file mode 100644 index 00000000..2baf1a2a --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java @@ -0,0 +1,52 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags.unsafe; + +import io.grpc.Context; +import io.opencensus.tags.Tag; +import io.opencensus.tags.TagContext; +import java.util.Collections; +import java.util.Iterator; +import javax.annotation.concurrent.Immutable; + +/** + * Utility methods for accessing the {@link TagContext} contained in the {@link io.grpc.Context}. + * + *

Most code should interact with the current context via the public APIs in {@link + * io.opencensus.tags.TagContext} and avoid accessing {@link #TAG_CONTEXT_KEY} directly. + */ +public final class ContextUtils { + private static final TagContext EMPTY_TAG_CONTEXT = new EmptyTagContext(); + + private ContextUtils() {} + + /** + * The {@link io.grpc.Context.Key} used to interact with the {@code TagContext} contained in the + * {@link io.grpc.Context}. + */ + public static final Context.Key TAG_CONTEXT_KEY = + Context.keyWithDefault("opencensus-tag-context-key", EMPTY_TAG_CONTEXT); + + @Immutable + private static final class EmptyTagContext extends TagContext { + + @Override + protected Iterator getIterator() { + return Collections.emptySet().iterator(); + } + } +} -- cgit v1.2.3 From 2536bd35d6b24fab12695ee973b8a1fbba949b3a Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 17 Oct 2017 13:23:24 -0700 Subject: Remove support for multiple tag types. This commit removes the class hierarchies for TagKey, TagValue, and Tag. The three classes are now concrete AutoValue classes that use Strings for keys and values. The serialization format isn't affected, because it already only supported string tags. --- api/src/main/java/io/opencensus/tags/NoopTags.java | 22 +-- api/src/main/java/io/opencensus/tags/Tag.java | 189 ++---------------- .../main/java/io/opencensus/tags/TagContext.java | 8 +- .../java/io/opencensus/tags/TagContextBuilder.java | 26 +-- api/src/main/java/io/opencensus/tags/TagKey.java | 212 +++------------------ api/src/main/java/io/opencensus/tags/TagValue.java | 177 ++++------------- .../main/java/io/opencensus/tags/package-info.java | 7 +- 7 files changed, 80 insertions(+), 561 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/NoopTags.java b/api/src/main/java/io/opencensus/tags/NoopTags.java index 2267edb0..b7c86a2d 100644 --- a/api/src/main/java/io/opencensus/tags/NoopTags.java +++ b/api/src/main/java/io/opencensus/tags/NoopTags.java @@ -21,12 +21,6 @@ import static com.google.common.base.Preconditions.checkNotNull; import com.google.common.base.Preconditions; import io.opencensus.common.Scope; import io.opencensus.internal.NoopScope; -import io.opencensus.tags.TagKey.TagKeyBoolean; -import io.opencensus.tags.TagKey.TagKeyLong; -import io.opencensus.tags.TagKey.TagKeyString; -import io.opencensus.tags.TagValue.TagValueBoolean; -import io.opencensus.tags.TagValue.TagValueLong; -import io.opencensus.tags.TagValue.TagValueString; import io.opencensus.tags.propagation.TagContextBinarySerializer; import io.opencensus.tags.propagation.TagPropagationComponent; import java.util.Collections; @@ -154,21 +148,7 @@ final class NoopTags { static final TagContextBuilder INSTANCE = new NoopTagContextBuilder(); @Override - public TagContextBuilder put(TagKeyString key, TagValueString value) { - checkNotNull(key, "key"); - checkNotNull(value, "value"); - return this; - } - - @Override - public TagContextBuilder put(TagKeyLong key, TagValueLong value) { - checkNotNull(key, "key"); - checkNotNull(value, "value"); - return this; - } - - @Override - public TagContextBuilder put(TagKeyBoolean key, TagValueBoolean value) { + public TagContextBuilder put(TagKey key, TagValue value) { checkNotNull(key, "key"); checkNotNull(value, "value"); return this; diff --git a/api/src/main/java/io/opencensus/tags/Tag.java b/api/src/main/java/io/opencensus/tags/Tag.java index a53cd838..18a56547 100644 --- a/api/src/main/java/io/opencensus/tags/Tag.java +++ b/api/src/main/java/io/opencensus/tags/Tag.java @@ -17,192 +17,37 @@ package io.opencensus.tags; import com.google.auto.value.AutoValue; -import io.opencensus.common.Function; -import io.opencensus.tags.TagKey.TagKeyBoolean; -import io.opencensus.tags.TagKey.TagKeyLong; -import io.opencensus.tags.TagKey.TagKeyString; -import io.opencensus.tags.TagValue.TagValueBoolean; -import io.opencensus.tags.TagValue.TagValueLong; -import io.opencensus.tags.TagValue.TagValueString; import javax.annotation.concurrent.Immutable; -/** {@link TagKey} paired with a value. */ +/** {@link TagKey} paired with a {@link TagValue}. */ @Immutable +@AutoValue public abstract class Tag { + Tag() {} + /** - * Returns the tag's key. + * Creates a {@code Tag} from the given key and value. * - * @return the tag's key. + * @param key the tag key. + * @param value the tag value. + * @return a {@code Tag} with the given key and value. */ - public abstract TagKey getKey(); + public static Tag create(TagKey key, TagValue value) { + return new AutoValue_Tag(key, value); + } /** - * Returns the associated tag value. + * Returns the tag's key. * - * @return the associated tag value. + * @return the tag's key. */ - public abstract TagValue getValue(); - - Tag() {} + public abstract TagKey getKey(); /** - * Applies a function to the tag's key and value. The function that is called depends on the type - * of the tag. This is similar to the visitor pattern. {@code match} also takes a function to - * handle the default case, for backwards compatibility when tag types are added. For example, - * this code serializes a {@code Tag} and tries to handle new tag types by calling {@code - * toString()}. - * - * 

{@code
-   * byte[] serializedValue =
-   *     tag.match(
-   *         stringTag -> serializeString(stringTag.getValue().asString()),
-   *         longTag -> serializeLong(longTag.getValue()),
-   *         booleanTag -> serializeBoolean(booleanTag.getValue()),
-   *         unknownTag -> serializeString(unknownTag.toString()));
-   * }
+ * Returns the tag's value. * - *

Without lambdas: - * - * 


-   *   byte[] serializedValue =
-   *       tag.match(
-   *           new Function<TagString, String>() {
-   *            {@literal @}Override
-   *             public String apply(TagString stringTag) {
-   *               return serializeString(stringTag.getValue().asString());
-   *             }
-   *           },
-   *           new Function<TagLong, String>() {
-   *            {@literal @}Override
-   *             public String apply(TagLong longTag) {
-   *               serializeLong(longTag.getValue());
-   *             }
-   *           },
-   *           new Function<TagBoolean, String>() {
-   *            {@literal @}Override
-   *             public String apply(TagBoolean booleanTag) {
-   *               serializeBoolean(booleanTag.getValue());
-   *             }
-   *           },
-   *           new Function<Tag, String>() {
-   *            {@literal @}Override
-   *             public String apply(TagBoolean unknownTag) {
-   *               serializeString(unknownTag.toString());
-   *             }
-   *           });
-   *
- * - * @param stringFunction the function to call when the tag has a {@code String} value. - * @param longFunction the function to call when the tag has a {@code long} value. - * @param booleanFunction the function to call when the tag has a {@code boolean} value. - * @param defaultFunction the function to call when the tag has a value other than {@code String}, - * {@code long}, or {@code boolean}. - * @param The result type of the function. - * @return The result of calling the function that matches the tag's type. + * @return the tag's value. */ - public abstract T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction); - - /** A tag with a {@code String} key and value. */ - @Immutable - @AutoValue - public abstract static class TagString extends Tag { - TagString() {} - - /** - * Creates a {@code TagString} from the given {@code String} key and value. - * - * @param key the tag key. - * @param value the tag value. - * @return a {@code TagString} with the given key and value. - */ - public static TagString create(TagKeyString key, TagValueString value) { - return new AutoValue_Tag_TagString(key, value); - } - - @Override - public abstract TagKeyString getKey(); - - @Override - public abstract TagValueString getValue(); - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return stringFunction.apply(this); - } - } - - /** A tag with a {@code long} key and value. */ - @Immutable - @AutoValue - public abstract static class TagLong extends Tag { - TagLong() {} - - /** - * Creates a {@code TagLong} from the given {@code long} key and value. - * - * @param key the tag key. - * @param value the tag value. - * @return a {@code TagLong} with the given key and value. - */ - public static TagLong create(TagKeyLong key, TagValueLong value) { - return new AutoValue_Tag_TagLong(key, value); - } - - @Override - public abstract TagKeyLong getKey(); - - @Override - public abstract TagValueLong getValue(); - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return longFunction.apply(this); - } - } - - /** A tag with a {@code boolean} key and value. */ - @Immutable - @AutoValue - public abstract static class TagBoolean extends Tag { - TagBoolean() {} - - /** - * Creates a {@code TagBoolean} from the given {@code boolean} key and value. - * - * @param key the tag key. - * @param value the tag value. - * @return a {@code TagBoolean} with the given key and value. - */ - public static TagBoolean create(TagKeyBoolean key, TagValueBoolean value) { - return new AutoValue_Tag_TagBoolean(key, value); - } - - @Override - public abstract TagKeyBoolean getKey(); - - @Override - public abstract TagValueBoolean getValue(); - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return booleanFunction.apply(this); - } - } + public abstract TagValue getValue(); } diff --git a/api/src/main/java/io/opencensus/tags/TagContext.java b/api/src/main/java/io/opencensus/tags/TagContext.java index be8f0dc1..8147906b 100644 --- a/api/src/main/java/io/opencensus/tags/TagContext.java +++ b/api/src/main/java/io/opencensus/tags/TagContext.java @@ -20,19 +20,15 @@ import com.google.common.collect.HashMultiset; import com.google.common.collect.ImmutableMultiset; import com.google.common.collect.Lists; import com.google.common.collect.Multiset; -import io.opencensus.tags.TagValue.TagValueString; import java.util.Iterator; import javax.annotation.concurrent.Immutable; /** - * A map from keys to values that can be used to label anything that is associated with a specific - * operation. + * A map from {@link TagKey} to {@link TagValue} that can be used to label anything that is + * associated with a specific operation. * *

For example, {@code TagContext}s can be used to label stats, log messages, or debugging * information. - * - *

Keys have type {@link TagKey}. Values have type {@link TagValueString}, though the library - * will support more types in the future, including {@code long} and {@code boolean}. */ @Immutable public abstract class TagContext { diff --git a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java index bbd6da7c..2ac36455 100644 --- a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java +++ b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java @@ -17,12 +17,6 @@ package io.opencensus.tags; import io.opencensus.common.Scope; -import io.opencensus.tags.TagKey.TagKeyBoolean; -import io.opencensus.tags.TagKey.TagKeyLong; -import io.opencensus.tags.TagKey.TagKeyString; -import io.opencensus.tags.TagValue.TagValueBoolean; -import io.opencensus.tags.TagValue.TagValueLong; -import io.opencensus.tags.TagValue.TagValueString; /** Builder for the {@link TagContext} class. */ // TODO(sebright): Decide what to do when 'put' is called with a key that has the same name as an @@ -36,25 +30,7 @@ public abstract class TagContextBuilder { * @param value the value to set for the given key. * @return this */ - public abstract TagContextBuilder put(TagKeyString key, TagValueString value); - - /** - * Adds the key/value pair regardless of whether the key is present. - * - * @param key the {@code TagKey} which will be set. - * @param value the value to set for the given key. - * @return this - */ - public abstract TagContextBuilder put(TagKeyLong key, TagValueLong value); - - /** - * Adds the key/value pair regardless of whether the key is present. - * - * @param key the {@code TagKey} which will be set. - * @param value the value to set for the given key. - * @return this - */ - public abstract TagContextBuilder put(TagKeyBoolean key, TagValueBoolean value); + public abstract TagContextBuilder put(TagKey key, TagValue value); /** * Removes the key if it exists. diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index 943f12d7..7e532849 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -19,103 +19,52 @@ package io.opencensus.tags; import static com.google.common.base.Preconditions.checkArgument; import com.google.auto.value.AutoValue; -import io.opencensus.common.Function; import io.opencensus.internal.StringUtil; -import io.opencensus.tags.TagValue.TagValueString; import javax.annotation.concurrent.Immutable; /** * A key to a value stored in a {@link TagContext}. * - *

There is one {@code TagKey} subclass corresponding to each tag value type, so that each key - * can only be paired with a single type of value. For example, {@link TagKeyString} can only be - * used to set {@link TagValueString} values in a {@code TagContext}. - * *

Each {@code TagKey} has a {@code String} name. Names have a maximum length of {@link * #MAX_LENGTH} and contain only printable ASCII characters. * - *

{@code TagKey}s are designed to be used as constants. Declaring each key as a constant ensures - * that the keys have consistent value types and prevents key names from being validated multiple - * times. + *

{@code TagKey}s are designed to be used as constants. Declaring each key as a constant + * prevents key names from being validated multiple times. */ @Immutable +@AutoValue public abstract class TagKey { /** The maximum length for a tag key name. The value is {@value #MAX_LENGTH}. */ public static final int MAX_LENGTH = 255; TagKey() {} - public abstract String getName(); - /** - * Applies a function to the {@code TagKey} subclass. The function that is called depends on the - * type of the tag key. This is similar to the visitor pattern. {@code match} also takes a - * function to handle the default case, for backwards compatibility when tag types are added. For - * example, this code creates a {@code Tag} from a {@code TagKey}. It handles new tag types by - * logging an error and returning a {@code TagKeyString}. + * Constructs a {@code TagKey} with the given name. * - * 

{@code
-   * Tag tag =
-   *     tagKey.match(
-   *         stringKey -> TagString.create(stringKey, TagValueString.create("string value")),
-   *         longKey -> TagLong.create(longKey, 100L),
-   *         booleanKey -> TagBoolean.create(booleanKey, true),
-   *         unknownKey -> {
-   *           logger.log(Level.WARNING, "Unknown tag key type: " + unknownKey.toString());
-   *           return TagString.create(
-   *               TagKeyString.create(unknownKey.getName()),
-   *               TagValueString.create("string value"));
-   *         });
-   * }
+ *

The name must meet the following requirements: * - *

Without lambdas: + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
* - * 

-   *   Tag tag =
-   *       tagKey.match(
-   *           new Function<TagKeyString, Tag>() {
-   *            {@literal @}Override
-   *             public Tag apply(TagKeyString stringKey) {
-   *               return TagString.create(stringKey, TagValueString.create("string value"));
-   *             }
-   *           },
-   *           new Function<TagKeyLong, Tag>() {
-   *            {@literal @}Override
-   *             public Tag apply(TagKeyLong longKey) {
-   *               return TagLong.create(longKey, 100L);
-   *             }
-   *           },
-   *           new Function<TagKeyBoolean, Tag>() {
-   *            {@literal @}Override
-   *             public Tag apply(TagKeyBoolean booleanKey) {
-   *               return TagBoolean.create(booleanKey, true);
-   *             }
-   *           },
-   *           new Function<TagKey, Tag>() {
-   *            {@literal @}Override
-   *             public Tag apply(TagKey unknownKey) {
-   *               logger.log(Level.WARNING, "Unknown tag key type: " + unknownKey.toString());
-   *               return TagString.create(
-   *                   TagKeyString.create(unknownKey.getName()),
-   *                   TagValueString.create("string value"));
-   *             }
-   *           });
-   *
+ * @param name the name of the key. + * @return a {@code TagKey} with the given name. + * @throws IllegalArgumentException if the name is not valid. + */ + public static TagKey create(String name) { + // TODO(sebright): Should we disallow an empty name? + checkArgument(isValid(name)); + return new AutoValue_TagKey(name); + } + + /** + * Returns the name of the key. * - * @param stringFunction the function to call when the {@code TagKey} is a {@code TagKeyString}. - * @param longFunction the function to call when the {@code TagKey} is a {@code TagKeyLong}. - * @param booleanFunction the function to call when the {@code TagKey} is a {@code TagKeyBoolean}. - * @param defaultFunction the function to call when the tag key has a type other than {@code - * String}, {@code long}, or {@code boolean}. - * @param The result type of the function. - * @return The result of calling the function that matches the tag key's type. + * @return the name of the key. */ - // TODO(sebright): Should we make this public in the first release? - public abstract T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction); + public abstract String getName(); /** * Determines whether the given {@code String} is a valid tag key. @@ -126,119 +75,4 @@ public abstract class TagKey { private static boolean isValid(String name) { return name.length() <= MAX_LENGTH && StringUtil.isPrintableString(name); } - - /** A {@code TagKey} for values of type {@code String}. */ - @Immutable - @AutoValue - public abstract static class TagKeyString extends TagKey { - - /** - * Constructs a {@code TagKeyString} with the given name. - * - *

The name must meet the following requirements: - * - *

    - *
  1. It cannot be longer than {@link #MAX_LENGTH}. - *
  2. It can only contain printable ASCII characters. - *
- * - * @param name the name of the key. - * @return a {@code TagKeyString} with the given name. - * @throws IllegalArgumentException if the name is not valid. - */ - public static TagKeyString create(String name) { - // TODO(sebright): Should we disallow an empty name? - checkArgument(isValid(name)); - return new AutoValue_TagKey_TagKeyString(name); - } - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return stringFunction.apply(this); - } - } - - /** - * A {@code TagKey} for values of type {@code long}. - * - *

Note that {@link TagKeyLong} isn't supported by the implementation yet, so the factory - * method isn't exposed. - */ - @Immutable - @AutoValue - public abstract static class TagKeyLong extends TagKey { - - /** - * Constructs a {@code TagKeyLong} with the given name. - * - *

The name must meet the following requirements: - * - *

    - *
  1. It cannot be longer than {@link #MAX_LENGTH}. - *
  2. It can only contain printable ASCII characters. - *
- * - * @param name the name of the key. - * @return a {@code TagKeyLong} with the given name. - * @throws IllegalArgumentException if the name is not valid. - */ - // TODO(sebright): Make this public once we support types other than String. - static TagKeyLong create(String name) { - checkArgument(isValid(name)); - return new AutoValue_TagKey_TagKeyLong(name); - } - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return longFunction.apply(this); - } - } - - /** - * A {@code TagKey} for values of type {@code boolean}. - * - *

Note that {@link TagKeyBoolean} isn't supported by the implementation yet, so the factory - * method isn't exposed. - */ - @Immutable - @AutoValue - public abstract static class TagKeyBoolean extends TagKey { - - /** - * Constructs a {@code TagKeyBoolean} with the given name. - * - *

The name must meet the following requirements: - * - *

    - *
  1. It cannot be longer than {@link #MAX_LENGTH}. - *
  2. It can only contain printable ASCII characters. - *
- * - * @param name the name of the key. - * @return a {@code TagKeyBoolean} with the given name. - * @throws IllegalArgumentException if the name is not valid. - */ - // TODO(sebright): Make this public once we support types other than String. - static TagKeyBoolean create(String name) { - checkArgument(isValid(name)); - return new AutoValue_TagKey_TagKeyBoolean(name); - } - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return booleanFunction.apply(this); - } - } } diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index 7da713c5..abd0bda4 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -18,165 +18,54 @@ package io.opencensus.tags; import com.google.auto.value.AutoValue; import com.google.common.base.Preconditions; -import io.opencensus.common.Function; import io.opencensus.internal.StringUtil; -import io.opencensus.tags.TagKey.TagKeyBoolean; -import io.opencensus.tags.TagKey.TagKeyLong; -import io.opencensus.tags.TagKey.TagKeyString; import javax.annotation.concurrent.Immutable; -/** A validated tag value. */ +/** + * A validated tag value. + * + *

Validation ensures that the {@code String} has a maximum length of {@link #MAX_LENGTH} and + * contains only printable ASCII characters. + */ @Immutable +@AutoValue public abstract class TagValue { + /** The maximum length for a tag value. The value is {@value #MAX_LENGTH}. */ + public static final int MAX_LENGTH = 256; TagValue() {} /** - * Applies a function to a tag value. The function that is called depends on the type of the - * value. This is similar to the visitor pattern. {@code match} also takes a function to handle - * the default case, for backwards compatibility when tag types are added. + * Constructs a {@code TagValue} from the given string. The string must meet the following + * requirements: + * + *

    + *
  1. It cannot be longer than {@link #MAX_LENGTH}. + *
  2. It can only contain printable ASCII characters. + *
* - * @param stringFunction the function to call when the tag value has type {@code String}. - * @param longFunction the function to call when the tag value has type {@code long}. - * @param booleanFunction the function to call when the tag value has type {@code boolean}. - * @param defaultFunction the function to call when the tag value has a type other than {@code - * String}, {@code long}, or {@code boolean}. - * @param The result type of the function. - * @return The result of calling the function that matches the tag value's type. + * @param value the tag value. + * @throws IllegalArgumentException if the {@code String} is not valid. */ - public abstract T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction); + public static TagValue create(String value) { + Preconditions.checkArgument(isValid(value)); + return new AutoValue_TagValue(value); + } /** - * A validated tag value associated with a {@link TagKeyString}. + * Returns the tag value as a {@code String}. * - *

Validation ensures that the {@code String} has a maximum length of {@link #MAX_LENGTH} and - * contains only printable ASCII characters. + * @return the tag value as a {@code String}. */ - @Immutable - @AutoValue - public abstract static class TagValueString extends TagValue { - /** The maximum length for a {@code String} tag value. The value is {@value #MAX_LENGTH}. */ - public static final int MAX_LENGTH = 256; - - TagValueString() {} - - /** - * Constructs a {@code TagValueString} from the given string. The string must meet the following - * requirements: - * - *

    - *
  1. It cannot be longer than {@link #MAX_LENGTH}. - *
  2. It can only contain printable ASCII characters. - *
- * - * @param value the tag value. - * @throws IllegalArgumentException if the {@code String} is not valid. - */ - public static TagValueString create(String value) { - Preconditions.checkArgument(isValid(value)); - return new AutoValue_TagValue_TagValueString(value); - } - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return stringFunction.apply(this); - } - - /** - * Returns the tag value as a {@code String}. - * - * @return the tag value as a {@code String}. - */ - public abstract String asString(); - - /** - * Determines whether the given {@code String} is a valid tag value. - * - * @param value the tag value to be validated. - * @return whether the value is valid. - */ - private static boolean isValid(String value) { - return value.length() <= MAX_LENGTH && StringUtil.isPrintableString(value); - } - } - - /** A tag value associated with a {@link TagKeyLong}. */ - @Immutable - @AutoValue - public abstract static class TagValueLong extends TagValue { - - TagValueLong() {} + public abstract String asString(); - /** - * Constructs a {@code TagValueLong} from the given {@code long}. - * - * @param value the tag value. - */ - public static TagValueLong create(long value) { - return new AutoValue_TagValue_TagValueLong(value); - } - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return longFunction.apply(this); - } - - /** - * Returns the tag value as a {@code long}. - * - * @return the tag value as a {@code long}. - */ - public abstract long asLong(); - } - - /** A tag value associated with a {@link TagKeyBoolean}. */ - @Immutable - @AutoValue - public abstract static class TagValueBoolean extends TagValue { - private static final TagValueBoolean TRUE_VALUE = createInternal(true); - private static final TagValueBoolean FALSE_VALUE = createInternal(false); - - TagValueBoolean() {} - - /** - * Constructs a {@code TagValueBoolean} from the given {@code boolean}. - * - * @param value the tag value. - */ - public static TagValueBoolean create(boolean value) { - return value ? TRUE_VALUE : FALSE_VALUE; - } - - private static TagValueBoolean createInternal(boolean value) { - return new AutoValue_TagValue_TagValueBoolean(value); - } - - @Override - public final T match( - Function stringFunction, - Function longFunction, - Function booleanFunction, - Function defaultFunction) { - return booleanFunction.apply(this); - } - - /** - * Returns the tag value as a {@code boolean}. - * - * @return the tag value as a {@code boolean}. - */ - public abstract boolean asBoolean(); + /** + * Determines whether the given {@code String} is a valid tag value. + * + * @param value the tag value to be validated. + * @return whether the value is valid. + */ + private static boolean isValid(String value) { + return value.length() <= MAX_LENGTH && StringUtil.isPrintableString(value); } } diff --git a/api/src/main/java/io/opencensus/tags/package-info.java b/api/src/main/java/io/opencensus/tags/package-info.java index 2a332f6d..e18c68d1 100644 --- a/api/src/main/java/io/opencensus/tags/package-info.java +++ b/api/src/main/java/io/opencensus/tags/package-info.java @@ -22,12 +22,11 @@ * io.opencensus.stats} package labels all stats with the current tags. * *

{@link io.opencensus.tags.Tag Tags} are key-value pairs. The {@link io.opencensus.tags.TagKey - * keys} are wrapped {@code String}s, but the values can have multiple types, such as {@code - * String}, {@code long}, and {@code boolean}. They are stored as a map in a {@link - * io.opencensus.tags.TagContext}. + * keys} and {@link io.opencensus.tags.TagValue values} are wrapped {@code String}s. They are + * stored as a map in a {@link io.opencensus.tags.TagContext}. * *

Note that tags are independent of the tracing data that is propagated in the {@code * io.grpc.Context}, such as trace ID. */ -// TODO(sebright): Add code examples after the API is updated to use a TagContext factory. +// TODO(sebright): Add code examples. package io.opencensus.tags; -- cgit v1.2.3 From fa2c722348bf38ed09879916ef459904f61b504b Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 17 Oct 2017 14:07:39 -0700 Subject: Remove an obsolete TODO. --- api/src/main/java/io/opencensus/tags/TagContextBuilder.java | 2 -- 1 file changed, 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java index 2ac36455..c2828b34 100644 --- a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java +++ b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java @@ -19,8 +19,6 @@ package io.opencensus.tags; import io.opencensus.common.Scope; /** Builder for the {@link TagContext} class. */ -// TODO(sebright): Decide what to do when 'put' is called with a key that has the same name as an -// existing key, but a different type. We currently keep both keys. public abstract class TagContextBuilder { /** -- cgit v1.2.3 From 8b475cb9fc86c645d2ebe70a1f35437511da3b13 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 17 Oct 2017 14:08:08 -0700 Subject: Improve TagContextBuilder.put Javadoc. --- api/src/main/java/io/opencensus/tags/TagContextBuilder.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java index c2828b34..c6c858c6 100644 --- a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java +++ b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java @@ -25,7 +25,7 @@ public abstract class TagContextBuilder { * Adds the key/value pair regardless of whether the key is present. * * @param key the {@code TagKey} which will be set. - * @param value the value to set for the given key. + * @param value the {@code TagValue} to set for the given key. * @return this */ public abstract TagContextBuilder put(TagKey key, TagValue value); -- cgit v1.2.3 From 25bc0f2954a43c989c03fc80db5f836b4140c37a Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 15 Aug 2017 17:01:43 -0700 Subject: Disallow empty tag keys. --- api/src/main/java/io/opencensus/tags/TagKey.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index 7e532849..d68f0b75 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -73,6 +73,6 @@ public abstract class TagKey { * @return whether the name is valid. */ private static boolean isValid(String name) { - return name.length() <= MAX_LENGTH && StringUtil.isPrintableString(name); + return !name.isEmpty() && name.length() <= MAX_LENGTH && StringUtil.isPrintableString(name); } } -- cgit v1.2.3 From 441080fc0da4e9cadf3f90c200ab8c2cfa6d1d6a Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Fri, 27 Oct 2017 15:46:42 -0700 Subject: Change TagValue.MAX_LENGTH to 255, to match TagKey.MAX_LENGTH. --- api/src/main/java/io/opencensus/tags/TagValue.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index abd0bda4..71196051 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -31,7 +31,7 @@ import javax.annotation.concurrent.Immutable; @AutoValue public abstract class TagValue { /** The maximum length for a tag value. The value is {@value #MAX_LENGTH}. */ - public static final int MAX_LENGTH = 256; + public static final int MAX_LENGTH = 255; TagValue() {} -- cgit v1.2.3 From ba5c5b1796d6dfd8ef09573dbcee8145dee5a872 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 31 Oct 2017 18:38:19 -0700 Subject: Make TagContextBinarySerializer.toByteArray throw a checked exception. The first version of the implementation will throw TagContextSerializationException when the serialized TagContext would be larger than 8192 bytes. --- .../propagation/TagContextBinarySerializer.java | 3 +- .../TagContextSerializationException.java | 43 ++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java index e54e5d3d..0baa7b2a 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java @@ -34,8 +34,9 @@ public abstract class TagContextBinarySerializer { * * @param tags the {@code TagContext} to serialize. * @return the on-the-wire representation of a {@code TagContext}. + * @throws TagContextSerializationException if the {@code TagContext} is too large to serialize. */ - public abstract byte[] toByteArray(TagContext tags); + public abstract byte[] toByteArray(TagContext tags) throws TagContextSerializationException; /** * Creates a {@code TagContext} from the given on-the-wire encoded representation. diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java new file mode 100644 index 00000000..b702dd74 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java @@ -0,0 +1,43 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags.propagation; + +import io.opencensus.tags.TagContext; + +/** Exception thrown when a {@link TagContext} cannot be serialized. */ +public final class TagContextSerializationException extends Exception { + private static final long serialVersionUID = 0L; + + /** + * Constructs a new {@code TagContextSerializationException} with the given message. + * + * @param message a message describing the error. + */ + public TagContextSerializationException(String message) { + super(message); + } + + /** + * Constructs a new {@code TagContextSerializationException} with the given message and cause. + * + * @param message a message describing the error. + * @param cause the cause of the error. + */ + public TagContextSerializationException(String message, Throwable cause) { + super(message, cause); + } +} -- cgit v1.2.3 From 6f5b6617f150d04726960818758c1b48bd890373 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 31 Oct 2017 18:47:37 -0700 Subject: Add maximum serialized TagContext size to toByteArray Javadoc. --- .../java/io/opencensus/tags/propagation/TagContextBinarySerializer.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java index 0baa7b2a..d3645e1a 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java @@ -34,7 +34,7 @@ public abstract class TagContextBinarySerializer { * * @param tags the {@code TagContext} to serialize. * @return the on-the-wire representation of a {@code TagContext}. - * @throws TagContextSerializationException if the {@code TagContext} is too large to serialize. + * @throws TagContextSerializationException if the result would be larger than 8192 bytes. */ public abstract byte[] toByteArray(TagContext tags) throws TagContextSerializationException; -- cgit v1.2.3 From 28f8581d5a6947250fc86e00dfe4cb538d01fa85 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 31 Oct 2017 19:00:32 -0700 Subject: Rename TagContextParseException to TagContextDeserializationException. The new name is more consistent with TagContextSerializationException. --- .../propagation/TagContextBinarySerializer.java | 6 +-- .../TagContextDeserializationException.java | 43 ++++++++++++++++++++++ .../tags/propagation/TagContextParseException.java | 43 ---------------------- 3 files changed, 46 insertions(+), 46 deletions(-) create mode 100644 api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java delete mode 100644 api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java index d3645e1a..0f5ea7ac 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java @@ -45,8 +45,8 @@ public abstract class TagContextBinarySerializer { * * @param bytes on-the-wire representation of a {@code TagContext}. * @return a {@code TagContext} deserialized from {@code bytes}. - * @throws TagContextParseException if there is a parse error or the serialized {@code TagContext} - * contains invalid tags. + * @throws TagContextDeserializationException if there is a parse error or the serialized {@code + * TagContext} contains invalid tags. */ - public abstract TagContext fromByteArray(byte[] bytes) throws TagContextParseException; + public abstract TagContext fromByteArray(byte[] bytes) throws TagContextDeserializationException; } diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java new file mode 100644 index 00000000..aa84e495 --- /dev/null +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java @@ -0,0 +1,43 @@ +/* + * Copyright 2017, OpenCensus Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package io.opencensus.tags.propagation; + +import io.opencensus.tags.TagContext; + +/** Exception thrown when a {@link TagContext} cannot be parsed. */ +public final class TagContextDeserializationException extends Exception { + private static final long serialVersionUID = 0L; + + /** + * Constructs a new {@code TagContextParseException} with the given message. + * + * @param message a message describing the parse error. + */ + public TagContextDeserializationException(String message) { + super(message); + } + + /** + * Constructs a new {@code TagContextParseException} with the given message and cause. + * + * @param message a message describing the parse error. + * @param cause the cause of the parse error. + */ + public TagContextDeserializationException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java deleted file mode 100644 index 0174c416..00000000 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextParseException.java +++ /dev/null @@ -1,43 +0,0 @@ -/* - * Copyright 2017, OpenCensus Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package io.opencensus.tags.propagation; - -import io.opencensus.tags.TagContext; - -/** Exception thrown when a {@link TagContext} cannot be parsed. */ -public final class TagContextParseException extends Exception { - private static final long serialVersionUID = 0L; - - /** - * Constructs a new {@code TagContextParseException} with the given message. - * - * @param message a message describing the parse error. - */ - public TagContextParseException(String message) { - super(message); - } - - /** - * Constructs a new {@code TagContextParseException} with the given message and cause. - * - * @param message a message describing the parse error. - * @param cause the cause of the parse error. - */ - public TagContextParseException(String message, Throwable cause) { - super(message, cause); - } -} -- cgit v1.2.3 From 1b68e740608d33c6039a4781fd7c523a0ad54c27 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 31 Oct 2017 19:19:21 -0700 Subject: Don't mention parsing in TagContextDeserializationException Javadoc. --- .../tags/propagation/TagContextDeserializationException.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java index aa84e495..eb8d18ea 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java @@ -25,7 +25,7 @@ public final class TagContextDeserializationException extends Exception { /** * Constructs a new {@code TagContextParseException} with the given message. * - * @param message a message describing the parse error. + * @param message a message describing the error. */ public TagContextDeserializationException(String message) { super(message); @@ -34,8 +34,8 @@ public final class TagContextDeserializationException extends Exception { /** * Constructs a new {@code TagContextParseException} with the given message and cause. * - * @param message a message describing the parse error. - * @param cause the cause of the parse error. + * @param message a message describing the error. + * @param cause the cause of the error. */ public TagContextDeserializationException(String message, Throwable cause) { super(message, cause); -- cgit v1.2.3 From 38c7a2db7acaf72207cd401dd76204097a51dcf9 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 31 Oct 2017 19:23:11 -0700 Subject: Add maximum serialized TagContext size to fromByteArray Javadoc. --- .../io/opencensus/tags/propagation/TagContextBinarySerializer.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java index 0f5ea7ac..5b354629 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java @@ -45,8 +45,8 @@ public abstract class TagContextBinarySerializer { * * @param bytes on-the-wire representation of a {@code TagContext}. * @return a {@code TagContext} deserialized from {@code bytes}. - * @throws TagContextDeserializationException if there is a parse error or the serialized {@code - * TagContext} contains invalid tags. + * @throws TagContextDeserializationException if there is a parse error, the input contains + * invalid tags, or the input is larger than 8192 bytes. */ public abstract TagContext fromByteArray(byte[] bytes) throws TagContextDeserializationException; } -- cgit v1.2.3 From 71478086c27da524ee1097cd40fbe7a2afdd9588 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 31 Oct 2017 19:29:33 -0700 Subject: Avoid specifying maximum size of serialized TagContext. The value will probably be configurable in a future version, and the default could change. --- .../io/opencensus/tags/propagation/TagContextBinarySerializer.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java index 5b354629..f89d7b0d 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java @@ -34,7 +34,8 @@ public abstract class TagContextBinarySerializer { * * @param tags the {@code TagContext} to serialize. * @return the on-the-wire representation of a {@code TagContext}. - * @throws TagContextSerializationException if the result would be larger than 8192 bytes. + * @throws TagContextSerializationException if the result would be larger than the maximum allowed + * serialized size. */ public abstract byte[] toByteArray(TagContext tags) throws TagContextSerializationException; @@ -46,7 +47,7 @@ public abstract class TagContextBinarySerializer { * @param bytes on-the-wire representation of a {@code TagContext}. * @return a {@code TagContext} deserialized from {@code bytes}. * @throws TagContextDeserializationException if there is a parse error, the input contains - * invalid tags, or the input is larger than 8192 bytes. + * invalid tags, or the input is larger than the maximum allowed serialized size. */ public abstract TagContext fromByteArray(byte[] bytes) throws TagContextDeserializationException; } -- cgit v1.2.3 From 6cb4dd2cc949a2602783321da179cb11afb7fc7a Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Fri, 3 Nov 2017 09:25:12 +1100 Subject: Add gradle plugin for google java format. Enforce all files to be formatted. (#771) * Add gradle plugin for google java format. Enforce all files to be formatted. * Fix javadoc comments. * update to google-java-formatter 1.5 * Fix comments and run formatter only for java8. * Formatter works only on java8. --- api/src/main/java/io/opencensus/tags/InternalUtils.java | 4 +--- api/src/main/java/io/opencensus/tags/package-info.java | 4 ++-- 2 files changed, 3 insertions(+), 5 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/InternalUtils.java b/api/src/main/java/io/opencensus/tags/InternalUtils.java index c55ca7d4..734fcf98 100644 --- a/api/src/main/java/io/opencensus/tags/InternalUtils.java +++ b/api/src/main/java/io/opencensus/tags/InternalUtils.java @@ -18,9 +18,7 @@ package io.opencensus.tags; import java.util.Iterator; -/** - * Internal tagging utilities. - */ +/** Internal tagging utilities. */ @io.opencensus.common.Internal public final class InternalUtils { private InternalUtils() {} diff --git a/api/src/main/java/io/opencensus/tags/package-info.java b/api/src/main/java/io/opencensus/tags/package-info.java index e18c68d1..eb19ee77 100644 --- a/api/src/main/java/io/opencensus/tags/package-info.java +++ b/api/src/main/java/io/opencensus/tags/package-info.java @@ -22,8 +22,8 @@ * io.opencensus.stats} package labels all stats with the current tags. * *

{@link io.opencensus.tags.Tag Tags} are key-value pairs. The {@link io.opencensus.tags.TagKey - * keys} and {@link io.opencensus.tags.TagValue values} are wrapped {@code String}s. They are - * stored as a map in a {@link io.opencensus.tags.TagContext}. + * keys} and {@link io.opencensus.tags.TagValue values} are wrapped {@code String}s. They are stored + * as a map in a {@link io.opencensus.tags.TagContext}. * *

Note that tags are independent of the tracing data that is propagated in the {@code * io.grpc.Context}, such as trace ID. -- cgit v1.2.3 From 80b8b631b47e6db4cd3f543adeb4059b14d3033a Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Wed, 8 Nov 2017 13:00:03 -0800 Subject: Deprecate Tags.setState, and throw an exception when it is called after getState. This commit is related to #608. It deprecates Tags.setState and TagsComponent.setState and makes NoopTagsComponent.setState and TagsComponentImplBase.setState throw IllegalStateException when they are called after getState. --- api/src/main/java/io/opencensus/tags/NoopTags.java | 12 ++++++++---- api/src/main/java/io/opencensus/tags/Tags.java | 13 +++++++++++-- api/src/main/java/io/opencensus/tags/TagsComponent.java | 11 ++++++++++- 3 files changed, 29 insertions(+), 7 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/NoopTags.java b/api/src/main/java/io/opencensus/tags/NoopTags.java index b7c86a2d..973a1b40 100644 --- a/api/src/main/java/io/opencensus/tags/NoopTags.java +++ b/api/src/main/java/io/opencensus/tags/NoopTags.java @@ -26,6 +26,7 @@ import io.opencensus.tags.propagation.TagPropagationComponent; import java.util.Collections; import java.util.Iterator; import javax.annotation.concurrent.Immutable; +import javax.annotation.concurrent.ThreadSafe; /** No-op implementations of tagging classes. */ final class NoopTags { @@ -37,8 +38,8 @@ final class NoopTags { * * @return a {@code TagsComponent} that has a no-op implementation for {@code Tagger}. */ - static TagsComponent getNoopTagsComponent() { - return NoopTagsComponent.INSTANCE; + static TagsComponent newNoopTagsComponent() { + return new NoopTagsComponent(); } /** @@ -81,9 +82,9 @@ final class NoopTags { return NoopTagContextBinarySerializer.INSTANCE; } - @Immutable + @ThreadSafe private static final class NoopTagsComponent extends TagsComponent { - static final TagsComponent INSTANCE = new NoopTagsComponent(); + private volatile boolean isRead; @Override public Tagger getTagger() { @@ -97,12 +98,15 @@ final class NoopTags { @Override public TaggingState getState() { + isRead = true; return TaggingState.DISABLED; } @Override + @Deprecated public void setState(TaggingState state) { Preconditions.checkNotNull(state, "state"); + Preconditions.checkState(!isRead, "State was already read, cannot set state."); } } diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index 5378fa5a..8772e8ec 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -55,6 +55,9 @@ public final class Tags { *

When no implementation is available, {@code getState} always returns {@link * TaggingState#DISABLED}. * + *

Once {@link #getState()} is called, subsequent calls to {@link #setState(TaggingState)} will + * throw an {@code IllegalStateException}. + * * @return the current {@code TaggingState}. */ public static TaggingState getState() { @@ -64,10 +67,16 @@ public final class Tags { /** * Sets the current {@code TaggingState}. * - *

When no implementation is available, {@code setState} has no effect. + *

When no implementation is available, {@code setState} does not change the state. * * @param state the new {@code TaggingState}. + * @throws IllegalStateException if {@link #getState()} was previously called. + * @deprecated This method is deprecated because other libraries could cache the result of {@link + * #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in + * initialization. This method throws {@link IllegalStateException} after {@link #getState()} + * has been called, in order to prevent the result of {@code getState()} from changing. */ + @Deprecated public static void setState(TaggingState state) { tagsComponent.setState(state); } @@ -99,6 +108,6 @@ public final class Tags { + "default implementation for TagsComponent.", e); } - return NoopTags.getNoopTagsComponent(); + return NoopTags.newNoopTagsComponent(); } } diff --git a/api/src/main/java/io/opencensus/tags/TagsComponent.java b/api/src/main/java/io/opencensus/tags/TagsComponent.java index 755173d8..076fe48d 100644 --- a/api/src/main/java/io/opencensus/tags/TagsComponent.java +++ b/api/src/main/java/io/opencensus/tags/TagsComponent.java @@ -37,6 +37,9 @@ public abstract class TagsComponent { *

When no implementation is available, {@code getState} always returns {@link * TaggingState#DISABLED}. * + *

Once {@link #getState()} is called, subsequent calls to {@link #setState(TaggingState)} will + * throw an {@code IllegalStateException}. + * * @return the current {@code TaggingState}. */ public abstract TaggingState getState(); @@ -44,9 +47,15 @@ public abstract class TagsComponent { /** * Sets the current {@code TaggingState}. * - *

When no implementation is available, {@code setState} has no effect. + *

When no implementation is available, {@code setState} does not change the state. * * @param state the new {@code TaggingState}. + * @throws IllegalStateException if {@link #getState()} was previously called. + * @deprecated This method is deprecated because other libraries could cache the result of {@link + * #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in + * initialization. This method throws {@link IllegalStateException} after {@code getState()} + * has been called, in order to prevent the result of {@code getState()} from changing. */ + @Deprecated public abstract void setState(TaggingState state); } -- cgit v1.2.3 From 7102022573c6e1c0e215ad1fccf8b1ec1d36818a Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Fri, 10 Nov 2017 12:30:23 -0800 Subject: Avoid guaranteeing that the result of Tags.getState() won't change. --- api/src/main/java/io/opencensus/tags/Tags.java | 2 +- api/src/main/java/io/opencensus/tags/TagsComponent.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index 8772e8ec..593312ae 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -74,7 +74,7 @@ public final class Tags { * @deprecated This method is deprecated because other libraries could cache the result of {@link * #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in * initialization. This method throws {@link IllegalStateException} after {@link #getState()} - * has been called, in order to prevent the result of {@code getState()} from changing. + * has been called, in order to limit changes to the result of {@code getState()}. */ @Deprecated public static void setState(TaggingState state) { diff --git a/api/src/main/java/io/opencensus/tags/TagsComponent.java b/api/src/main/java/io/opencensus/tags/TagsComponent.java index 076fe48d..b0965077 100644 --- a/api/src/main/java/io/opencensus/tags/TagsComponent.java +++ b/api/src/main/java/io/opencensus/tags/TagsComponent.java @@ -54,7 +54,7 @@ public abstract class TagsComponent { * @deprecated This method is deprecated because other libraries could cache the result of {@link * #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in * initialization. This method throws {@link IllegalStateException} after {@code getState()} - * has been called, in order to prevent the result of {@code getState()} from changing. + * has been called, in order to limit changes to the result of {@code getState()}. */ @Deprecated public abstract void setState(TaggingState state); -- cgit v1.2.3 From 933817d0b9cb0cc4b90d750d3ac4aa5e5e96a59a Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Fri, 17 Nov 2017 12:57:48 -0800 Subject: Remove an obsolete TODO from TagKey.java. We decided not to allow empty tag key names in https://github.com/census-instrumentation/opencensus-specs/issues/12. --- api/src/main/java/io/opencensus/tags/TagKey.java | 1 - 1 file changed, 1 deletion(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index d68f0b75..f1304b33 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -54,7 +54,6 @@ public abstract class TagKey { * @throws IllegalArgumentException if the name is not valid. */ public static TagKey create(String name) { - // TODO(sebright): Should we disallow an empty name? checkArgument(isValid(name)); return new AutoValue_TagKey(name); } -- cgit v1.2.3 From dc0ed0bba9d2adc1f3bee8558746560fbdb0f8a8 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Mon, 18 Dec 2017 22:21:10 -0800 Subject: Add more null annotations (issue #359). This commit adds some Nullable annotations that are required by the Checker Framework, but it doesn't change any other code. It also suppresses some Error Prone and FindBugs warnings that conflict with the Checker Framework, since the three tools use different algorithms. --- api/src/main/java/io/opencensus/tags/TagContext.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagContext.java b/api/src/main/java/io/opencensus/tags/TagContext.java index 8147906b..13fde2ac 100644 --- a/api/src/main/java/io/opencensus/tags/TagContext.java +++ b/api/src/main/java/io/opencensus/tags/TagContext.java @@ -21,6 +21,7 @@ import com.google.common.collect.ImmutableMultiset; import com.google.common.collect.Lists; import com.google.common.collect.Multiset; import java.util.Iterator; +import javax.annotation.Nullable; import javax.annotation.concurrent.Immutable; /** @@ -59,7 +60,7 @@ public abstract class TagContext { * performance. */ @Override - public boolean equals(Object other) { + public boolean equals(@Nullable Object other) { if (!(other instanceof TagContext)) { return false; } -- cgit v1.2.3 From 5c151c5f0f813ce88346681d14075001ad229b19 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 19 Dec 2017 17:16:04 -0800 Subject: Add type variables for Checker Framework null analysis (issue #359). --- api/src/main/java/io/opencensus/tags/TagContext.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagContext.java b/api/src/main/java/io/opencensus/tags/TagContext.java index 13fde2ac..bc2a1630 100644 --- a/api/src/main/java/io/opencensus/tags/TagContext.java +++ b/api/src/main/java/io/opencensus/tags/TagContext.java @@ -70,11 +70,11 @@ public abstract class TagContext { Multiset tags1 = iter1 == null ? ImmutableMultiset.of() - : HashMultiset.create(Lists.newArrayList(iter1)); + : HashMultiset.create(Lists.newArrayList(iter1)); Multiset tags2 = iter2 == null ? ImmutableMultiset.of() - : HashMultiset.create(Lists.newArrayList(iter2)); + : HashMultiset.create(Lists.newArrayList(iter2)); return tags1.equals(tags2); } -- cgit v1.2.3 From bbe6b10f7c6b622b4ffd18e98f58d96a8eba3854 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 19 Dec 2017 20:02:00 -0800 Subject: Suppress warnings about missing @Nullable in AutoValue equals methods (#359). The Checker Framework treats Object.equals as having a Nullable annotation on its argument. AutoValue doesn't add any annotations to its generated equals methods, so the Checker Framework produces warnings. I couldn't find a way to suppress Checker Framework warnings in generated code, so I added @SuppressWarnings("nullness") to the abstract classes and used @AutoValue.CopyAnnotations to copy the annotations to the generated classes. --- api/src/main/java/io/opencensus/tags/Tag.java | 3 +++ api/src/main/java/io/opencensus/tags/TagKey.java | 3 +++ api/src/main/java/io/opencensus/tags/TagValue.java | 3 +++ 3 files changed, 9 insertions(+) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tag.java b/api/src/main/java/io/opencensus/tags/Tag.java index 18a56547..90b050d5 100644 --- a/api/src/main/java/io/opencensus/tags/Tag.java +++ b/api/src/main/java/io/opencensus/tags/Tag.java @@ -22,6 +22,9 @@ import javax.annotation.concurrent.Immutable; /** {@link TagKey} paired with a {@link TagValue}. */ @Immutable @AutoValue +// Suppress Checker Framework warning about missing @Nullable in generated equals method. +@AutoValue.CopyAnnotations +@SuppressWarnings("nullness") public abstract class Tag { Tag() {} diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index f1304b33..a6eb802f 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -33,6 +33,9 @@ import javax.annotation.concurrent.Immutable; */ @Immutable @AutoValue +// Suppress Checker Framework warning about missing @Nullable in generated equals method. +@AutoValue.CopyAnnotations +@SuppressWarnings("nullness") public abstract class TagKey { /** The maximum length for a tag key name. The value is {@value #MAX_LENGTH}. */ public static final int MAX_LENGTH = 255; diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index 71196051..bd2894a7 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -29,6 +29,9 @@ import javax.annotation.concurrent.Immutable; */ @Immutable @AutoValue +// Suppress Checker Framework warning about missing @Nullable in generated equals method. +@AutoValue.CopyAnnotations +@SuppressWarnings("nullness") public abstract class TagValue { /** The maximum length for a tag value. The value is {@value #MAX_LENGTH}. */ public static final int MAX_LENGTH = 255; -- cgit v1.2.3 From 2fc0d4dd057ca28e1e9c37d18ebcfac6d2136de9 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 19 Dec 2017 20:02:00 -0800 Subject: Suppress some Checker Framework warnings and add TODOs (issue #359). Fixing these warnings will require significant refactoring. --- api/src/main/java/io/opencensus/tags/Tags.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index 593312ae..f480714d 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -17,6 +17,7 @@ package io.opencensus.tags; import com.google.common.annotations.VisibleForTesting; +import io.opencensus.internal.NullnessUtils; import io.opencensus.internal.Provider; import io.opencensus.tags.propagation.TagPropagationComponent; import java.util.logging.Level; @@ -27,7 +28,7 @@ public final class Tags { private static final Logger logger = Logger.getLogger(Tags.class.getName()); private static final TagsComponent tagsComponent = - loadTagsComponent(TagsComponent.class.getClassLoader()); + loadTagsComponent(NullnessUtils.castNonNull(TagsComponent.class.getClassLoader())); private Tags() {} -- cgit v1.2.3 From a2241dd72616869db521cc18724f7beab85be168 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Wed, 20 Dec 2017 10:46:38 -0800 Subject: Rename NullnessUtils to CheckerFrameworkUtils. --- api/src/main/java/io/opencensus/tags/Tags.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index f480714d..b2162264 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -17,7 +17,7 @@ package io.opencensus.tags; import com.google.common.annotations.VisibleForTesting; -import io.opencensus.internal.NullnessUtils; +import io.opencensus.internal.CheckerFrameworkUtils; import io.opencensus.internal.Provider; import io.opencensus.tags.propagation.TagPropagationComponent; import java.util.logging.Level; @@ -28,7 +28,7 @@ public final class Tags { private static final Logger logger = Logger.getLogger(Tags.class.getName()); private static final TagsComponent tagsComponent = - loadTagsComponent(NullnessUtils.castNonNull(TagsComponent.class.getClassLoader())); + loadTagsComponent(CheckerFrameworkUtils.castNonNull(TagsComponent.class.getClassLoader())); private Tags() {} -- cgit v1.2.3 From fbe01af5eb386508617a91906253e5b5f19fa1be Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Wed, 20 Dec 2017 12:06:50 -0800 Subject: Remove warning suppression related to null ClassLoaders. Class.forName can take a null ClassLoader, so the methods that instantiate the stats, tags, and tracing components can also take null ClassLoaders. --- api/src/main/java/io/opencensus/tags/Tags.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index b2162264..5832ca5d 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -17,18 +17,18 @@ package io.opencensus.tags; import com.google.common.annotations.VisibleForTesting; -import io.opencensus.internal.CheckerFrameworkUtils; import io.opencensus.internal.Provider; import io.opencensus.tags.propagation.TagPropagationComponent; import java.util.logging.Level; import java.util.logging.Logger; +import javax.annotation.Nullable; /** Class for accessing the default {@link TagsComponent}. */ public final class Tags { private static final Logger logger = Logger.getLogger(Tags.class.getName()); private static final TagsComponent tagsComponent = - loadTagsComponent(CheckerFrameworkUtils.castNonNull(TagsComponent.class.getClassLoader())); + loadTagsComponent(TagsComponent.class.getClassLoader()); private Tags() {} @@ -84,7 +84,7 @@ public final class Tags { // Any provider that may be used for TagsComponent can be added here. @VisibleForTesting - static TagsComponent loadTagsComponent(ClassLoader classLoader) { + static TagsComponent loadTagsComponent(@Nullable ClassLoader classLoader) { try { // Call Class.forName with literal string name of the class to help shading tools. return Provider.createInstance( -- cgit v1.2.3 From 33dcccc9279ffc2fdd8206f5d1be40188dd26c82 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Wed, 31 Jan 2018 09:34:02 -0800 Subject: Add '@since' Javadoc tag to all tagging APIs (issue #864). This commit also adds missing Javadocs. --- api/src/main/java/io/opencensus/tags/InternalUtils.java | 11 ++++++++++- api/src/main/java/io/opencensus/tags/Tag.java | 9 ++++++++- api/src/main/java/io/opencensus/tags/TagContext.java | 3 +++ .../main/java/io/opencensus/tags/TagContextBuilder.java | 10 +++++++++- api/src/main/java/io/opencensus/tags/TagKey.java | 10 +++++++++- api/src/main/java/io/opencensus/tags/TagValue.java | 10 +++++++++- api/src/main/java/io/opencensus/tags/Tagger.java | 8 ++++++++ api/src/main/java/io/opencensus/tags/TaggingState.java | 10 +++++++++- api/src/main/java/io/opencensus/tags/Tags.java | 10 +++++++++- api/src/main/java/io/opencensus/tags/TagsComponent.java | 16 ++++++++++++++-- .../tags/propagation/TagContextBinarySerializer.java | 4 ++++ .../propagation/TagContextDeserializationException.java | 8 +++++++- .../propagation/TagContextSerializationException.java | 8 +++++++- .../tags/propagation/TagPropagationComponent.java | 7 ++++++- .../java/io/opencensus/tags/unsafe/ContextUtils.java | 4 ++++ 15 files changed, 116 insertions(+), 12 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/InternalUtils.java b/api/src/main/java/io/opencensus/tags/InternalUtils.java index 734fcf98..944122e1 100644 --- a/api/src/main/java/io/opencensus/tags/InternalUtils.java +++ b/api/src/main/java/io/opencensus/tags/InternalUtils.java @@ -18,11 +18,20 @@ package io.opencensus.tags; import java.util.Iterator; -/** Internal tagging utilities. */ +/** + * Internal tagging utilities. + * + * @since 0.8 + */ @io.opencensus.common.Internal public final class InternalUtils { private InternalUtils() {} + /** + * Internal tag accessor. + * + * @since 0.8 + */ public static Iterator getTags(TagContext tags) { return tags.getIterator(); } diff --git a/api/src/main/java/io/opencensus/tags/Tag.java b/api/src/main/java/io/opencensus/tags/Tag.java index 90b050d5..d5415e02 100644 --- a/api/src/main/java/io/opencensus/tags/Tag.java +++ b/api/src/main/java/io/opencensus/tags/Tag.java @@ -19,7 +19,11 @@ package io.opencensus.tags; import com.google.auto.value.AutoValue; import javax.annotation.concurrent.Immutable; -/** {@link TagKey} paired with a {@link TagValue}. */ +/** + * {@link TagKey} paired with a {@link TagValue}. + * + * @since 0.8 + */ @Immutable @AutoValue // Suppress Checker Framework warning about missing @Nullable in generated equals method. @@ -35,6 +39,7 @@ public abstract class Tag { * @param key the tag key. * @param value the tag value. * @return a {@code Tag} with the given key and value. + * @since 0.8 */ public static Tag create(TagKey key, TagValue value) { return new AutoValue_Tag(key, value); @@ -44,6 +49,7 @@ public abstract class Tag { * Returns the tag's key. * * @return the tag's key. + * @since 0.8 */ public abstract TagKey getKey(); @@ -51,6 +57,7 @@ public abstract class Tag { * Returns the tag's value. * * @return the tag's value. + * @since 0.8 */ public abstract TagValue getValue(); } diff --git a/api/src/main/java/io/opencensus/tags/TagContext.java b/api/src/main/java/io/opencensus/tags/TagContext.java index bc2a1630..841c8ab5 100644 --- a/api/src/main/java/io/opencensus/tags/TagContext.java +++ b/api/src/main/java/io/opencensus/tags/TagContext.java @@ -30,6 +30,8 @@ import javax.annotation.concurrent.Immutable; * *

For example, {@code TagContext}s can be used to label stats, log messages, or debugging * information. + * + * @since 0.8 */ @Immutable public abstract class TagContext { @@ -38,6 +40,7 @@ public abstract class TagContext { * Returns an iterator over the tags in this {@code TagContext}. * * @return an iterator over the tags in this {@code TagContext}. + * @since 0.8 */ // This method is protected to prevent client code from accessing the tags of any TagContext. We // don't currently support efficient access to tags. However, every TagContext subclass needs to diff --git a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java index c6c858c6..f4268968 100644 --- a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java +++ b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java @@ -18,7 +18,11 @@ package io.opencensus.tags; import io.opencensus.common.Scope; -/** Builder for the {@link TagContext} class. */ +/** + * Builder for the {@link TagContext} class. + * + * @since 0.8 + */ public abstract class TagContextBuilder { /** @@ -27,6 +31,7 @@ public abstract class TagContextBuilder { * @param key the {@code TagKey} which will be set. * @param value the {@code TagValue} to set for the given key. * @return this + * @since 0.8 */ public abstract TagContextBuilder put(TagKey key, TagValue value); @@ -35,6 +40,7 @@ public abstract class TagContextBuilder { * * @param key the {@code TagKey} which will be removed. * @return this + * @since 0.8 */ public abstract TagContextBuilder remove(TagKey key); @@ -42,6 +48,7 @@ public abstract class TagContextBuilder { * Creates a {@code TagContext} from this builder. * * @return a {@code TagContext} with the same tags as this builder. + * @since 0.8 */ public abstract TagContext build(); @@ -52,6 +59,7 @@ public abstract class TagContextBuilder { * * @return an object that defines a scope where the {@code TagContext} created from this builder * is set to the current context. + * @since 0.8 */ public abstract Scope buildScoped(); } diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index a6eb802f..bad2fec3 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -30,6 +30,8 @@ import javax.annotation.concurrent.Immutable; * *

{@code TagKey}s are designed to be used as constants. Declaring each key as a constant * prevents key names from being validated multiple times. + * + * @since 0.8 */ @Immutable @AutoValue @@ -37,7 +39,11 @@ import javax.annotation.concurrent.Immutable; @AutoValue.CopyAnnotations @SuppressWarnings("nullness") public abstract class TagKey { - /** The maximum length for a tag key name. The value is {@value #MAX_LENGTH}. */ + /** + * The maximum length for a tag key name. The value is {@value #MAX_LENGTH}. + * + * @since 0.8 + */ public static final int MAX_LENGTH = 255; TagKey() {} @@ -55,6 +61,7 @@ public abstract class TagKey { * @param name the name of the key. * @return a {@code TagKey} with the given name. * @throws IllegalArgumentException if the name is not valid. + * @since 0.8 */ public static TagKey create(String name) { checkArgument(isValid(name)); @@ -65,6 +72,7 @@ public abstract class TagKey { * Returns the name of the key. * * @return the name of the key. + * @since 0.8 */ public abstract String getName(); diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index bd2894a7..07ccc2cc 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -26,6 +26,8 @@ import javax.annotation.concurrent.Immutable; * *

Validation ensures that the {@code String} has a maximum length of {@link #MAX_LENGTH} and * contains only printable ASCII characters. + * + * @since 0.8 */ @Immutable @AutoValue @@ -33,7 +35,11 @@ import javax.annotation.concurrent.Immutable; @AutoValue.CopyAnnotations @SuppressWarnings("nullness") public abstract class TagValue { - /** The maximum length for a tag value. The value is {@value #MAX_LENGTH}. */ + /** + * The maximum length for a tag value. The value is {@value #MAX_LENGTH}. + * + * @since 0.8 + */ public static final int MAX_LENGTH = 255; TagValue() {} @@ -49,6 +55,7 @@ public abstract class TagValue { * * @param value the tag value. * @throws IllegalArgumentException if the {@code String} is not valid. + * @since 0.8 */ public static TagValue create(String value) { Preconditions.checkArgument(isValid(value)); @@ -59,6 +66,7 @@ public abstract class TagValue { * Returns the tag value as a {@code String}. * * @return the tag value as a {@code String}. + * @since 0.8 */ public abstract String asString(); diff --git a/api/src/main/java/io/opencensus/tags/Tagger.java b/api/src/main/java/io/opencensus/tags/Tagger.java index 1d786f71..f3ba0f5b 100644 --- a/api/src/main/java/io/opencensus/tags/Tagger.java +++ b/api/src/main/java/io/opencensus/tags/Tagger.java @@ -27,6 +27,8 @@ import io.opencensus.common.Scope; *

Implementations may have different constraints and are free to convert tag contexts to their * own subtypes. This means callers cannot assume the {@link #getCurrentTagContext() current * context} is the same instance as the one {@link #withTagContext(TagContext) placed into scope}. + * + * @since 0.8 */ public abstract class Tagger { @@ -34,6 +36,7 @@ public abstract class Tagger { * Returns an empty {@code TagContext}. * * @return an empty {@code TagContext}. + * @since 0.8 */ public abstract TagContext empty(); @@ -41,6 +44,7 @@ public abstract class Tagger { * Returns the current {@code TagContext}. * * @return the current {@code TagContext}. + * @since 0.8 */ public abstract TagContext getCurrentTagContext(); @@ -48,6 +52,7 @@ public abstract class Tagger { * Returns a new empty {@code Builder}. * * @return a new empty {@code Builder}. + * @since 0.8 */ public abstract TagContextBuilder emptyBuilder(); @@ -55,6 +60,7 @@ public abstract class Tagger { * Returns a builder based on this {@code TagContext}. * * @return a builder based on this {@code TagContext}. + * @since 0.8 */ public abstract TagContextBuilder toBuilder(TagContext tags); @@ -62,6 +68,7 @@ public abstract class Tagger { * Returns a new builder created from the current {@code TagContext}. * * @return a new builder created from the current {@code TagContext}. + * @since 0.8 */ public abstract TagContextBuilder currentBuilder(); @@ -73,6 +80,7 @@ public abstract class Tagger { * @param tags the {@code TagContext} to be set to the current context. * @return an object that defines a scope where the given {@code TagContext} is set to the current * context. + * @since 0.8 */ public abstract Scope withTagContext(TagContext tags); } diff --git a/api/src/main/java/io/opencensus/tags/TaggingState.java b/api/src/main/java/io/opencensus/tags/TaggingState.java index 861aca74..88970361 100644 --- a/api/src/main/java/io/opencensus/tags/TaggingState.java +++ b/api/src/main/java/io/opencensus/tags/TaggingState.java @@ -16,7 +16,11 @@ package io.opencensus.tags; -/** State of the {@link TagsComponent}. */ +/** + * State of the {@link TagsComponent}. + * + * @since 0.8 + */ public enum TaggingState { // TODO(sebright): Should we add a state that propagates the tags, but doesn't allow // modifications? @@ -26,6 +30,8 @@ public enum TaggingState { * *

The {@link TagsComponent} can add tags to {@link TagContext}s, propagate {@code TagContext}s * in the current context, and serialize {@code TagContext}s. + * + * @since 0.8 */ ENABLED, @@ -34,6 +40,8 @@ public enum TaggingState { * *

The {@link TagsComponent} may not add tags to {@link TagContext}s, propagate {@code * TagContext}s in the current context, or serialize {@code TagContext}s. + * + * @since 0.8 */ // TODO(sebright): Document how this interacts with stats collection. DISABLED diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index 5832ca5d..b784b5f5 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -23,7 +23,11 @@ import java.util.logging.Level; import java.util.logging.Logger; import javax.annotation.Nullable; -/** Class for accessing the default {@link TagsComponent}. */ +/** + * Class for accessing the default {@link TagsComponent}. + * + * @since 0.8 + */ public final class Tags { private static final Logger logger = Logger.getLogger(Tags.class.getName()); @@ -36,6 +40,7 @@ public final class Tags { * Returns the default {@code Tagger}. * * @return the default {@code Tagger}. + * @since 0.8 */ public static Tagger getTagger() { return tagsComponent.getTagger(); @@ -45,6 +50,7 @@ public final class Tags { * Returns the default {@code TagPropagationComponent}. * * @return the default {@code TagPropagationComponent}. + * @since 0.8 */ public static TagPropagationComponent getTagPropagationComponent() { return tagsComponent.getTagPropagationComponent(); @@ -60,6 +66,7 @@ public final class Tags { * throw an {@code IllegalStateException}. * * @return the current {@code TaggingState}. + * @since 0.8 */ public static TaggingState getState() { return tagsComponent.getState(); @@ -76,6 +83,7 @@ public final class Tags { * #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in * initialization. This method throws {@link IllegalStateException} after {@link #getState()} * has been called, in order to limit changes to the result of {@code getState()}. + * @since 0.8 */ @Deprecated public static void setState(TaggingState state) { diff --git a/api/src/main/java/io/opencensus/tags/TagsComponent.java b/api/src/main/java/io/opencensus/tags/TagsComponent.java index b0965077..d34f1951 100644 --- a/api/src/main/java/io/opencensus/tags/TagsComponent.java +++ b/api/src/main/java/io/opencensus/tags/TagsComponent.java @@ -22,13 +22,23 @@ import io.opencensus.tags.propagation.TagPropagationComponent; * Class that holds the implementation for {@link Tagger} and {@link TagPropagationComponent}. * *

All objects returned by methods on {@code TagsComponent} are cacheable. + * + * @since 0.8 */ public abstract class TagsComponent { - /** Returns the {@link Tagger} for this implementation. */ + /** + * Returns the {@link Tagger} for this implementation. + * + * @since 0.8 + */ public abstract Tagger getTagger(); - /** Returns the {@link TagPropagationComponent} for this implementation. */ + /** + * Returns the {@link TagPropagationComponent} for this implementation. + * + * @since 0.8 + */ public abstract TagPropagationComponent getTagPropagationComponent(); /** @@ -41,6 +51,7 @@ public abstract class TagsComponent { * throw an {@code IllegalStateException}. * * @return the current {@code TaggingState}. + * @since 0.8 */ public abstract TaggingState getState(); @@ -55,6 +66,7 @@ public abstract class TagsComponent { * #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in * initialization. This method throws {@link IllegalStateException} after {@code getState()} * has been called, in order to limit changes to the result of {@code getState()}. + * @since 0.8 */ @Deprecated public abstract void setState(TaggingState state); diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java index f89d7b0d..39eb8cee 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java @@ -24,6 +24,8 @@ import io.opencensus.tags.TagContext; *

See opencensus-specs * for the specification of the cross-language binary serialization format. + * + * @since 0.8 */ public abstract class TagContextBinarySerializer { @@ -36,6 +38,7 @@ public abstract class TagContextBinarySerializer { * @return the on-the-wire representation of a {@code TagContext}. * @throws TagContextSerializationException if the result would be larger than the maximum allowed * serialized size. + * @since 0.8 */ public abstract byte[] toByteArray(TagContext tags) throws TagContextSerializationException; @@ -48,6 +51,7 @@ public abstract class TagContextBinarySerializer { * @return a {@code TagContext} deserialized from {@code bytes}. * @throws TagContextDeserializationException if there is a parse error, the input contains * invalid tags, or the input is larger than the maximum allowed serialized size. + * @since 0.8 */ public abstract TagContext fromByteArray(byte[] bytes) throws TagContextDeserializationException; } diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java index eb8d18ea..11dcb59f 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java @@ -18,7 +18,11 @@ package io.opencensus.tags.propagation; import io.opencensus.tags.TagContext; -/** Exception thrown when a {@link TagContext} cannot be parsed. */ +/** + * Exception thrown when a {@link TagContext} cannot be parsed. + * + * @since 0.8 + */ public final class TagContextDeserializationException extends Exception { private static final long serialVersionUID = 0L; @@ -26,6 +30,7 @@ public final class TagContextDeserializationException extends Exception { * Constructs a new {@code TagContextParseException} with the given message. * * @param message a message describing the error. + * @since 0.8 */ public TagContextDeserializationException(String message) { super(message); @@ -36,6 +41,7 @@ public final class TagContextDeserializationException extends Exception { * * @param message a message describing the error. * @param cause the cause of the error. + * @since 0.8 */ public TagContextDeserializationException(String message, Throwable cause) { super(message, cause); diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java index b702dd74..bb3c9b74 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java @@ -18,7 +18,11 @@ package io.opencensus.tags.propagation; import io.opencensus.tags.TagContext; -/** Exception thrown when a {@link TagContext} cannot be serialized. */ +/** + * Exception thrown when a {@link TagContext} cannot be serialized. + * + * @since 0.8 + */ public final class TagContextSerializationException extends Exception { private static final long serialVersionUID = 0L; @@ -26,6 +30,7 @@ public final class TagContextSerializationException extends Exception { * Constructs a new {@code TagContextSerializationException} with the given message. * * @param message a message describing the error. + * @since 0.8 */ public TagContextSerializationException(String message) { super(message); @@ -36,6 +41,7 @@ public final class TagContextSerializationException extends Exception { * * @param message a message describing the error. * @param cause the cause of the error. + * @since 0.8 */ public TagContextSerializationException(String message, Throwable cause) { super(message, cause); diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java b/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java index c51a845c..6ececa79 100644 --- a/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java +++ b/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java @@ -18,7 +18,11 @@ package io.opencensus.tags.propagation; import io.opencensus.tags.TagContext; -/** Object containing all supported {@link TagContext} propagation formats. */ +/** + * Object containing all supported {@link TagContext} propagation formats. + * + * @since 0.8 + */ // TODO(sebright): Add an HTTP serializer. public abstract class TagPropagationComponent { @@ -26,6 +30,7 @@ public abstract class TagPropagationComponent { * Returns the {@link TagContextBinarySerializer} for this implementation. * * @return the {@code TagContextBinarySerializer} for this implementation. + * @since 0.8 */ public abstract TagContextBinarySerializer getBinarySerializer(); } diff --git a/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java b/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java index 2baf1a2a..8936bbbb 100644 --- a/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java +++ b/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java @@ -28,6 +28,8 @@ import javax.annotation.concurrent.Immutable; * *

Most code should interact with the current context via the public APIs in {@link * io.opencensus.tags.TagContext} and avoid accessing {@link #TAG_CONTEXT_KEY} directly. + * + * @since 0.8 */ public final class ContextUtils { private static final TagContext EMPTY_TAG_CONTEXT = new EmptyTagContext(); @@ -37,6 +39,8 @@ public final class ContextUtils { /** * The {@link io.grpc.Context.Key} used to interact with the {@code TagContext} contained in the * {@link io.grpc.Context}. + * + * @since 0.8 */ public static final Context.Key TAG_CONTEXT_KEY = Context.keyWithDefault("opencensus-tag-context-key", EMPTY_TAG_CONTEXT); -- cgit v1.2.3 From f0e9b541d93cc3df67310aa47d12729824c31d5f Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Wed, 21 Feb 2018 21:58:46 -0800 Subject: Add comments to boolean arguments to fix Error Prone warning (BooleanParameter). --- api/src/main/java/io/opencensus/tags/Tags.java | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index b784b5f5..e4c6a579 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -96,7 +96,8 @@ public final class Tags { try { // Call Class.forName with literal string name of the class to help shading tools. return Provider.createInstance( - Class.forName("io.opencensus.impl.tags.TagsComponentImpl", true, classLoader), + Class.forName( + "io.opencensus.impl.tags.TagsComponentImpl", /*initialize=*/ true, classLoader), TagsComponent.class); } catch (ClassNotFoundException e) { logger.log( @@ -108,7 +109,10 @@ public final class Tags { try { // Call Class.forName with literal string name of the class to help shading tools. return Provider.createInstance( - Class.forName("io.opencensus.impllite.tags.TagsComponentImplLite", true, classLoader), + Class.forName( + "io.opencensus.impllite.tags.TagsComponentImplLite", + /*initialize=*/ true, + classLoader), TagsComponent.class); } catch (ClassNotFoundException e) { logger.log( -- cgit v1.2.3 From 1e524dca48c9a9de6bd4e4058138391ff23bea2e Mon Sep 17 00:00:00 2001 From: Eric Gribkoff Date: Mon, 19 Mar 2018 11:10:59 -0700 Subject: Remove usages of guava collections in api/ (#1069) This allows proguard to strip out the com.google.common.collect.* classes on Android --- .../main/java/io/opencensus/tags/TagContext.java | 36 ++++++++++++++-------- 1 file changed, 23 insertions(+), 13 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagContext.java b/api/src/main/java/io/opencensus/tags/TagContext.java index 841c8ab5..e36acdff 100644 --- a/api/src/main/java/io/opencensus/tags/TagContext.java +++ b/api/src/main/java/io/opencensus/tags/TagContext.java @@ -16,10 +16,7 @@ package io.opencensus.tags; -import com.google.common.collect.HashMultiset; -import com.google.common.collect.ImmutableMultiset; -import com.google.common.collect.Lists; -import com.google.common.collect.Multiset; +import java.util.HashMap; import java.util.Iterator; import javax.annotation.Nullable; import javax.annotation.concurrent.Immutable; @@ -70,15 +67,28 @@ public abstract class TagContext { TagContext otherTags = (TagContext) other; Iterator iter1 = getIterator(); Iterator iter2 = otherTags.getIterator(); - Multiset tags1 = - iter1 == null - ? ImmutableMultiset.of() - : HashMultiset.create(Lists.newArrayList(iter1)); - Multiset tags2 = - iter2 == null - ? ImmutableMultiset.of() - : HashMultiset.create(Lists.newArrayList(iter2)); - return tags1.equals(tags2); + HashMap tags = new HashMap(); + while (iter1 != null && iter1.hasNext()) { + Tag tag = iter1.next(); + if (tags.containsKey(tag)) { + tags.put(tag, tags.get(tag) + 1); + } else { + tags.put(tag, 1); + } + } + while (iter2 != null && iter2.hasNext()) { + Tag tag = iter2.next(); + if (!tags.containsKey(tag)) { + return false; + } + int count = tags.get(tag); + if (count > 1) { + tags.put(tag, count - 1); + } else { + tags.remove(tag); + } + } + return tags.isEmpty(); } @Override -- cgit v1.2.3 From 20da2d47707d89c1927b272817ff554cdafb3a90 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 27 Mar 2018 12:28:55 -0700 Subject: Remove @SuppressWarnings("nullness") from all AutoValue classes. This change allows the Checker Framework to check the classes annotated with @AutoValue, even though their generated subclasses are skipped. This commit also fixes some previously suppressed warnings in the ViewData class. --- api/src/main/java/io/opencensus/tags/Tag.java | 3 --- api/src/main/java/io/opencensus/tags/TagKey.java | 3 --- api/src/main/java/io/opencensus/tags/TagValue.java | 3 --- 3 files changed, 9 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tag.java b/api/src/main/java/io/opencensus/tags/Tag.java index d5415e02..9e0a7a82 100644 --- a/api/src/main/java/io/opencensus/tags/Tag.java +++ b/api/src/main/java/io/opencensus/tags/Tag.java @@ -26,9 +26,6 @@ import javax.annotation.concurrent.Immutable; */ @Immutable @AutoValue -// Suppress Checker Framework warning about missing @Nullable in generated equals method. -@AutoValue.CopyAnnotations -@SuppressWarnings("nullness") public abstract class Tag { Tag() {} diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index bad2fec3..ceaa1b80 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -35,9 +35,6 @@ import javax.annotation.concurrent.Immutable; */ @Immutable @AutoValue -// Suppress Checker Framework warning about missing @Nullable in generated equals method. -@AutoValue.CopyAnnotations -@SuppressWarnings("nullness") public abstract class TagKey { /** * The maximum length for a tag key name. The value is {@value #MAX_LENGTH}. diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index 07ccc2cc..5ba71959 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -31,9 +31,6 @@ import javax.annotation.concurrent.Immutable; */ @Immutable @AutoValue -// Suppress Checker Framework warning about missing @Nullable in generated equals method. -@AutoValue.CopyAnnotations -@SuppressWarnings("nullness") public abstract class TagValue { /** * The maximum length for a tag value. The value is {@value #MAX_LENGTH}. -- cgit v1.2.3 From 26110b6cbf41dcf889502022a495576511025335 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 3 Apr 2018 16:37:22 -0700 Subject: Rename "Util" classes to "Utils", for consistency with public "Utils" classes. This commit adds an "s" to TimeUtil, StringUtil, and BaseMessageEventUtil, for consistency with utility classes that have been made public, such as ContextUtils. --- api/src/main/java/io/opencensus/tags/TagKey.java | 4 ++-- api/src/main/java/io/opencensus/tags/TagValue.java | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index ceaa1b80..ba0b91ed 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -19,7 +19,7 @@ package io.opencensus.tags; import static com.google.common.base.Preconditions.checkArgument; import com.google.auto.value.AutoValue; -import io.opencensus.internal.StringUtil; +import io.opencensus.internal.StringUtils; import javax.annotation.concurrent.Immutable; /** @@ -80,6 +80,6 @@ public abstract class TagKey { * @return whether the name is valid. */ private static boolean isValid(String name) { - return !name.isEmpty() && name.length() <= MAX_LENGTH && StringUtil.isPrintableString(name); + return !name.isEmpty() && name.length() <= MAX_LENGTH && StringUtils.isPrintableString(name); } } diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index 5ba71959..95e13002 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -18,7 +18,7 @@ package io.opencensus.tags; import com.google.auto.value.AutoValue; import com.google.common.base.Preconditions; -import io.opencensus.internal.StringUtil; +import io.opencensus.internal.StringUtils; import javax.annotation.concurrent.Immutable; /** @@ -74,6 +74,6 @@ public abstract class TagValue { * @return whether the value is valid. */ private static boolean isValid(String value) { - return value.length() <= MAX_LENGTH && StringUtil.isPrintableString(value); + return value.length() <= MAX_LENGTH && StringUtils.isPrintableString(value); } } -- cgit v1.2.3 From ba8aea851d53764ec2cd45ccb76ff224c8846358 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 3 Apr 2018 16:37:22 -0700 Subject: Remove usages of Guava Precondtions from opencensus-api (issue #1081). This commit replaces the most commonly used precondtion checks with methods in a new utility class, io.opencensus.internal.Utils. --- api/src/main/java/io/opencensus/tags/NoopTags.java | 22 ++++++++++------------ api/src/main/java/io/opencensus/tags/TagKey.java | 5 ++--- api/src/main/java/io/opencensus/tags/TagValue.java | 4 ++-- 3 files changed, 14 insertions(+), 17 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/NoopTags.java b/api/src/main/java/io/opencensus/tags/NoopTags.java index 973a1b40..fb52b164 100644 --- a/api/src/main/java/io/opencensus/tags/NoopTags.java +++ b/api/src/main/java/io/opencensus/tags/NoopTags.java @@ -16,11 +16,9 @@ package io.opencensus.tags; -import static com.google.common.base.Preconditions.checkNotNull; - -import com.google.common.base.Preconditions; import io.opencensus.common.Scope; import io.opencensus.internal.NoopScope; +import io.opencensus.internal.Utils; import io.opencensus.tags.propagation.TagContextBinarySerializer; import io.opencensus.tags.propagation.TagPropagationComponent; import java.util.Collections; @@ -105,8 +103,8 @@ final class NoopTags { @Override @Deprecated public void setState(TaggingState state) { - Preconditions.checkNotNull(state, "state"); - Preconditions.checkState(!isRead, "State was already read, cannot set state."); + Utils.checkNotNull(state, "state"); + Utils.checkState(!isRead, "State was already read, cannot set state."); } } @@ -131,7 +129,7 @@ final class NoopTags { @Override public TagContextBuilder toBuilder(TagContext tags) { - checkNotNull(tags, "tags"); + Utils.checkNotNull(tags, "tags"); return getNoopTagContextBuilder(); } @@ -142,7 +140,7 @@ final class NoopTags { @Override public Scope withTagContext(TagContext tags) { - checkNotNull(tags, "tags"); + Utils.checkNotNull(tags, "tags"); return NoopScope.getInstance(); } } @@ -153,14 +151,14 @@ final class NoopTags { @Override public TagContextBuilder put(TagKey key, TagValue value) { - checkNotNull(key, "key"); - checkNotNull(value, "value"); + Utils.checkNotNull(key, "key"); + Utils.checkNotNull(value, "value"); return this; } @Override public TagContextBuilder remove(TagKey key) { - checkNotNull(key, "key"); + Utils.checkNotNull(key, "key"); return this; } @@ -203,13 +201,13 @@ final class NoopTags { @Override public byte[] toByteArray(TagContext tags) { - checkNotNull(tags, "tags"); + Utils.checkNotNull(tags, "tags"); return EMPTY_BYTE_ARRAY; } @Override public TagContext fromByteArray(byte[] bytes) { - checkNotNull(bytes, "bytes"); + Utils.checkNotNull(bytes, "bytes"); return getNoopTagContext(); } } diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index ba0b91ed..615c2d46 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -16,10 +16,9 @@ package io.opencensus.tags; -import static com.google.common.base.Preconditions.checkArgument; - import com.google.auto.value.AutoValue; import io.opencensus.internal.StringUtils; +import io.opencensus.internal.Utils; import javax.annotation.concurrent.Immutable; /** @@ -61,7 +60,7 @@ public abstract class TagKey { * @since 0.8 */ public static TagKey create(String name) { - checkArgument(isValid(name)); + Utils.checkArgument(isValid(name), "Invalid TagKey name: " + name); return new AutoValue_TagKey(name); } diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index 95e13002..5c1019ff 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -17,8 +17,8 @@ package io.opencensus.tags; import com.google.auto.value.AutoValue; -import com.google.common.base.Preconditions; import io.opencensus.internal.StringUtils; +import io.opencensus.internal.Utils; import javax.annotation.concurrent.Immutable; /** @@ -55,7 +55,7 @@ public abstract class TagValue { * @since 0.8 */ public static TagValue create(String value) { - Preconditions.checkArgument(isValid(value)); + Utils.checkArgument(isValid(value), "Invalid TagValue: " + value); return new AutoValue_TagValue(value); } -- cgit v1.2.3 From 952d64323cf95aa2fe04ddb6188303bac8a5fb35 Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 3 Apr 2018 16:37:22 -0700 Subject: Replace Guava VisibleForTesting in opencensus-api (issue #1081). This commit adds two annotations to replace the uses of Guava's VisibleForTesting annotation in opencensus-api. Each annotation has a more specific meaning than VisibleForTesting, to make the uses of the annotations more informative. DefaultVisibilityForTesting - This annotation replaces the main use of @VisibleForTesting, indicating that an element was changed from private to package-private for testing. PublicForTesting - This annotation is temporary and should be removed as part of issue #977. --- api/src/main/java/io/opencensus/tags/Tags.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java index e4c6a579..07123647 100644 --- a/api/src/main/java/io/opencensus/tags/Tags.java +++ b/api/src/main/java/io/opencensus/tags/Tags.java @@ -16,7 +16,7 @@ package io.opencensus.tags; -import com.google.common.annotations.VisibleForTesting; +import io.opencensus.internal.DefaultVisibilityForTesting; import io.opencensus.internal.Provider; import io.opencensus.tags.propagation.TagPropagationComponent; import java.util.logging.Level; @@ -91,7 +91,7 @@ public final class Tags { } // Any provider that may be used for TagsComponent can be added here. - @VisibleForTesting + @DefaultVisibilityForTesting static TagsComponent loadTagsComponent(@Nullable ClassLoader classLoader) { try { // Call Class.forName with literal string name of the class to help shading tools. -- cgit v1.2.3 From 13a5c96d2602f5af2eafe9c23b9e92955ecf3dff Mon Sep 17 00:00:00 2001 From: Kristen Kozak Date: Tue, 26 Jun 2018 17:22:19 -0700 Subject: Clarify Javadoc for Tagger.withTagContext. See census-instrumentation/opencensus-specs#99. --- api/src/main/java/io/opencensus/tags/Tagger.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/Tagger.java b/api/src/main/java/io/opencensus/tags/Tagger.java index f3ba0f5b..f1e203ad 100644 --- a/api/src/main/java/io/opencensus/tags/Tagger.java +++ b/api/src/main/java/io/opencensus/tags/Tagger.java @@ -73,9 +73,9 @@ public abstract class Tagger { public abstract TagContextBuilder currentBuilder(); /** - * Enters the scope of code where the given {@code TagContext} is in the current context and - * returns an object that represents that scope. The scope is exited when the returned object is - * closed. + * Enters the scope of code where the given {@code TagContext} is in the current context + * (replacing the previous {@code TagContext}) and returns an object that represents that scope. + * The scope is exited when the returned object is closed. * * @param tags the {@code TagContext} to be set to the current context. * @return an object that defines a scope where the given {@code TagContext} is set to the current -- cgit v1.2.3 From eabc800c3749ca6f8e3a17f057ae11c8d1385d0c Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 28 Aug 2018 14:40:27 -0700 Subject: Avoid doing string formatting when calling checkArgument. (#1394) --- api/src/main/java/io/opencensus/tags/TagKey.java | 2 +- api/src/main/java/io/opencensus/tags/TagValue.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'api/src/main/java/io/opencensus/tags') diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java index 615c2d46..ca4582bd 100644 --- a/api/src/main/java/io/opencensus/tags/TagKey.java +++ b/api/src/main/java/io/opencensus/tags/TagKey.java @@ -60,7 +60,7 @@ public abstract class TagKey { * @since 0.8 */ public static TagKey create(String name) { - Utils.checkArgument(isValid(name), "Invalid TagKey name: " + name); + Utils.checkArgument(isValid(name), "Invalid TagKey name: %s", name); return new AutoValue_TagKey(name); } diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java index 5c1019ff..9111ca28 100644 --- a/api/src/main/java/io/opencensus/tags/TagValue.java +++ b/api/src/main/java/io/opencensus/tags/TagValue.java @@ -55,7 +55,7 @@ public abstract class TagValue { * @since 0.8 */ public static TagValue create(String value) { - Utils.checkArgument(isValid(value), "Invalid TagValue: " + value); + Utils.checkArgument(isValid(value), "Invalid TagValue: %s", value); return new AutoValue_TagValue(value); } -- cgit v1.2.3