<refactor>: refactor the velocity-engine to be more scalable

1. define new  and  interfaces. APIs for users, SPIs for developers.
2. implements some builtin spi interfaces

Author: xiaoma20082008

pom.xml

@@ -137,6 +137,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.8.1</version>
                 <configuration>
                     <showDeprecation>true</showDeprecation>
                     <showWarning>true</showWarning>

velocity-engine-core/README.md

@@ -0,0 +1,62 @@
+```
+        +----------+                             |
+        |          |  nowContext  +---------+    |
+        |          | -----------> | Context | <--+ run
+   init |          |              +---------+    |
+  ----->| Velocity |                             v
+        |          |  getTemplate  +------------------+
+        |          | ------------> |     Template     |
+        |          |               +------------------+
+        +----------+
+```
+
+```java
+import java.io.StringReader;
+import java.io.Writer;
+import org.apache.velocity.Template;
+import org.apache.velocity.spi.Translator;
+import org.apache.velocity.runtime.parser.Parser;
+import org.apache.velocity.runtime.parser.node.SimpleNode;
+import org.apache.velocity.runtime.resource.Resource;
+import org.apache.velocity.runtime.resource.ResourceManager;
+import org.apache.velocity.runtime.resource.loader.ResourceLoader;
+
+public class View {
+
+  /**
+   * render the template
+   *
+   * @param name template name
+   * @param writer out
+   */
+  public void render(String name, Writer writer) {
+    // 1. get template
+    Template template = Velocity.getTemplate(name, "utf-8");
+    // 2. get current context
+    Context context = Velocity.nowContext();
+    // 3. render template
+    template.render(context, writer);
+  }
+}
+
+public class Velocity {
+
+  private ResourceManager resourceManager;
+  private Parser parser;
+  private Translator translator;
+  private ResourceLoader loader;
+
+  public Template getTemplate(String name, String encoding) {
+    String path = toPath(name);
+    Resource resource = resourceManager.getResource(path, ResourceManager.RESOURCE_TEMPLATE, encoding);
+    SimpleNode node = parser.parse(new StringReader((String) resource.getData()), new Template());
+    return translator.translate(resource, node);
+  }
+
+  private String toPath(String name) {
+    return "suffix/" + name;
+  }
+
+}
+
+```

velocity-engine-core/src/main/java/org/apache/velocity/api/Node.java

@@ -0,0 +1,8 @@
+package org.apache.velocity.api;
+
+import org.apache.velocity.runtime.visitor.BaseVisitor;
+
+public interface Node {
+
+  void accept(BaseVisitor visitor);
+}

velocity-engine-core/src/main/java/org/apache/velocity/api/Resource.java

@@ -0,0 +1,99 @@
+package org.apache.velocity.api;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.Reader;
+import java.util.Locale;
+import org.apache.velocity.runtime.RuntimeInstance;
+
+public interface Resource {
+
+  /**
+   * Get the resource name.
+   *
+   * @return name
+   */
+  String getName();
+
+  /**
+   * Get the resource encoding.
+   *
+   * @return encoding
+   */
+  String getEncoding();
+
+  /**
+   * Get the resource locale.
+   *
+   * @return locale
+   */
+  Locale getLocale();
+
+  /**
+   * Get the resource last modified time.
+   *
+   * @return last modified time
+   */
+  long getLastModified();
+
+  /**
+   * Get the resource length.
+   *
+   * @return source length
+   */
+  long getLength();
+
+  /**
+   * Get the template source.
+   *
+   * @return source
+   * @throws IOException - If an I/O error occurs
+   */
+  String getSource() throws IOException;
+
+  /**
+   * Get the template source reader.
+   * <p/>
+   * NOTE: Don't forget close the reader.
+   * <p/>
+   * <pre>
+   * Reader reader = resource.openReader();
+   * try {
+   * 	 // do something ...
+   * } finally {
+   * 	 reader.close();
+   * }
+   * </pre>
+   *
+   * @return source reader
+   * @throws IOException - If an I/O error occurs
+   */
+  Reader openReader() throws IOException;
+
+  /**
+   * Get the template source input stream.
+   * <p/>
+   * NOTE: Don't forget close the input stream.
+   * <p/>
+   * <pre>
+   * InputStream stream = resource.openStream();
+   * try {
+   * 	 // do something ...
+   * } finally {
+   * 	 stream.close();
+   * }
+   * </pre>
+   *
+   * @return source input stream
+   * @throws IOException - If an I/O error occurs
+   */
+  InputStream openStream() throws IOException;
+
+  /**
+   * Get the template engine.
+   *
+   * @return engine
+   */
+  RuntimeInstance getEngine();
+
+}

velocity-engine-core/src/main/java/org/apache/velocity/api/Template.java

@@ -0,0 +1,13 @@
+package org.apache.velocity.api;
+
+import java.io.IOException;
+import java.io.Writer;
+import java.text.ParseException;
+import org.apache.velocity.context.Context;
+
+public interface Template extends Resource, Node {
+
+  void render(Context context, Writer out) throws IOException, ParseException;
+
+  Object evaluate(Context context) throws ParseException;
+}

velocity-engine-core/src/main/java/org/apache/velocity/spi/Cache.java

@@ -0,0 +1,25 @@
+package org.apache.velocity.spi;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.util.concurrent.ConcurrentMap;
+
+public interface Cache<K, V> extends ConcurrentMap<K, V> {
+}

velocity-engine-core/src/main/java/org/apache/velocity/spi/Compiler.java

@@ -0,0 +1,28 @@
+package org.apache.velocity.spi;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import org.apache.velocity.exception.VelocityException;
+
+public interface Compiler {
+
+  Class<?> compile(String source) throws VelocityException;
+
+}

velocity-engine-core/src/main/java/org/apache/velocity/spi/Converter.java

@@ -0,0 +1,25 @@
+package org.apache.velocity.spi;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+public interface Converter {
+
+  String convert(String key, String value);
+}

velocity-engine-core/src/main/java/org/apache/velocity/spi/Loader.java

@@ -0,0 +1,38 @@
+package org.apache.velocity.spi;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Locale;
+import org.apache.velocity.api.Resource;
+
+public interface Loader {
+
+  /**
+   * @param suffix resource suffix
+   * @return resource names.
+   */
+  List<String> list(String suffix) throws IOException;
+
+  boolean exists(String name, Locale locale);
+
+  Resource load(String name, Locale locale, String encoding) throws IOException;
+}