feat: Add Lineage Enablement Cache

lib/build.gradle

@@ -23,7 +23,7 @@ plugins {
 
 // v"2.2.5" is recommended, but it uses Java21 which is incompatible with other
 // plugins (e.g. "com.github.johnrengelman.shadow"), therefore, using latest compatible version
-   id("com.google.cloud.artifactregistry.gradle-plugin") version "2.1.5"
+    id("com.google.cloud.artifactregistry.gradle-plugin") version "2.1.5"
 }
 
 googleJavaFormat {
@@ -62,25 +62,29 @@ dependencies {
     implementation "com.google.api:gax-httpjson:${gaxHttpJsonVersion}"
     implementation "io.grpc:grpc-protobuf:${grpcProtobufVersion}"
     implementation "com.google.guava:guava:${guavaVersion}"
-    
+
     // SLF4J logging
     implementation "org.slf4j:slf4j-api:${slf4jVersion}"
-    
+
     // Lombok for @Slf4j annotation
     compileOnly "org.projectlombok:lombok:${lombokVersion}"
     annotationProcessor "org.projectlombok:lombok:${lombokVersion}"
-
+
+    // AutoValue
+    compileOnly "com.google.auto.value:auto-value-annotations:1.10.1"
+    annotationProcessor "com.google.auto.value:auto-value:1.10.1"
+
     // Use JUnit test framework.
     testImplementation "junit:junit:${junitVersion}"
     testImplementation "com.google.truth:truth:${truthVersion}"
     testImplementation "org.mockito:mockito-core:${mockitoVersion}"
     testImplementation "com.google.api:gax:${gaxTestLibVersion}:testlib"
     testImplementation "com.google.testparameterinjector:test-parameter-injector:${parameterInjectorVersion}"
-    
+
     // Test logging dependencies
     testImplementation "ch.qos.logback:logback-classic:${logbackVersion}"
     testImplementation "ch.qos.logback:logback-core:${logbackVersion}"
-    
+
     // Test Lombok
     testCompileOnly "org.projectlombok:lombok:${lombokVersion}"
     testAnnotationProcessor "org.projectlombok:lombok:${lombokVersion}"

lib/src/main/java/com/google/cloud/datalineage/producerclient/ApiEnablementCacheFactory.java

@@ -21,7 +21,7 @@ public class ApiEnablementCacheFactory {
   /** Make the factory class non-instantiable */
   private ApiEnablementCacheFactory() {}
 
-  public static ApiEnablementCache get(ApiEnablementCacheSettings settings) {
+  public static ApiEnablementCache get(CacheSettings settings) {
     if (!settings.getEnabled()) {
       return new NoOpApiEnablementCache();
     }

lib/src/main/java/com/google/cloud/datalineage/producerclient/ApiEnablementCacheOptions.java → lib/src/main/java/com/google/cloud/datalineage/producerclient/CacheOptions.java

@@ -18,10 +18,11 @@
 import java.time.Duration;
 
 /**
- * Provides an immutable object for ConnectionCache initialization. ApiEnablementCacheOptions object
- * can be created via Builder.
+ * Provides an immutable object for Cache initialization. CacheOptions object can be created via
+ * Builder.
  */
-public class ApiEnablementCacheOptions {
+public class CacheOptions {
+
   protected static final Duration DEFAULT_DISABLED_TIME = Duration.ofMinutes(5);
   protected static final int DEFAULT_SIZE = 1000;
   protected static final Clock DEFAULT_CLOCK = Clock.systemDefaultZone();
@@ -30,18 +31,18 @@ public class ApiEnablementCacheOptions {
   private final int cacheSize;
   private final Clock clock;
 
-  protected ApiEnablementCacheOptions(ApiEnablementCacheOptions.Builder settingsBuilder) {
+  protected CacheOptions(CacheOptions.Builder settingsBuilder) {
     defaultCacheDisabledStatusTime = settingsBuilder.defaultCacheDisabledStatusTime;
     cacheSize = settingsBuilder.cacheSize;
     clock = settingsBuilder.clock;
   }
 
-  public static ApiEnablementCacheOptions.Builder newBuilder() {
-    return ApiEnablementCacheOptions.Builder.createDefault();
+  public static CacheOptions.Builder newBuilder() {
+    return CacheOptions.Builder.createDefault();
   }
 
-  public static ApiEnablementCacheOptions getDefaultInstance() {
-    return ApiEnablementCacheOptions.Builder.createDefault().build();
+  public static CacheOptions getDefaultInstance() {
+    return CacheOptions.Builder.createDefault().build();
   }
 
   public Duration getDefaultCacheDisabledStatusTime() {
@@ -56,22 +57,37 @@ public Clock getClock() {
     return clock;
   }
 
-  public ApiEnablementCacheOptions.Builder toBuilder() {
-    return new ApiEnablementCacheOptions.Builder(this);
+  public CacheOptions.Builder toBuilder() {
+    return new CacheOptions.Builder(this);
+  }
+
+  @Override
+  public boolean equals(Object obj) {
+    if (this == obj) {
+      return true;
+    }
+    if (!(obj instanceof CacheOptions)) {
+      return false;
+    }
+    CacheOptions that = (CacheOptions) obj;
+    return this.cacheSize == that.cacheSize
+        && this.defaultCacheDisabledStatusTime.equals(that.defaultCacheDisabledStatusTime)
+        && this.clock.equals(that.clock);
   }
 
   /**
-   * * Builder for ApiEnablementCacheSettings.
+   * * Builder for CacheSettings.
    *
    * <p>Lets setting `markServiceAsDisabledTime`, `cacheSize`, and `clock`. Can be created by
-   * ApiEnablementCacheOptions.newBuilder method. To create settings object, use build method.
+   * CacheOptions.newBuilder method. To create settings object, use build method.
    */
   public static class Builder {
+
     protected Duration defaultCacheDisabledStatusTime;
     protected int cacheSize;
     protected Clock clock;
 
-    protected Builder(ApiEnablementCacheOptions settings) {
+    protected Builder(CacheOptions settings) {
       defaultCacheDisabledStatusTime = settings.defaultCacheDisabledStatusTime;
       cacheSize = settings.cacheSize;
       clock = settings.clock;
@@ -83,12 +99,11 @@ protected Builder(Duration defaultCacheDisabledStatusTime, int cacheSize, Clock
       this.clock = clock;
     }
 
-    private static ApiEnablementCacheOptions.Builder createDefault() {
-      return new ApiEnablementCacheOptions.Builder(
-          DEFAULT_DISABLED_TIME, DEFAULT_SIZE, DEFAULT_CLOCK);
+    private static CacheOptions.Builder createDefault() {
+      return new CacheOptions.Builder(DEFAULT_DISABLED_TIME, DEFAULT_SIZE, DEFAULT_CLOCK);
     }
 
-    public ApiEnablementCacheOptions.Builder setDefaultCacheDisabledStatusTime(
+    public CacheOptions.Builder setDefaultCacheDisabledStatusTime(
         Duration defaultCacheDisabledStatusTime) {
       if (defaultCacheDisabledStatusTime.isNegative()) {
         throw new IllegalArgumentException("Duration cannot be negative");
@@ -97,21 +112,21 @@ public ApiEnablementCacheOptions.Builder setDefaultCacheDisabledStatusTime(
       return this;
     }
 
-    public ApiEnablementCacheOptions.Builder setCacheSize(int cacheSize) {
+    public CacheOptions.Builder setCacheSize(int cacheSize) {
       if (cacheSize < 0) {
         throw new IllegalArgumentException("Limit cannot be negative");
       }
       this.cacheSize = cacheSize;
       return this;
     }
 
-    public ApiEnablementCacheOptions.Builder setClock(Clock clock) {
+    public CacheOptions.Builder setClock(Clock clock) {
       this.clock = clock;
       return this;
     }
 
-    public ApiEnablementCacheOptions build() {
-      return new ApiEnablementCacheOptions(this);
+    public CacheOptions build() {
+      return new CacheOptions(this);
     }
   }
 }

lib/src/main/java/com/google/cloud/datalineage/producerclient/ApiEnablementCacheSettings.java → lib/src/main/java/com/google/cloud/datalineage/producerclient/CacheSettings.java

@@ -14,27 +14,25 @@
 
 package com.google.cloud.datalineage.producerclient;
 
-/** Provides an immutable object for storing connection cache settings. */
-public final class ApiEnablementCacheSettings {
+/** Provides an immutable object for storing cache settings. */
+public final class CacheSettings {
 
   /**
-   * Disables connection cache feature.
+   * Disables cache feature.
    *
    * @return The requested cache settings.
    */
-  public static ApiEnablementCacheSettings getDisabledInstance() {
-    return new ApiEnablementCacheSettings(
-        false, false, ApiEnablementCacheOptions.getDefaultInstance());
+  public static CacheSettings getDisabledInstance() {
+    return new CacheSettings(false, false, CacheOptions.getDefaultInstance());
   }
 
   /**
    * Uses common instance. If there is no such instance, creates one with default cache options.
    *
    * @return The requested cache settings.
    */
-  public static ApiEnablementCacheSettings getCommonInstance() {
-    return new ApiEnablementCacheSettings(
-        true, true, ApiEnablementCacheOptions.getDefaultInstance());
+  public static CacheSettings getCommonInstance() {
+    return new CacheSettings(true, true, CacheOptions.getDefaultInstance());
   }
 
   /**
@@ -44,22 +42,20 @@ public static ApiEnablementCacheSettings getCommonInstance() {
    * @param fallbackOptions The fallback cache options.
    * @return The requested cache settings.
    */
-  public static ApiEnablementCacheSettings getCommonInstance(
-      ApiEnablementCacheOptions fallbackOptions) {
+  public static CacheSettings getCommonInstance(CacheOptions fallbackOptions) {
     if (fallbackOptions == null) {
       throw new IllegalArgumentException("defaultSettings cannot be null");
     }
-    return new ApiEnablementCacheSettings(true, true, fallbackOptions);
+    return new CacheSettings(true, true, fallbackOptions);
   }
 
   /**
    * Uses stand-alone instance with default cache options.
    *
    * @return The requested cache settings.
    */
-  public static ApiEnablementCacheSettings getStandAloneInstance() {
-    return new ApiEnablementCacheSettings(
-        true, false, ApiEnablementCacheOptions.getDefaultInstance());
+  public static CacheSettings getStandAloneInstance() {
+    return new CacheSettings(true, false, CacheOptions.getDefaultInstance());
   }
 
   /**
@@ -68,20 +64,18 @@ public static ApiEnablementCacheSettings getStandAloneInstance() {
    * @param options The cache options
    * @return The requested cache settings.
    */
-  public static ApiEnablementCacheSettings getStandAloneInstance(
-      ApiEnablementCacheOptions options) {
+  public static CacheSettings getStandAloneInstance(CacheOptions options) {
     if (options == null) {
       throw new IllegalArgumentException("settings cannot be null");
     }
-    return new ApiEnablementCacheSettings(true, false, options);
+    return new CacheSettings(true, false, options);
   }
 
   private final boolean enabled;
   private final boolean useCommonInstance;
-  private final ApiEnablementCacheOptions options;
+  private final CacheOptions options;
 
-  private ApiEnablementCacheSettings(
-      boolean enabled, boolean useCommonInstance, ApiEnablementCacheOptions options) {
+  private CacheSettings(boolean enabled, boolean useCommonInstance, CacheOptions options) {
     this.enabled = enabled;
     this.useCommonInstance = useCommonInstance;
     this.options = options;
@@ -95,7 +89,7 @@ public boolean getUseCommonInstance() {
     return useCommonInstance;
   }
 
-  public ApiEnablementCacheOptions getOptions() {
+  public CacheOptions getOptions() {
     return options;
   }
 }

lib/src/main/java/com/google/cloud/datalineage/producerclient/LineageEnablementCache.java

@@ -0,0 +1,50 @@
+// Copyright 2024 Google LLC
+//
+// 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
+//
+// https://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 com.google.cloud.datalineage.producerclient;
+
+import java.time.Duration;
+
+/**
+ * Cache used to store information about whether Lineage is disabled for a given project in
+ * LineageConfigurations.
+ */
+public interface LineageEnablementCache {
+
+  /**
+   * Mark lineage ingestion state as disabled for a given project name.
+   *
+   * @param projectName The project for which to disable the lineage ingestion
+   * @see LineageEnablementCache#markLineageAsDisabled(String, Duration)
+   */
+  void markLineageAsDisabled(String projectName);
+
+  /**
+   * Mark lineage ingestion state as disabled for a given project name and duration.
+   *
+   * @param projectName The project for which to disable the lineage ingestion
+   * @param duration - suggests how long the project should be marked as disabled. It is not
+   *     guarantied that cache will indicate lineage ingestion enablement state as disabled for
+   *     given time. Behaviour depends on implementation.
+   */
+  void markLineageAsDisabled(String projectName, Duration duration);
+
+  /**
+   * Indicates if lineage ingestion with provided projectName is marked as disabled.
+   *
+   * @param projectName The project for which to disable the lineage ingestion
+   * @return `true` if the lineage ingestion is marked as disabled
+   */
+  boolean isLineageMarkedAsDisabled(String projectName);
+}

lib/src/main/java/com/google/cloud/datalineage/producerclient/LineageEnablementCacheFactory.java

@@ -0,0 +1,45 @@
+// Copyright 2024 Google LLC
+//
+// 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
+//
+// https://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 com.google.cloud.datalineage.producerclient;
+
+/** A factory that returns ConnectionCache based on LineageEnablementCacheSettings. */
+public class LineageEnablementCacheFactory {
+  private static volatile LineageEnablementCache commonInstance;
+
+  /** Make the factory class non-instantiable */
+  private LineageEnablementCacheFactory() {}
+
+  public static LineageEnablementCache get(CacheSettings settings) {
+    if (!settings.getEnabled()) {
+      return new NoOpLineageEnablementCache();
+    }
+
+    if (!settings.getUseCommonInstance()) {
+      return new StandardLineageEnablementCache(settings.getOptions());
+    }
+
+    if (commonInstance != null) {
+      return commonInstance;
+    }
+
+    synchronized (LineageEnablementCacheFactory.class) {
+      if (commonInstance == null) {
+        commonInstance = new StandardLineageEnablementCache(settings.getOptions());
+      }
+    }
+
+    return commonInstance;
+  }
+}