Merge pull request #3877 from evolvedbinary/bugfix/bound-lazy-cache-creation

Lazily created caches should be bounded

Author: duncdrum

exist-distribution/src/main/config/conf.xml

@@ -989,7 +989,31 @@
             <!--
                 Extension Modules
             -->
-            <module uri="http://exist-db.org/xquery/cache" class="org.exist.xquery.modules.cache.CacheModule"/>
+            <module uri="http://exist-db.org/xquery/cache" class="org.exist.xquery.modules.cache.CacheModule">
+                <!--
+                If a named Cache does not exist it can be created lazily on-demand
+                when an operation is first performed upon it.
+
+                    - enableLazyCreation
+                        true to enable lazy creation, false to disable.
+                        When false, if the Cache is not explicitly created before
+                        it is used then an error is raised.
+
+                    - lazy.*
+                        These settings are as documented for the Cache Module
+                        and control the config that is used when lazily creating
+                        a Cache.
+                        Valid settings are:
+                            - lazy.maximumSize
+                            - lazy.expireAfterAccess
+                            - lazy.putGroup
+                            - lazy.getGroup
+                            - lazy.removeGroup
+                            - lazy.clearGroup
+                -->
+                <parameter name="enableLazyCreation" value="true"/>
+                <parameter name="lazy.maximumSize" value="128"/>
+            </module>
             <module uri="http://exist-db.org/xquery/compression" class="org.exist.xquery.modules.compression.CompressionModule"/>
             <module uri="http://exist-db.org/xquery/counter" class="org.exist.xquery.modules.counter.CounterModule"/>
             <module uri="http://exist-db.org/xquery/cqlparser" class="org.exist.xquery.modules.cqlparser.CQLParserModule"/>

extensions/modules/cache/pom.xml

@@ -57,6 +57,11 @@
             <artifactId>caffeine</artifactId>
         </dependency>
 
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-api</artifactId>
+        </dependency>
+
         <dependency>
             <groupId>xml-apis</groupId>
             <artifactId>xml-apis</artifactId>

extensions/modules/cache/src/main/java/org/exist/xquery/modules/cache/CacheConfig.java

@@ -34,10 +34,6 @@ public class CacheConfig {
     private final Optional<Long> maximumSize;
     private final Optional<Long> expireAfterAccess;
 
-    public CacheConfig() {
-        this(Optional.empty(), Optional.empty(), Optional.empty());
-    }
-
     /**
      * @param permissions Any restrictions on cache operations
      * @param maximumSize The maximimum number of entries in the cache

extensions/modules/cache/src/main/java/org/exist/xquery/modules/cache/CacheFunctions.java

@@ -62,7 +62,7 @@ public class CacheFunctions extends BasicFunction {
             "Explicitly create a cache with a specific configuration",
             returns(Type.BOOLEAN, "true if the cache was created, false if the cache already exists"),
             FS_PARAM_CACHE_NAME,
-            param("config", Type.MAP, "A map with configuration for the cache. At present cache LRU and permission groups may be specified, for operations on the cache. `maximumSize` is optional and specifies the maximum number of entries. `expireAfterAccess` is optional and specified the expiry period for infrequently accessed entries (in milliseconds). If a permission group is not specified for an operation, then permissions are not checked for that operation. Should have the format: map { \"maximumSize\": 1000, \"expireAfterAccess\": 120000, \"permissions\": map { \"put-group\": \"group1\", \"get-group\": \"group2\", \"remove-group\": \"group3\", \"clear-group\": \"group4\"} }")
+            param("config", Type.MAP, "A map with configuration for the cache. At present cache LRU and permission groups may be specified, for operations on the cache. `maximumSize` is optional and specifies the maximum number of entries. `expireAfterAccess` is optional and specifies the expiry period for infrequently accessed entries (in milliseconds). If a permission group is not specified for an operation, then permissions are not checked for that operation. Should have the format: map { \"maximumSize\": 1000, \"expireAfterAccess\": 120000, \"permissions\": map { \"put-group\": \"group1\", \"get-group\": \"group2\", \"remove-group\": \"group3\", \"clear-group\": \"group4\"} }")
     );
 
     private static final String FS_NAMES_NAME = "names";
@@ -159,7 +159,7 @@ public Sequence eval(final Sequence[] args, final Sequence contextSequence) thro
             cacheName = null;
         }
 
-        switch(getName().getLocalPart()) {
+        switch (getName().getLocalPart()) {
 
             case FS_CREATE_NAME:
                 if(CacheModule.caches.containsKey(cacheName)) {
@@ -173,7 +173,7 @@ public Sequence eval(final Sequence[] args, final Sequence contextSequence) thro
             case FS_PUT_NAME:
                 // lazy create cache if it doesn't exist
                 if(!CacheModule.caches.containsKey(cacheName)) {
-                    createCache(cacheName, new CacheConfig());
+                    lazilyCreateCache(cacheName);
                 }
                 final String putKey = toMapKey(args[1]);
                 final Sequence value = args[2];
@@ -182,30 +182,30 @@ public Sequence eval(final Sequence[] args, final Sequence contextSequence) thro
             case FS_LIST_NAME:
                 // lazy create cache if it doesn't exist
                 if(!CacheModule.caches.containsKey(cacheName)) {
-                    createCache(cacheName, new CacheConfig());
+                    lazilyCreateCache(cacheName);
                 }
                 final String[] keys = toMapKeys(args[1]);
                 return list(cacheName, keys);
 
             case FS_KEYS_NAME:
                 // lazy create cache if it doesn't exist
                 if(!CacheModule.caches.containsKey(cacheName)) {
-                    createCache(cacheName, new CacheConfig());
+                    lazilyCreateCache(cacheName);
                 }
                 return listKeys(cacheName);
 
             case FS_GET_NAME:
                 // lazy create cache if it doesn't exist
                 if(!CacheModule.caches.containsKey(cacheName)) {
-                    createCache(cacheName, new CacheConfig());
+                    lazilyCreateCache(cacheName);
                 }
                 final String getKey = toMapKey(args[1]);
                 return get(cacheName, getKey);
 
             case FS_REMOVE_NAME:
                 // lazy create cache if it doesn't exist
                 if(!CacheModule.caches.containsKey(cacheName)) {
-                    createCache(cacheName, new CacheConfig());
+                    lazilyCreateCache(cacheName);
                 }
                 final String removeKey = toMapKey(args[1]);
                 return remove(cacheName, removeKey);
@@ -292,6 +292,17 @@ private boolean createCache(final String cacheName, final CacheConfig config) {
         return newOrExisting.getConfig() == config;
     }
 
+    private void lazilyCreateCache(final String cacheName) throws XPathException {
+        final CacheModule cacheModule = (CacheModule) getParentModule();
+        final Optional<CacheConfig> maybeLazyCacheConfig = cacheModule.getLazyCacheConfig();
+
+        if (!maybeLazyCacheConfig.isPresent()) {
+            throw new XPathException(this, LAZY_CREATION_DISABLED, "There is no such named cache: " + cacheName + ", and lazy creation of the cache has been disabled.");
+        }
+
+        createCache(cacheName, maybeLazyCacheConfig.get());
+    }
+
     private Sequence cacheNames() throws XPathException {
         final Sequence result = new ValueSequence();
         for(final String cacheName : CacheModule.caches.keySet()) {

extensions/modules/cache/src/main/java/org/exist/xquery/modules/cache/CacheModule.java

@@ -23,12 +23,16 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 import org.exist.dom.QName;
 import org.exist.xquery.*;
 import org.exist.xquery.value.FunctionParameterSequenceType;
 import org.exist.xquery.value.FunctionReturnSequenceType;
+
 import static org.exist.xquery.FunctionDSL.functionDefs;
 
 /**
@@ -42,11 +46,13 @@
  */
 public class CacheModule extends AbstractInternalModule {
 
-    public final static String NAMESPACE_URI = "http://exist-db.org/xquery/cache";
+    private static final Logger LOG = LogManager.getLogger(CacheModule.class);
+
+    public static final String NAMESPACE_URI = "http://exist-db.org/xquery/cache";
 
-    public final static String PREFIX = "cache";
-    public final static String INCLUSION_DATE = "2009-03-04";
-    public final static String RELEASED_IN_VERSION = "eXist-1.4";
+    public static final String PREFIX = "cache";
+    public static final String INCLUSION_DATE = "2009-03-04";
+    public static final String RELEASED_IN_VERSION = "eXist-1.4";
 
     public static final FunctionDef[] functions = functionDefs(
             CacheFunctions.class,
@@ -62,11 +68,26 @@ public class CacheModule extends AbstractInternalModule {
             CacheFunctions.FS_CLEANUP,
             CacheFunctions.FS_DESTROY);
 
+    private static final String PARAM_NAME_ENABLE_LAZY_CREATION = "enableLazyCreation";
+    private static final String PARAM_NAME_LAZY_MAXIMUM_SIZE = "lazy.maximumSize";
+    private static final String PARAM_NAME_LAZY_EXPIRE_AFTER_ACCESS = "lazy.expireAfterAccess";
+    private static final String PARAM_NAME_LAZY_PUT_GROUP = "lazy.putGroup";
+    private static final String PARAM_NAME_LAZY_GET_GROUP = "lazy.getGroup";
+    private static final String PARAM_NAME_LAZY_REMOVE_GROUP = "lazy.removeGroup";
+    private static final String PARAM_NAME_LAZY_CLEAR_GROUP = "lazy.clearGroup";
+
+    private static final long DEFAULT_LAZY_MAXIMUM_SIZE = 128;  // 128 items
+    private static final long DEFAULT_LAZY_EXPIRE_AFTER_ACCESS = 1000 * 60 * 5;  // 5 minutes
 
     static final Map<String, Cache> caches = new ConcurrentHashMap<>();
 
+    private final Optional<CacheConfig> lazyCacheConfig;
+
     public CacheModule(final Map<String, List<?>> parameters) {
         super(functions, parameters);
+
+        // read parameters
+        this.lazyCacheConfig = parseParameters(parameters);
     }
 
     @Override
@@ -105,4 +126,60 @@ private CacheModuleErrorCode(final String code, final String description) {
 
     static final ErrorCodes.ErrorCode INSUFFICIENT_PERMISSIONS = new CacheModuleErrorCode("insufficient-permissions", "The calling user does not have sufficient permissions to operate on the cache.");
     static final ErrorCodes.ErrorCode KEY_SERIALIZATION = new CacheModuleErrorCode("key-serialization", "Unable to serialize the provided key.");
+    static final ErrorCodes.ErrorCode LAZY_CREATION_DISABLED = new CacheModuleErrorCode("lazy-creation-disabled", "There is no such named cache, and lazy creation of the cache has been disabled.");
+
+    private static Optional<CacheConfig> parseParameters(final Map<String, List<?>> parameters) {
+        if (parameters == null || parameters.isEmpty()) {
+            return Optional.empty();
+        }
+
+        final boolean enableLazyCreation = getFirstString(parameters, PARAM_NAME_ENABLE_LAZY_CREATION)
+                .map(Boolean::parseBoolean)
+                .orElse(false);
+
+        if (!enableLazyCreation) {
+            return Optional.empty();
+        }
+
+        final Optional<String> putGroup = getFirstString(parameters, PARAM_NAME_LAZY_PUT_GROUP);
+        final Optional<String> getGroup = getFirstString(parameters, PARAM_NAME_LAZY_GET_GROUP);
+        final Optional<String> removeGroup = getFirstString(parameters, PARAM_NAME_LAZY_REMOVE_GROUP);
+        final Optional<String> clearGroup = getFirstString(parameters, PARAM_NAME_LAZY_CLEAR_GROUP);
+        final Optional<CacheConfig.Permissions> permissions = Optional.of(new CacheConfig.Permissions(putGroup, getGroup, removeGroup, clearGroup));
+
+        final Optional<Long> maximumSize = getFirstString(parameters, PARAM_NAME_LAZY_MAXIMUM_SIZE)
+                .map(s -> {
+                    try {
+                        return Long.parseLong(s);
+                    } catch (final NumberFormatException e) {
+                        LOG.warn("Unable to set {} to: {}. Using default: ", PARAM_NAME_LAZY_MAXIMUM_SIZE, s, DEFAULT_LAZY_MAXIMUM_SIZE);
+                        return DEFAULT_LAZY_MAXIMUM_SIZE;
+                    }
+                });
+
+        final Optional<Long> expireAfterAccess = getFirstString(parameters, PARAM_NAME_LAZY_EXPIRE_AFTER_ACCESS)
+                .map(s -> {
+                    try {
+                        return Long.parseLong(s);
+                    } catch (final NumberFormatException e) {
+                        LOG.warn("Unable to set {} to: {}. Using default: ", PARAM_NAME_LAZY_EXPIRE_AFTER_ACCESS, s, DEFAULT_LAZY_EXPIRE_AFTER_ACCESS);
+                        return DEFAULT_LAZY_EXPIRE_AFTER_ACCESS;
+                    }
+                });
+
+
+        return Optional.of(new CacheConfig(permissions, maximumSize, expireAfterAccess));
+    }
+
+    private static Optional<String> getFirstString(final Map<String, List<?>> parameters, final String paramName) {
+        return Optional.ofNullable(parameters.get(paramName))
+                .filter(l -> l.size() == 1)
+                .map(l -> l.get(0))
+                .filter(o -> o instanceof String)
+                .map(o -> (String)o);
+    }
+
+    Optional<CacheConfig> getLazyCacheConfig() {
+        return lazyCacheConfig;
+    }
 }

extensions/modules/cache/src/test/resources-filtered/conf.xml

@@ -744,7 +744,10 @@
         <builtin-modules>
 
             <!-- Module under test -->
-            <module uri="http://exist-db.org/xquery/cache" class="org.exist.xquery.modules.cache.CacheModule"/>
+            <module uri="http://exist-db.org/xquery/cache" class="org.exist.xquery.modules.cache.CacheModule">
+                <parameter name="enableLazyCreation" value="true"/>
+                <parameter name="lazy.maximumSize" value="128"/>
+            </module>
 
 
             <!-- Needed for XQSuite! -->