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 93ba186 docs: refactor multiple documentation structures (#182)
93ba186 is described below
commit 93ba1862295ac1f0f96d6124581a9d82325b15c6
Author: tzssangglass <[email protected]>
AuthorDate: Thu Aug 11 15:26:01 2022 +0800
docs: refactor multiple documentation structures (#182)
---
README.md | 1 +
docs/en/latest/config.json | 12 +++
docs/en/latest/deployment-guide.md | 61 ++++++++++++
docs/en/latest/development.md | 33 +------
docs/en/latest/hot-reloading.md | 4 +
docs/en/latest/installation-guide.md | 111 ++++++++++++++++++++++
docs/en/latest/writing-filters.md | 176 -----------------------------------
docs/zh/quick-start.md | 2 +-
8 files changed, 191 insertions(+), 209 deletions(-)
diff --git a/README.md b/README.md
index 0e18ca2..01deb33 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ Version Matrix
|---------------------------|-----------------------------------------------------------------------------|
| 0.1.0 | >=
[2.7.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#270) |
| 0.2.0 | >=
[2.12.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#2102) |
+| 0.3.0 | >=
[2.15.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#2150) |
How it Works
-------------
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index eb6af5a..4ecf626 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -12,6 +12,18 @@
{
"type": "doc",
"id": "the-internal-of-apisix-java-plugin-runner"
+ },
+ {
+ "type": "doc",
+ "id": "installation-guide"
+ },
+ {
+ "type": "doc",
+ "id": "deployment-guide"
+ },
+ {
+ "type": "doc",
+ "id": "hot-reload"
}
]
}
diff --git a/docs/en/latest/deployment-guide.md
b/docs/en/latest/deployment-guide.md
new file mode 100644
index 0000000..8143d88
--- /dev/null
+++ b/docs/en/latest/deployment-guide.md
@@ -0,0 +1,61 @@
+---
+title: Deployment Guide
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+# Overview
+
+This document explains how to support multiple ways to deploy custom plugins.
+
+:::note
+
+This feature is WIP.
+
+:::
+
+### Ship plugin
+
+In your plugin's `pom.xml`, add the following configuration:
+```
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-maven-plugin</artifactId>
+ <configuration>
+ <classifier>exec</classifier>
+ </configuration>
+ </plugin>
+ </plugins>
+</build>
+```
+
+The standard Spring Boot executable JAR places all of your application classes
inside *BOOT-INF/classes*,
+making it impossible to inject into another project. This config builds an
additional non-executable JAR
+that can be used for dependency injection.
+
+Deploy the JARs to Maven Central.
+
+### Using a deployed plugin
+
+To use someone else's plugin, add their plugin's non-executable JAR as a
dependency in your project.
+Add the package name of their filters (usually the same as the Group ID) in
*scanBasePackages* in your main
+SpringBootApplication class to allow Spring to find the plugin *@Component*.
diff --git a/docs/en/latest/development.md b/docs/en/latest/development.md
index 01dcb24..567701d 100644
--- a/docs/en/latest/development.md
+++ b/docs/en/latest/development.md
@@ -23,38 +23,7 @@ title: Development
## Overview
-This document explains how to get started to develop the
apisix-java-plugin-runner.
-
-Prerequisites
--------------
-
-* JDK 11
-* APISIX 2.12.0
-* Clone the
[apisix-java-plugin-runner](https://github.com/apache/apisix-java-plugin-runner)
project.
-* Refer to [Debug](how-it-works.md#debug) to build the debug environment.
-
-Install
--------
-
-```shell
-cd /path/to/apisix-java-plugin-runner
-./mvnw install
-```
-
-Write Filter
-------------
-
-Refer to the code in the
[sample](https://github.com/apache/apisix-java-plugin-runner/tree/main/sample)
-to learn how to extend `PluginFilter`, define the order, rewrite requests and
stop requests.
-
-#### Code Location
-
-You need to put the code in
[runner-plugin](https://github.com/apache/apisix-java-plugin-runner/tree/main/runner-plugin/src/main/java/org/apache/apisix/plugin/runner/filter)
-so that the `apisix-java-plugin-runner.jar` will contain the filter
implementation class you wrote when you package it.
-
-#### The order of filter execution
-
-The order of execution of the filter in the runner is determined by the index
of the `conf` array in the `ext-plugin-pre-req` or `ext-plugin-post-req`
configuration.
+This document explains how to write custom plugins.
#### The name of filter execution
diff --git a/docs/en/latest/hot-reloading.md b/docs/en/latest/hot-reloading.md
index 58195c6..e26b977 100644
--- a/docs/en/latest/hot-reloading.md
+++ b/docs/en/latest/hot-reloading.md
@@ -1,3 +1,7 @@
+---
+title: Hot-Reload
+---
+
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/en/latest/installation-guide.md
b/docs/en/latest/installation-guide.md
new file mode 100644
index 0000000..2579053
--- /dev/null
+++ b/docs/en/latest/installation-guide.md
@@ -0,0 +1,111 @@
+---
+title: Installation
+keywords:
+- apisix-java-plugin-runner
+- Installation
+description: This document explains how to installation and use
apisix-java-plugin-runner.
+---
+
+
+<!--
+#
+# 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.
+#
+-->
+
+## Overview
+
+This document explains how to install apisix-java-plugin-runner.
+
+Prerequisites
+-------------
+
+* JDK 11
+* APISIX 2.15.0
+* Refer to [Debug](how-it-works.md#debug) to build the debug environment.
+
+Install
+-------
+
+1. Create a simple web application with Spring Boot, and choose Maven as the
build tool.
+
+2. Add the apisix-java-plugin-runner dependency in your POM, like:
+
+```xml
+<dependency>
+ <groupId>org.apache.apisix</groupId>
+ <artifactId>apisix-runner-starter</artifactId>
+ <version>0.3.0</version>
+</dependency>
+```
+
+3. Configuring the scan package path
+
+```xml
+
+```java
+@SpringBootApplication(scanBasePackages =
{"your-filter's-package-name","org.apache.apisix.plugin.runner"})
+```
+
+4. Excluding the default logging framework
+
+To prevent multiple slf4j bindings, exclude the `logback-classic` and
`log4j-to-slf4j` in `pom.xml`, like:
+
+```xml
+<dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter</artifactId>
+ <exclusions>
+ <exclusion>
+ <groupId>ch.qos.logback</groupId>
+ <artifactId>logback-classic</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-to-slf4j</artifactId>
+ </exclusion>
+ </exclusions>
+</dependency>
+```
+
+5. Configuring the address for Unix Domain Socket communication with APISIX
+
+```properties
+socket.file = /tmp/runner.sock
+```
+
+6. Implementing the `PluginFilter` interface
+
+When you write your custom plugins, you need to implement the `PluginFilter`
interface and
+inject filters into Spring Boot's object lifecycle management using
`@Component`.
+
+code example:
+
+```java
+@Component
+public class RewriteRequestDemoFilter implements PluginFilter {
+ ......
+ implementing functions
+}
+```
+
+You can refer to [development](./development.md) to learn how to write custom
plugins.
+
+Demo
+-------
+
+A Demo Project that work with apisix-java-plugin-runner and custom filters
+can be found at:
[java-plugin-runner-demo](https://github.com/tzssangglass/java-plugin-runner-demo-1).
diff --git a/docs/en/latest/writing-filters.md
b/docs/en/latest/writing-filters.md
deleted file mode 100644
index 78868fe..0000000
--- a/docs/en/latest/writing-filters.md
+++ /dev/null
@@ -1,176 +0,0 @@
-<!--
-#
-# 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.
-#
--->
-
-# Overview
-
-This document explains how to develop and ship Java plugins using
apisix-java-plugin-runner's official Maven release.
-
-A Demo Project can be found at:
https://github.com/tzssangglass/java-plugin-runner-demo-1
-
-___
-
-### Write Java plugin
-
-Create a new Maven Spring Boot Project.
-
-Add the GAV of `apisix-java-plugin-runner` in `pom.xml`.
-```
-<dependency>
- <groupId>org.apache.apisix</groupId>
- <artifactId>apisix-runner-starter</artifactId>
- <version>0.3.0</version>
-</dependency>
-```
-Be sure to add the Maven JAR into the class path. Use
`org.apache.apisix:apisix-runner-starter:0.3.0` when asked for Maven
coordinates. For Intellij IDEA users unsure on how to add files to the class
path, follow
https://stackoverflow.com/questions/16742085/adding-jar-files-to-intellijidea-classpath.
-
-To prevent multiple slf4j (a facade for various logging frameworks) bindings,
exclude the *logback-classic* and *log4j-to-slf4j* transitive dependencies from
being built within *spring-boot-starter*
-
-```
-<dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter</artifactId>
- <exclusions>
- <exclusion>
- <groupId>ch.qos.logback</groupId>
- <artifactId>logback-classic</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-to-slf4j</artifactId>
- </exclusion>
- </exclusions>
-</dependency>
-```
-The final pom.xml file should look similar to
-```
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
https://maven.apache.org/xsd/maven-4.0.0.xsd";>
- <modelVersion>4.0.0</modelVersion>
- <parent>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-parent</artifactId>
- <version>2.7.1</version>
- <relativePath/> <!-- lookup parent from repository -->
- </parent>
- <groupId>com.example</groupId>
- <artifactId>demo</artifactId>
- <version>0.0.1-SNAPSHOT</version>
- <name>demo</name>
- <description>demo</description>
- <properties>
- <java.version>11</java.version>
- </properties>
- <dependencies>
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter</artifactId>
- <exclusions>
- <exclusion>
- <groupId>ch.qos.logback</groupId>
- <artifactId>logback-classic</artifactId>
- </exclusion>
- <exclusion>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-to-slf4j</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>org.projectlombok</groupId>
- <artifactId>lombok</artifactId>
- <optional>true</optional>
- </dependency>
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-test</artifactId>
- <scope>test</scope>
- </dependency>
- <groupId>org.apache.apisix</groupId>
- <artifactId>apisix-runner-starter</artifactId>
- <version>0.3.0</version>
- </dependency>
- </dependencies>
- <build>
- <plugins>
- <plugin>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-maven-plugin</artifactId>
- <configuration>
- <excludes>
- <exclude>
- <groupId>org.projectlombok</groupId>
- <artifactId>lombok</artifactId>
- </exclude>
- </excludes>
- </configuration>
- </plugin>
- </plugins>
- </build>
-</project>
-```
-
-In the Java main class, include the line
-```
-@SpringBootApplication(scanBasePackages =
{"your-filter's-package-name","org.apache.apisix.plugin.runner"})
-```
-*scanBasePackages* allows Spring Boot to read the *@Component* classes that
exist inside of the Maven JAR along with the implemented Java filter.
-
-An example main class looks like
-```
-package com.example.demo;
-
-import org.springframework.boot.SpringApplication;
-import org.springframework.boot.autoconfigure.SpringBootApplication;
-
-@SpringBootApplication(scanBasePackages =
{"com.example.demo","org.apache.apisix.plugin.runner"})
-public class DemoApplication {
- public static void main(String[] args) {
- SpringApplication.run(DemoApplication.class, args);
- }
-
-}
-```
-
-In *~/src/main/resources/application.properties*, add
-```
-socket.file = /tmp/runner.sock
-```
-This allows our java-plugin-runner to communicate with the main APISIX process.
-
-Build your Java plugin! Be sure to label each filter class as a Spring
*@Component* while following the guide at:
-https://github.com/apache/apisix-java-plugin-runner/blob/main/docs/en/latest/development.md
-
-### Ship plugin
-
-In your plugin's *pom.xml*, add
-```
-<configuration>
- <classifier>exec</classifier>
-</configuration>
-```
-
-The standard Spring Boot executable JAR places all of your application classes
inside *BOOT-INF/classes*, making it impossible to inject into another project.
This config builds an additional non-executable JAR that can be used for
dependency injection.
-
-Deploy the JARs to Maven Central.
-
-### Using a deployed plugin
-
-To use someone else's plugin, add their plugin's non-executable JAR as a
dependency in your project. Add the package name of their filters (usually the
same as the Group ID) in *scanBasePackages* in your main SpringBootApplication
class to allow Spring to find the plugin *@Component*.
-
diff --git a/docs/zh/quick-start.md b/docs/zh/quick-start.md
index 77bfe58..c0c8107 100644
--- a/docs/zh/quick-start.md
+++ b/docs/zh/quick-start.md
@@ -3,7 +3,7 @@
### 准备工作
* JDK 11
-* APISIX 2.12.0
+* APISIX 2.15.0
* Clone the
[apisix-java-plugin-runner](https://github.com/apache/apisix-java-plugin-runner)
project。
### 开发扩展插件过滤器
