Further simplify the API and SDK for entities

- Remove `Entity` and only expose `EntityBuilder` similar to how we do `LogRecord`s.
- Have methods on `Resource` which determine if you're attaching the entity, simplify "remove" or just ignore for now.

Author: jsuereth

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/Entity.java

@@ -10,8 +10,20 @@
 import java.util.function.Consumer;
 
 /**
- * A builder of {@link Entity} that allows to add identifying or descriptive {@link Attributes}, as
- * well as type and schema_url.
+ * A builder of an Entity that allows to add identifying or descriptive {@link Attributes}, as well
+ * as type and schema_url.
+ *
+ * <p>Entity represents an object of interest associated with produced telemetry: traces, metrics or
+ * logs.
+ *
+ * <p>For example, telemetry produced using OpenTelemetry SDK is normally associated with a Service
+ * entity. Similarly, OpenTelemetry defines system metrics for a host. The Host is the entity we
+ * want to associate metrics with in this case.
+ *
+ * <p>Entities may be also associated with produced telemetry indirectly. For example a service that
+ * produces telemetry is also related with a process in which the service runs, so we say that the
+ * Service entity is related to the Process entity. The process normally also runs on a host, so we
+ * say that the Process entity is related to the Host entity.
  */
 public interface EntityBuilder {
   /**
@@ -38,6 +50,6 @@ public interface EntityBuilder {
    */
   EntityBuilder withId(Consumer<AttributesBuilder> f);
 
-  /** Create the {@link Entity} from this. */
-  Entity build();
+  /** Emits the current entity. */
+  void emit();
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/EntityBuilder.java

@@ -25,7 +25,5 @@ public EntityBuilder withId(Consumer<AttributesBuilder> f) {
   }
 
   @Override
-  public Entity build() {
-    return new NoopEntity();
-  }
+  public void emit() {}
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/NoopEntity.java

@@ -8,17 +8,12 @@
 final class NoopResource implements Resource {
 
   @Override
-  public boolean addOrUpdate(Entity e) {
+  public boolean removeEntity(String entityType) {
     return false;
   }
 
   @Override
-  public boolean removeEntity(Entity e) {
-    return false;
-  }
-
-  @Override
-  public EntityBuilder createEntity(String entityType) {
+  public EntityBuilder attachEntity(String entityType) {
     return new NoopEntityBuilder();
   }
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/NoopEntityBuilder.java

@@ -7,29 +7,19 @@
 
 /** The active resource for which Telemetry is being generated. */
 public interface Resource {
-  /**
-   * Adds an {@link Entity} to this resource.
-   *
-   * <p>If the entity already exists, this updates the description.
-   *
-   * @param e The entity
-   * @return true if the entity was added or updated, false if there was a conflict.
-   */
-  public boolean addOrUpdate(Entity e);
-
   /**
    * Removes an {@link Entity} from this resource.
    *
-   * @param e The entity
+   * @param entityType the type of entity to remove.
    * @return true if entity was found and removed.
    */
-  public boolean removeEntity(Entity e);
+  public boolean removeEntity(String entityType);
 
   /**
-   * Returns a builder that can construct an {@link Entity}.
+   * Attaches an entity to the current {@link Resource}.
    *
    * @param entityType The type of the entity.
-   * @return A builder that can construct an entity.
+   * @return A builder that can construct an {@link Entity}.
    */
-  public EntityBuilder createEntity(String entityType);
+  public EntityBuilder attachEntity(String entityType);
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/NoopResource.java

@@ -6,15 +6,17 @@
 package io.opentelemetry.sdk.extension.incubator.entities;
 
 import io.opentelemetry.api.common.AttributesBuilder;
-import io.opentelemetry.api.incubator.entities.Entity;
 import io.opentelemetry.api.incubator.entities.EntityBuilder;
+import io.opentelemetry.sdk.resources.internal.Entity;
 import java.util.function.Consumer;
 
-final class PassthroughEntityBuilder implements EntityBuilder {
+final class SdkEntityBuilder implements EntityBuilder {
   private final io.opentelemetry.sdk.resources.internal.EntityBuilder builder;
+  private final Consumer<Entity> emitter;
 
-  PassthroughEntityBuilder(io.opentelemetry.sdk.resources.internal.EntityBuilder builder) {
-    this.builder = builder;
+  SdkEntityBuilder(String entityType, Consumer<Entity> emitter) {
+    this.builder = Entity.builder(entityType);
+    this.emitter = emitter;
   }
 
   @Override
@@ -36,7 +38,7 @@ public EntityBuilder withId(Consumer<AttributesBuilder> f) {
   }
 
   @Override
-  public Entity build() {
-    return new PassthroughEntity(builder.build());
+  public void emit() {
+    emitter.accept(builder.build());
   }
 }

api/incubator/src/main/java/io/opentelemetry/api/incubator/entities/Resource.java

@@ -5,19 +5,15 @@
 
 package io.opentelemetry.sdk.extension.incubator.entities;
 
-import io.opentelemetry.api.incubator.entities.Entity;
 import io.opentelemetry.api.incubator.entities.EntityBuilder;
 import io.opentelemetry.sdk.resources.Resource;
-import io.opentelemetry.sdk.resources.ResourceBuilder;
+import io.opentelemetry.sdk.resources.internal.Entity;
 import io.opentelemetry.sdk.resources.internal.EntityUtil;
-import java.util.ArrayList;
-import java.util.Collection;
 import java.util.concurrent.atomic.AtomicReference;
 
 final class SdkResource implements io.opentelemetry.api.incubator.entities.Resource {
 
   private final AtomicReference<Resource> resource = new AtomicReference<>(Resource.empty());
-
   private final Object writeLock = new Object();
 
   /** Returns the currently active resource. */
@@ -31,48 +27,21 @@ public Resource getResource() {
   }
 
   @Override
-  public boolean addOrUpdate(Entity e) {
-    synchronized (writeLock) {
-      Resource current = getResource();
-      Resource next =
-          EntityUtil.addEntity(Resource.builder(), ((PassthroughEntity) e).getPassthrough())
-              .build();
-      Resource result = current.merge(next);
-      // We rely on a volatile read to force this to be written.
-      resource.lazySet(result);
-      return EntityUtil.getEntities(result).stream()
-          .anyMatch(r -> r.getType().equals(e.getType()) && r.getId().equals(e.getId()));
-    }
+  public boolean removeEntity(String entityType) {
+    // TODO Auto-generated method stub
+    throw new UnsupportedOperationException("Unimplemented method 'removeEntity'");
   }
 
-  @Override
-  public boolean removeEntity(Entity e) {
+  void attachEntityOnEmit(Entity e) {
     synchronized (writeLock) {
       Resource current = getResource();
-      Collection<io.opentelemetry.sdk.resources.internal.Entity> previousEntities =
-          EntityUtil.getEntities(current);
-      Collection<io.opentelemetry.sdk.resources.internal.Entity> currentEntities =
-          new ArrayList<>(previousEntities);
-      boolean result = currentEntities.removeIf(c -> c.getType().equals(e.getType()));
-      ResourceBuilder rb = Resource.builder();
-      EntityUtil.addAllEntity(rb, currentEntities);
-      rb.putAll(
-          current.getAttributes().toBuilder()
-              .removeIf(
-                  key ->
-                      previousEntities.stream()
-                          .anyMatch(
-                              pe ->
-                                  pe.getId().asMap().containsKey(key)
-                                      || pe.getDescription().asMap().containsKey(key)))
-              .build());
-      resource.lazySet(rb.build());
-      return result;
+      Resource next = EntityUtil.addEntity(Resource.builder(), e).build();
+      resource.lazySet(current.merge(next));
     }
   }
 
   @Override
-  public EntityBuilder createEntity(String entityType) {
-    return PassthroughEntity.builder(entityType);
+  public EntityBuilder attachEntity(String entityType) {
+    return new SdkEntityBuilder(entityType, this::attachEntityOnEmit);
   }
 }