You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2026/09/15 12:11:28 UTC

(velocity-engine) 02/09: Deprecate velocimacro library old default name ; warn about deprecation warnings

This is an automated email from the ASF dual-hosted git repository.

asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/velocity-engine.git

commit f2a2d7af5a73610913086ee32528dce1465ce0ff
Author: Claude Brisson <cl...@renegat.net>
AuthorDate: Sun Sep 13 19:02:18 2026 +0200

    Deprecate velocimacro library old default name ; warn about deprecation warnings
---
 .../apache/velocity/runtime/RuntimeInstance.java   |  2 +
 .../velocity/runtime/VelocimacroFactory.java       |  5 ++
 .../velocity/test/DeprecationWarningTestCase.java  | 68 ++++++++++++++++++++++
 3 files changed, 75 insertions(+)

diff --git a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java
index 6f025f81..ae8efd59 100644
--- a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java
+++ b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/RuntimeInstance.java
@@ -414,6 +414,8 @@ private void warnDeprecatedSettings()
             return;
         }
 
+        log.warn("deprecation warnings are on; set {} to false to silence them", RUNTIME_DEPRECATION_WARN);
+
         if (hyphenAllowedInIdentifiers)
         {
             log.warn("the '{}' option is deprecated: hyphenated identifiers (e.g. $foo-bar) cannot be expressed in the next major version", PARSER_HYPHEN_ALLOWED);
diff --git a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/VelocimacroFactory.java b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/VelocimacroFactory.java
index b7961a5d..4f694594 100644
--- a/velocity-engine-core/src/main/java/org/apache/velocity/runtime/VelocimacroFactory.java
+++ b/velocity-engine-core/src/main/java/org/apache/velocity/runtime/VelocimacroFactory.java
@@ -163,6 +163,11 @@ public void initVelocimacro()
                      if (rsvc.getLoaderNameForResource(RuntimeConstants.OLD_VM_LIBRARY_DEFAULT) != null)
                      {
                          libfiles = RuntimeConstants.OLD_VM_LIBRARY_DEFAULT;
+                         if (rsvc.getBoolean(RuntimeConstants.RUNTIME_DEPRECATION_WARN, true))
+                         {
+                             log.warn("the macro library was found under its pre-2.1 default name '{}', which the next major version does not search for any more: rename it '{}' or declare it with '{}'",
+                                      RuntimeConstants.OLD_VM_LIBRARY_DEFAULT, RuntimeConstants.VM_LIBRARY_DEFAULT, RuntimeConstants.VM_LIBRARY);
+                         }
                      }
                      else
                      {
diff --git a/velocity-engine-core/src/test/java/org/apache/velocity/test/DeprecationWarningTestCase.java b/velocity-engine-core/src/test/java/org/apache/velocity/test/DeprecationWarningTestCase.java
index 39b278fd..4f45d30f 100644
--- a/velocity-engine-core/src/test/java/org/apache/velocity/test/DeprecationWarningTestCase.java
+++ b/velocity-engine-core/src/test/java/org/apache/velocity/test/DeprecationWarningTestCase.java
@@ -23,6 +23,7 @@
 import org.apache.velocity.exception.MathException;
 import org.apache.velocity.runtime.RuntimeConstants;
 import org.apache.velocity.runtime.resource.loader.StringResourceLoader;
+import org.apache.velocity.runtime.resource.util.StringResourceRepository;
 import org.apache.velocity.test.misc.TestVelocityEngine;
 
 import java.util.Properties;
@@ -38,6 +39,7 @@
  * and the settings the next major version does not provide any more:
  * <ul>
  *   <li>{@code velocimacro.enable_bc_mode}</li>
+ *   <li>an implicitly loaded macro library</li>
  * </ul>
  */
 public class DeprecationWarningTestCase extends BaseTestCase
@@ -486,4 +488,70 @@ public void testBcModeSilentWhenDeprecationOff()
         assertSilentAtInit(RuntimeConstants.VM_ENABLE_BC_MODE, false, RuntimeConstants.VM_ENABLE_BC_MODE, "true");
     }
 
+
+    /* ---- an implicitly loaded macro library: deprecated, declare it instead ---- */
+
+    private static final String OLD_DEFAULT_LIBRARY = "pre-2.1 default name";
+
+    /**
+     * Initializes an engine whose loader can serve a library under the given name, which the engine
+     * then looks for on its own unless a library is declared.
+     *
+     * @param warn value of runtime.deprecation.warn
+     * @param libraryName the name the library is served under
+     * @param declaredPath value of velocimacro.library.path, or null to leave it unset
+     * @return what was logged at init
+     */
+    private String warningsAtInitWithLibrary(boolean warn, String libraryName, String declaredPath)
+    {
+        StringResourceRepository repository = StringResourceLoader.getRepository();
+        repository.putStringResource(libraryName, "#macro(fromlibrary)x#end");
+        try
+        {
+            VelocityEngine ve = settingEngine(warn, RuntimeConstants.VM_LIBRARY, declaredPath);
+            return warningsAtInit(ve);
+        }
+        finally
+        {
+            repository.removeStringResource(libraryName);
+        }
+    }
+
+    public void testOldDefaultMacroLibraryNameWarns()
+    {
+        String out = warningsAtInitWithLibrary(true, RuntimeConstants.OLD_VM_LIBRARY_DEFAULT, null);
+        assertTrue("a library found under the pre-2.1 name must warn, log was:\n" + out,
+                   out.contains(OLD_DEFAULT_LIBRARY) && out.contains(RuntimeConstants.OLD_VM_LIBRARY_DEFAULT));
+        assertTrue("the warning must say how to fix it, log was:\n" + out,
+                   out.contains(RuntimeConstants.VM_LIBRARY_DEFAULT) && out.contains(RuntimeConstants.VM_LIBRARY));
+    }
+
+    public void testDefaultMacroLibraryNameNeverWarns()
+    {
+        // velocimacros.vtl is still searched for in the next major version: nothing to warn about
+        String out = warningsAtInitWithLibrary(true, RuntimeConstants.VM_LIBRARY_DEFAULT, null);
+        assertFalse("the current default name has nothing to warn about, log was:\n" + out,
+                    out.contains(OLD_DEFAULT_LIBRARY));
+    }
+
+    public void testDeclaredMacroLibraryNeverWarns()
+    {
+        String out = warningsAtInitWithLibrary(true, RuntimeConstants.OLD_VM_LIBRARY_DEFAULT, RuntimeConstants.OLD_VM_LIBRARY_DEFAULT);
+        assertFalse("a declared library has nothing to warn about, log was:\n" + out,
+                    out.contains(OLD_DEFAULT_LIBRARY));
+    }
+
+    public void testOldDefaultMacroLibrarySilentWhenNoneIsThere()
+    {
+        String out = warningsAtInit(settingEngine(true, null, null));
+        assertFalse("no library, no warning, log was:\n" + out, out.contains(OLD_DEFAULT_LIBRARY));
+    }
+
+    public void testOldDefaultMacroLibrarySilentWhenDeprecationOff()
+    {
+        String out = warningsAtInitWithLibrary(false, RuntimeConstants.OLD_VM_LIBRARY_DEFAULT, null);
+        assertFalse("no warning expected with runtime.deprecation.warn = false, log was:\n" + out,
+                    out.contains(OLD_DEFAULT_LIBRARY));
+    }
+
 }