JCL-279: Cache abstraction with Guava and Caffeine implementations (#410)

* JCL-279: Cache abstraction with Guava and Caffeine implementations

* OpenId integration

* UMA integration

* Examples integration

* Archetype integration

* Access Grant integration

* Adjust cache creation definition

---------

Co-authored-by: Timea <4144203+timea-solid@users.noreply.github.com>

Author: acoburn

access-grant/pom.xml

@@ -55,6 +55,12 @@
       <version>${project.version}</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>com.inrupt.client</groupId>
+      <artifactId>inrupt-client-caffeine</artifactId>
+      <version>${project.version}</version>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>com.inrupt.client</groupId>
       <artifactId>inrupt-client-core</artifactId>

access-grant/src/main/java/com/inrupt/client/accessgrant/AccessGrantClient.java

@@ -23,6 +23,7 @@
 import static java.nio.charset.StandardCharsets.UTF_8;
 
 import com.inrupt.client.Client;
+import com.inrupt.client.ClientCache;
 import com.inrupt.client.ClientProvider;
 import com.inrupt.client.Request;
 import com.inrupt.client.Response;
@@ -36,6 +37,7 @@
 import java.io.InputStream;
 import java.io.UncheckedIOException;
 import java.net.URI;
+import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -92,6 +94,7 @@ public class AccessGrantClient {
     private static final Set<String> ACCESS_GRANT_TYPES = getAccessGrantTypes();
 
     private final Client client;
+    private final ClientCache<URI, Metadata> metadataCache;
     private final JsonService jsonService;
     private final AccessGrantConfiguration config;
 
@@ -107,23 +110,38 @@ public AccessGrantClient(final URI issuer) {
     /**
      * Create an access grant client.
      *
-     * @param issuer the issuer
      * @param client the client
+     * @param issuer the issuer
      */
     public AccessGrantClient(final Client client, final URI issuer) {
-        this(client, new AccessGrantConfiguration(issuer));
+        this(client, ServiceProvider.getCacheBuilder().build(100, Duration.ofMinutes(60)),
+                new AccessGrantConfiguration(issuer));
+    }
+
+    /**
+     * Create an access grant client.
+     *
+     * @param client the client
+     * @param issuer the issuer
+     * @param metadataCache the metadata cache
+     */
+    public AccessGrantClient(final Client client, final URI issuer, final ClientCache<URI, Metadata> metadataCache) {
+        this(client, metadataCache, new AccessGrantConfiguration(issuer));
     }
 
     /**
      * Create an access grant client.
      *
      * @param client the client
+     * @param metadataCache the metadata cache
      * @param config the access grant configuration
      */
     // This ctor may be made public at a later point
-    private AccessGrantClient(final Client client, final AccessGrantConfiguration config) {
-        this.client = Objects.requireNonNull(client);
-        this.config = Objects.requireNonNull(config);
+    private AccessGrantClient(final Client client, final ClientCache<URI, Metadata> metadataCache,
+            final AccessGrantConfiguration config) {
+        this.client = Objects.requireNonNull(client, "client may not be null!");
+        this.config = Objects.requireNonNull(config, "config may not be null!");
+        this.metadataCache = Objects.requireNonNull(metadataCache, "metadataCache may not be null!");
         this.jsonService = ServiceProvider.getJsonService();
     }
 
@@ -135,7 +153,7 @@ private AccessGrantClient(final Client client, final AccessGrantConfiguration co
      */
     public AccessGrantClient session(final Session session) {
         Objects.requireNonNull(session, "Session may not be null!");
-        return new AccessGrantClient(client.session(session), config);
+        return new AccessGrantClient(client.session(session), metadataCache, config);
     }
 
     /**
@@ -346,6 +364,11 @@ List<AccessGrant> processQueryResponse(final InputStream input, final Set<String
 
     CompletionStage<Metadata> v1Metadata() {
         final URI uri = URIBuilder.newBuilder(config.getIssuer()).path(".well-known/vc-configuration").build();
+        final Metadata cached = metadataCache.get(uri);
+        if (cached != null) {
+            return CompletableFuture.completedFuture(cached);
+        }
+
         final Request req = Request.newBuilder(uri).header("Accept", APPLICATION_JSON).build();
         return client.send(req, Response.BodyHandlers.ofInputStream())
             .thenApply(res -> {
@@ -369,6 +392,7 @@ CompletionStage<Metadata> v1Metadata() {
                 m.issueEndpoint = asUri(metadata.get("issuerService"));
                 m.verifyEndpoint = asUri(metadata.get("verifierService"));
                 m.statusEndpoint = asUri(metadata.get("statusService"));
+                metadataCache.put(uri, m);
                 return m;
             });
     }

access-grant/src/test/java/com/inrupt/client/accessgrant/AccessGrantClientTest.java

@@ -65,11 +65,13 @@ class AccessGrantClientTest {
     private static final URI ACCESS_REQUEST = URI.create("http://www.w3.org/ns/solid/vc#SolidAccessRequest");
 
     private static final MockAccessGrantServer mockServer = new MockAccessGrantServer();
+    private static AccessGrantClient agClient;
     private static URI baseUri;
 
     @BeforeAll
     static void setup() {
         baseUri = URI.create(mockServer.start());
+        agClient = new AccessGrantClient(baseUri);
     }
 
     @AfterAll
@@ -93,8 +95,7 @@ void testFetch1() {
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
         final URI uri = URIBuilder.newBuilder(baseUri).path("access-grant-1").build();
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
         final AccessGrant grant = client.fetch(uri).toCompletableFuture().join();
 
         assertEquals(uri, grant.getIdentifier());
@@ -116,8 +117,7 @@ void testFetch2() {
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
         final URI uri = URIBuilder.newBuilder(baseUri).path("access-grant-2").build();
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
         final AccessGrant grant = client.fetch(uri).toCompletableFuture().join();
 
         assertEquals(uri, grant.getIdentifier());
@@ -143,8 +143,7 @@ void testFetch6() {
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
         final URI uri = URIBuilder.newBuilder(baseUri).path("access-grant-6").build();
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
         final AccessGrant grant = client.fetch(uri).toCompletableFuture().join();
 
         assertEquals(uri, grant.getIdentifier());
@@ -168,35 +167,32 @@ void testNotAccessGrant() {
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
         final URI uri = URIBuilder.newBuilder(baseUri).path("vc-3").build();
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
         final CompletionException err = assertThrows(CompletionException.class,
                 client.fetch(uri).toCompletableFuture()::join);
     }
 
     @Test
     void testFetchInvalid() {
         final URI uri = URIBuilder.newBuilder(baseUri).path(".well-known/vc-configuration").build();
-        final AccessGrantClient client = new AccessGrantClient(baseUri);
         final CompletionException err = assertThrows(CompletionException.class,
-                client.fetch(uri).toCompletableFuture()::join);
+                agClient.fetch(uri).toCompletableFuture()::join);
 
         assertTrue(err.getCause() instanceof AccessGrantException);
     }
 
     @Test
     void testFetchNotFound() {
         final URI uri = URIBuilder.newBuilder(baseUri).path("not-found").build();
-        final AccessGrantClient client = new AccessGrantClient(uri);
         final CompletionException err1 = assertThrows(CompletionException.class,
-                client.fetch(uri).toCompletableFuture()::join);
+                agClient.fetch(uri).toCompletableFuture()::join);
 
         assertTrue(err1.getCause() instanceof AccessGrantException);
 
         final URI agent = URI.create("https://id.test/agent");
 
         final CompletionException err2 = assertThrows(CompletionException.class,
-                client.issue(ACCESS_GRANT, agent, Collections.emptySet(), Collections.emptySet(),
+                agClient.issue(ACCESS_GRANT, agent, Collections.emptySet(), Collections.emptySet(),
                     Collections.emptySet(), Instant.now()).toCompletableFuture()::join);
         assertTrue(err2.getCause() instanceof AccessGrantException);
     }
@@ -209,8 +205,7 @@ void testIssueGrant() {
         claims.put("iss", ISS);
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
 
         final URI agent = URI.create("https://id.test/agent");
         final Instant expiration = Instant.parse("2022-08-27T12:00:00Z");
@@ -238,8 +233,7 @@ void testIssueRequest() {
         claims.put("iss", ISS);
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
 
         final URI agent = URI.create("https://id.test/agent");
         final Instant expiration = Instant.parse("2022-08-27T12:00:00Z");
@@ -261,16 +255,14 @@ void testIssueRequest() {
 
     @Test
     void testIssueNoAuth() {
-        final AccessGrantClient client = new AccessGrantClient(baseUri);
-
         final URI agent = URI.create("https://id.test/agent");
         final Instant expiration = Instant.parse("2022-08-27T12:00:00Z");
         final Set<String> modes = new HashSet<>(Arrays.asList("Read", "Append"));
         final Set<String> purposes = Collections.singleton("https://purpose.test/Purpose1");
 
         final Set<URI> resources = Collections.singleton(URI.create("https://storage.test/data/"));
         final CompletionException err = assertThrows(CompletionException.class, () ->
-                client.issue(ACCESS_GRANT, agent, resources, modes, purposes, expiration)
+                agClient.issue(ACCESS_GRANT, agent, resources, modes, purposes, expiration)
                     .toCompletableFuture().join());
         assertTrue(err.getCause() instanceof AccessGrantException);
     }
@@ -283,8 +275,7 @@ void testIssueOther() {
         claims.put("iss", ISS);
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
 
         final URI agent = URI.create("https://id.test/agent");
         final Instant expiration = Instant.parse("2022-08-27T12:00:00Z");
@@ -306,8 +297,7 @@ void testQueryGrant() {
         claims.put("iss", ISS);
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
 
         final List<AccessGrant> grants = client.query(URI.create("SolidAccessGrant"), null,
                 URI.create("https://storage.example/e973cc3d-5c28-4a10-98c5-e40079289358/a/b/c"), "Read")
@@ -323,8 +313,7 @@ void testQueryRequest() {
         claims.put("iss", ISS);
         claims.put("azp", AZP);
         final String token = generateIdToken(claims);
-        final AccessGrantClient client = new AccessGrantClient(baseUri)
-            .session(OpenIdSession.ofIdToken(token));
+        final AccessGrantClient client = agClient.session(OpenIdSession.ofIdToken(token));
 
         final List<AccessGrant> grants = client.query(URI.create("SolidAccessRequest"), null,
                 URI.create("https://storage.example/f1759e6d-4dda-4401-be61-d90d070a5474/a/b/c"), "Read")
@@ -334,10 +323,8 @@ void testQueryRequest() {
 
     @Test
     void testQueryInvalidAuth() {
-        final AccessGrantClient client = new AccessGrantClient(baseUri);
-
         final CompletionException err = assertThrows(CompletionException.class,
-                client.query(URI.create("SolidAccessGrant"), null, null, null).toCompletableFuture()::join);
+                agClient.query(URI.create("SolidAccessGrant"), null, null, null).toCompletableFuture()::join);
 
         assertTrue(err.getCause() instanceof AccessGrantException);
     }

api/src/main/java/com/inrupt/client/ClientCache.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2023 Inrupt Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+ * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+ * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.inrupt.client;
+
+/**
+ * A generic caching abstraction for use in the Inrupt Client Libraries.
+ *
+ * @param <T> the key type
+ * @param <U> the value type
+ */
+public interface ClientCache<T, U> {
+
+    /**
+     * Retrieve a cached value.
+     *
+     * @param key the key
+     * @return the cached value, may be {@code null} if not present
+     */
+    U get(T key);
+
+    /**
+     * Set a cached value.
+     *
+     * @param key the key, not {@code null}
+     * @param value the value, not {@code null}
+     */
+    void put(T key, U value);
+
+    /**
+     * Invalidate a single cached value.
+     *
+     * @param key the key, not {@code null}
+     */
+    void invalidate(T key);
+
+    /**
+     * Invalidate all values in the cache.
+     */
+    void invalidateAll();
+}

api/src/main/java/com/inrupt/client/spi/CacheBuilderService.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2023 Inrupt Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+ * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+ * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.inrupt.client.spi;
+
+import com.inrupt.client.ClientCache;
+
+import java.time.Duration;
+
+/**
+ * A cache builder abstraction for use with different cache implementations.
+ */
+public interface CacheBuilderService {
+
+    /**
+     * Build a cache.
+     *
+     * @param maximumSize the maximum cache size
+     * @param expiration the duration after which items should expire from the cache
+     * @param <T> the key type
+     * @param <U> the value type
+     * @return the cache
+     */
+    <T, U> ClientCache<T, U> build(int maximumSize, Duration expiration);
+
+}