View Javadoc
1   /*
2    * SPDX-FileCopyrightText: Copyright (c) 2012-2026 Yegor Bugayenko
3    * SPDX-License-Identifier: MIT
4    */
5   package com.jcabi.velocity;
6   
7   import java.io.PrintWriter;
8   import java.io.StringWriter;
9   import java.util.Map;
10  import org.apache.velocity.Template;
11  import org.apache.velocity.VelocityContext;
12  import org.apache.velocity.app.VelocityEngine;
13  import org.apache.velocity.runtime.RuntimeConstants;
14  import org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader;
15  
16  /**
17   * Velocity page, builder/wrapper around Apache Velocity template.
18   *
19   * <p>The template should be in classpath:</p>
20   *
21   * <pre> String text = new VelocityPage("com/foo/my-template.vm")
22   *   .set("name", "John Doe")
23   *   .toString();</pre>
24   *
25   * <p>Logging is forwarded to SLF4J by Apache Velocity 2.x.</p>
26   *
27   * <p>The class is mutable and thread-safe.</p>
28   *
29   * @see <a href="https://velocity.apache.org/engine/2.4.1/user-guide.html">Velocity User Guide</a>
30   * @see <a href="https://velocity.apache.org/engine/2.4.1/developer-guide.html">Velocity Developer Guide</a>
31   * @since 0.1.6
32   */
33  @SuppressWarnings("PMD.AvoidSynchronizedStatement")
34  public final class VelocityPage {
35  
36      /**
37       * The engine to use.
38       */
39      private static final VelocityEngine ENGINE = VelocityPage.init();
40  
41      /**
42       * Name of resource.
43       */
44      private final transient String name;
45  
46      /**
47       * The context.
48       */
49      private final transient VelocityContext context;
50  
51      /**
52       * Public ctor, with absolute resource name in classpath.
53       *
54       * @param res Name of resource with template (absolute resource name in
55       *  classpath)
56       */
57      public VelocityPage(final String res) {
58          this.name = res;
59          this.context = new VelocityContext();
60      }
61  
62      /**
63       * Set the name to the value specified.
64       *
65       * @param prop Name of the property to set
66       * @param value The value to use
67       * @return This object
68       */
69      public VelocityPage set(final String prop, final Object value) {
70          synchronized (this.context) {
71              this.context.put(prop, value);
72          }
73          return this;
74      }
75  
76      /**
77       * Set all names in one go.
78       *
79       * @param args Map of arguments
80       * @return This object
81       * @since 0.8
82       */
83      public VelocityPage set(final Map<String, Object> args) {
84          synchronized (this.context) {
85              for (final Map.Entry<String, Object> entry : args.entrySet()) {
86                  this.context.put(entry.getKey(), entry.getValue());
87              }
88          }
89          return this;
90      }
91  
92      @Override
93      public String toString() {
94          final Template template =
95              VelocityPage.ENGINE.getTemplate(this.name, "UTF-8");
96          final StringWriter writer = new StringWriter();
97          try (PrintWriter print = new PrintWriter(writer)) {
98              template.merge(this.context, print);
99          }
100         return writer.toString();
101     }
102 
103     private static VelocityEngine init() {
104         final VelocityEngine engine = new VelocityEngine();
105         engine.setProperty(RuntimeConstants.RESOURCE_LOADERS, "cp");
106         engine.setProperty(
107             "resource.loader.cp.class",
108             ClasspathResourceLoader.class.getName()
109         );
110         engine.init();
111         return engine;
112     }
113 }