MODE-1325 Added property to JPA source to control background garbage …

…collection

Some use cases of ModeShape involve uploading files and then rarely (if ever) modifying those values.
In such cases, the background garbage collection process might be far more detrimental to these applications.
Therefore, this commit adds a new property to the JPA repository source, allowing such background processing
and garbage collection to be disabled. Note that this only affects large values (all BINARY values or large
STRING values), since they can be reused by multiple properties/nodes.

All unit and integration tests pass.

docs/reference/src/main/docbook/en-US/content/connectors/jdbc_storage.xml

@@ -178,11 +178,21 @@
       </listitem>
     </varlistentry>
     <varlistentry>
-      <term>idleTimeInSecondsBeforeTestingConnections</term>
+      <term>driverClassName</term>
+      <listitem>
+        <para>
+					The name of the JDBC driver class. This is not required if the DataSource is found in JNDI, but is required otherwise.
+				</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>garbageCollectionEnabled</term>
       <listitem>
         <para>
-					Optional property that specifies the number of seconds after a connection remains in the pool that the connection should be 
-					tested to ensure it is still valid. The default is 180 seconds (or 3 minutes).
+					Advanced optional property that specifies whether unused BINARY and large STRING values should be removed from the database. 
+					The default value is "true", meaning that garbage collection is enabled and results in a periodic running of a
+					query; this setting is appropriate for most applications. However, some applications store files and rarely (if ever)
+					update or change that content, and in these cases this property may be set to "false".
 				</para>
       </listitem>
     </varlistentry>

extensions/modeshape-connector-store-jpa/src/main/java/org/modeshape/connector/store/jpa/JpaConnectorI18n.java

@@ -155,6 +155,9 @@ public final class JpaConnectorI18n {
     public static I18n cacheConcurrencyStrategyPropertyDescription;
     public static I18n cacheConcurrencyStrategyPropertyLabel;
     public static I18n cacheConcurrencyStrategyPropertyCategory;
+    public static I18n garbageCollectionEnabledPropertyDescription;
+    public static I18n garbageCollectionEnabledPropertyLabel;
+    public static I18n garbageCollectionEnabledPropertyCategory;
     static {
         try {
             I18n.initialize(JpaConnectorI18n.class);

extensions/modeshape-connector-store-jpa/src/main/java/org/modeshape/connector/store/jpa/JpaSource.java

@@ -764,6 +764,38 @@ public synchronized void setCreatingWorkspacesAllowed( boolean allowWorkspaceCre
         capabilities = capabilities.withCreatingWorkspaces(allowWorkspaceCreation);
     }
 
+    /**
+     * Get whether this source garbage collects unused large values (BINARY and large STRING values) automatically, in the
+     * background.
+     * 
+     * @return true if this source should garbage collect unused large values, or false if they should not be garbage collected
+     * @see #setPredefinedWorkspaceNames(String[])
+     * @see #getPredefinedWorkspaceNames()
+     * @see #setCreatingWorkspacesAllowed(boolean)
+     */
+    @Description( i18n = JpaConnectorI18n.class, value = "garbageCollectionEnabledPropertyDescription" )
+    @Label( i18n = JpaConnectorI18n.class, value = "garbageCollectionEnabledPropertyLabel" )
+    @Category( i18n = JpaConnectorI18n.class, value = "garbageCollectionEnabledPropertyCategory" )
+    public boolean isGarbageCollectionEnabled() {
+        return capabilities.supportsAutomaticGarbageCollection();
+    }
+
+    /**
+     * Set whether this source garbage collects unused large values (BINARY and large STRING values) automatically, in the
+     * background.
+     * 
+     * @param garbageCollectionEnabled true if this source should garbage collect unused large values
+     * @see #isGarbageCollectionEnabled()
+     */
+    public synchronized void setGarbageCollectionEnabled( boolean garbageCollectionEnabled ) {
+        // Note that the capabilities define whether this source automatically handles garbage collection.
+        // By default, this is false for this connector, meaning the engine periodically garbage collects
+        // the content. If we set this to 'true', then the engine assumes the source does it.
+        // Therefore, when the user turns off garbage collection, we need to set this to 'true' ...
+        boolean engineExpectsSourceToHandleGarbageCollection = !garbageCollectionEnabled;
+        capabilities = capabilities.withAutomaticGarbageCollection(engineExpectsSourceToHandleGarbageCollection);
+    }
+
     /**
      * @return dialect
      */

extensions/modeshape-connector-store-jpa/src/main/resources/org/modeshape/connector/store/jpa/JpaConnectorI18n.properties

@@ -168,4 +168,8 @@ cacheManagerLookupPropertyCategory = Advanced
 
 cacheConcurrencyStrategyPropertyDescription = Specifies the cache concurrency strategy to use.  When Hibernate is used as the JPA provider, valid values are "read-only", "transactional", "nonstrict-read-write", and "read-write".  Changes made to this value at runtime will be ignored.
 cacheConcurrencyStrategyPropertyLabel = Cache Concurrency Strategy
-cacheConcurrencyStrategyPropertyCategory = Advanced
+cacheConcurrencyStrategyPropertyCategory = Advanced
+
+garbageCollectionEnabledPropertyDescription = Specifies whether unused BINARY and large STRING values should be removed from the database. The default value is "true"; false should be used only in cases when there is not a large number of changes to nodes containing large values.
+garbageCollectionEnabledPropertyLabel = Garbage Collection
+garbageCollectionEnabledPropertyCategory = Advanced