This is an automated email from the ASF dual-hosted git repository.
tzssangglass pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/apisix-java-plugin-runner.git
The following commit(s) were added to refs/heads/main by this push:
new f1454d2 docs: add hot-reloading documentation (#166)
f1454d2 is described below
commit f1454d2eea8fd707780f24031c0d089bb2b97c39
Author: Eric Liu <[email protected]>
AuthorDate: Sun Jul 17 18:36:10 2022 -0700
docs: add hot-reloading documentation (#166)
---
docs/en/latest/hot-reloading.md | 71 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 71 insertions(+)
diff --git a/docs/en/latest/hot-reloading.md b/docs/en/latest/hot-reloading.md
new file mode 100644
index 0000000..58195c6
--- /dev/null
+++ b/docs/en/latest/hot-reloading.md
@@ -0,0 +1,71 @@
+<!--
+#
+# 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.
+#
+-->
+
+Hot Reloading
+=================
+
+Overview
+-----
+This document explains the new hot reload feature provided by
apisix-java-plugin-runner.
+
+APISIX offers many fully-featured plugins and also allows users to develop
their own plugins in Lua, Java, and other languages. Currently, APISIX offers
hot reloading of plugins developed internally (Lua), however, hot reloading of
external Java plugins is currently not supported.
+
+This feature provides hot reloading of Java plugins through the implementation
of a custom classloader that can reload both Java classes and SpringBoot beans
during runtime. When apisix-java-plugin-runner is launched, a scheduled side
process watches for file modifications (create, delete, or change) in the
folder that holds the user-implemented filters. When a user changes their
filter while the plugin runner is running, the file watcher immediately picks
up on it, and the file is recom [...]
+
+This saves time during development and enables users to change parts of their
code without restarting the entire plugin-runner.
+
+How to use
+-----
+Using and understanding the hot reload feature is simple.
+
+To begin, make sure your filters are located in the *runner/filter* module
(along with *package-info.java*). If you are implementing filters from a
different location, be sure to specify the load-path and the package name in
the *application.yaml* file located in *runner-starter/src/main/resources/*.
+
+Path names should be enclosed in forward slashes
*~/runner-plugin/src/main/java/org/apache/apisix/plugin/runner/filter/*
+
+Package name should look like *org.apache.apisix.plugin.runner.filter*
+
+Run APISIX and apisix-java-plugin-runner.
+
+Create a route for your filter (follow
https://apisix.apache.org/blog/2021/06/21/use-java-to-write-apache-apisix-plugins/
for more information).
+
+Send a request to your route to ensure everything is functioning.
+
+Modify your files in *runner/filter* (or other location).
+
+Send another request to your route, changes should be noticeable immediately.
+
+Keep in mind, for the file watcher to detect a change, it may be necessary to
save the file.
+
+How it works
+-----
+Hot reload in apisix-java-plugin-runner is implemented using a custom
classloader that dynamically recompiles and reloads filters. The Java
WatchService is used to track file updates. Each file update is registered
either as a
+1. File Modification
+2. File Creation
+3. File Deletion
+
+where each type of file update is handled slightly differently.
+
+After File Modification, the following process occurs:
+1. The Spring Bean (associated with the modified filter) is removed from the
Spring Boot Application Context
+2. The Filter source code is recompiled
+3. The Filter class is reloaded
+4. The new Spring Bean is generated from the modified Filter class
+5. The new Spring Bean is loaded into Application Context
+
+File Creation and Deletion follow a similar process.
