Skip to content

Commit 93ba186

Browse files
tzssangglasstzssangglass
authored
docs: refactor multiple documentation structures (#182)
1 parent 58f8088 commit 93ba186

8 files changed

Lines changed: 191 additions & 209 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Version Matrix
2929
|---------------------------|-----------------------------------------------------------------------------|
3030
| 0.1.0 | >= [2.7.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#270) |
3131
| 0.2.0 | >= [2.12.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#2102) |
32+
| 0.3.0 | >= [2.15.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#2150) |
3233

3334
How it Works
3435
-------------

‎docs/en/latest/config.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,18 @@
1212
{
1313
"type": "doc",
1414
"id": "the-internal-of-apisix-java-plugin-runner"
15+
},
16+
{
17+
"type": "doc",
18+
"id": "installation-guide"
19+
},
20+
{
21+
"type": "doc",
22+
"id": "deployment-guide"
23+
},
24+
{
25+
"type": "doc",
26+
"id": "hot-reload"
1527
}
1628
]
1729
}

‎docs/en/latest/deployment-guide.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Deployment Guide
3+
---
4+
5+
<!--
6+
#
7+
# Licensed to the Apache Software Foundation (ASF) under one or more
8+
# contributor license agreements. See the NOTICE file distributed with
9+
# this work for additional information regarding copyright ownership.
10+
# The ASF licenses this file to You under the Apache License, Version 2.0
11+
# (the "License"); you may not use this file except in compliance with
12+
# the License. You may obtain a copy of the License at
13+
#
14+
# http://www.apache.org/licenses/LICENSE-2.0
15+
#
16+
# Unless required by applicable law or agreed to in writing, software
17+
# distributed under the License is distributed on an "AS IS" BASIS,
18+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19+
# See the License for the specific language governing permissions and
20+
# limitations under the License.
21+
#
22+
-->
23+
24+
# Overview
25+
26+
This document explains how to support multiple ways to deploy custom plugins.
27+
28+
:::note
29+
30+
This feature is WIP.
31+
32+
:::
33+
34+
### Ship plugin
35+
36+
In your plugin's `pom.xml`, add the following configuration:
37+
```
38+
<build>
39+
<plugins>
40+
<plugin>
41+
<groupId>org.springframework.boot</groupId>
42+
<artifactId>spring-boot-maven-plugin</artifactId>
43+
<configuration>
44+
<classifier>exec</classifier>
45+
</configuration>
46+
</plugin>
47+
</plugins>
48+
</build>
49+
```
50+
51+
The standard Spring Boot executable JAR places all of your application classes inside *BOOT-INF/classes*,
52+
making it impossible to inject into another project. This config builds an additional non-executable JAR
53+
that can be used for dependency injection.
54+
55+
Deploy the JARs to Maven Central.
56+
57+
### Using a deployed plugin
58+
59+
To use someone else's plugin, add their plugin's non-executable JAR as a dependency in your project.
60+
Add the package name of their filters (usually the same as the Group ID) in *scanBasePackages* in your main
61+
SpringBootApplication class to allow Spring to find the plugin *@Component*.

‎docs/en/latest/development.md‎

Lines changed: 1 addition & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -23,38 +23,7 @@ title: Development
2323

2424
## Overview
2525

26-
This document explains how to get started to develop the apisix-java-plugin-runner.
27-
28-
Prerequisites
29-
-------------
30-
31-
* JDK 11
32-
* APISIX 2.12.0
33-
* Clone the [apisix-java-plugin-runner](https://github.com/apache/apisix-java-plugin-runner) project.
34-
* Refer to [Debug](how-it-works.md#debug) to build the debug environment.
35-
36-
Install
37-
-------
38-
39-
```shell
40-
cd /path/to/apisix-java-plugin-runner
41-
./mvnw install
42-
```
43-
44-
Write Filter
45-
------------
46-
47-
Refer to the code in the [sample](https://github.com/apache/apisix-java-plugin-runner/tree/main/sample)
48-
to learn how to extend `PluginFilter`, define the order, rewrite requests and stop requests.
49-
50-
#### Code Location
51-
52-
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)
53-
so that the `apisix-java-plugin-runner.jar` will contain the filter implementation class you wrote when you package it.
54-
55-
#### The order of filter execution
56-
57-
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.
26+
This document explains how to write custom plugins.
5827

5928
#### The name of filter execution
6029

‎docs/en/latest/hot-reloading.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
title: Hot-Reload
3+
---
4+
15
<!--
26
#
37
# Licensed to the Apache Software Foundation (ASF) under one or more

‎docs/en/latest/installation-guide.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: Installation
3+
keywords:
4+
- apisix-java-plugin-runner
5+
- Installation
6+
description: This document explains how to installation and use apisix-java-plugin-runner.
7+
---
8+
9+
10+
<!--
11+
#
12+
# Licensed to the Apache Software Foundation (ASF) under one or more
13+
# contributor license agreements. See the NOTICE file distributed with
14+
# this work for additional information regarding copyright ownership.
15+
# The ASF licenses this file to You under the Apache License, Version 2.0
16+
# (the "License"); you may not use this file except in compliance with
17+
# the License. You may obtain a copy of the License at
18+
#
19+
# http://www.apache.org/licenses/LICENSE-2.0
20+
#
21+
# Unless required by applicable law or agreed to in writing, software
22+
# distributed under the License is distributed on an "AS IS" BASIS,
23+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
24+
# See the License for the specific language governing permissions and
25+
# limitations under the License.
26+
#
27+
-->
28+
29+
## Overview
30+
31+
This document explains how to install apisix-java-plugin-runner.
32+
33+
Prerequisites
34+
-------------
35+
36+
* JDK 11
37+
* APISIX 2.15.0
38+
* Refer to [Debug](how-it-works.md#debug) to build the debug environment.
39+
40+
Install
41+
-------
42+
43+
1. Create a simple web application with Spring Boot, and choose Maven as the build tool.
44+
45+
2. Add the apisix-java-plugin-runner dependency in your POM, like:
46+
47+
```xml
48+
<dependency>
49+
<groupId>org.apache.apisix</groupId>
50+
<artifactId>apisix-runner-starter</artifactId>
51+
<version>0.3.0</version>
52+
</dependency>
53+
```
54+
55+
3. Configuring the scan package path
56+
57+
```xml
58+
59+
```java
60+
@SpringBootApplication(scanBasePackages = {"your-filter's-package-name","org.apache.apisix.plugin.runner"})
61+
```
62+
63+
4. Excluding the default logging framework
64+
65+
To prevent multiple slf4j bindings, exclude the `logback-classic` and `log4j-to-slf4j` in `pom.xml`, like:
66+
67+
```xml
68+
<dependency>
69+
<groupId>org.springframework.boot</groupId>
70+
<artifactId>spring-boot-starter</artifactId>
71+
<exclusions>
72+
<exclusion>
73+
<groupId>ch.qos.logback</groupId>
74+
<artifactId>logback-classic</artifactId>
75+
</exclusion>
76+
<exclusion>
77+
<groupId>org.apache.logging.log4j</groupId>
78+
<artifactId>log4j-to-slf4j</artifactId>
79+
</exclusion>
80+
</exclusions>
81+
</dependency>
82+
```
83+
84+
5. Configuring the address for Unix Domain Socket communication with APISIX
85+
86+
```properties
87+
socket.file = /tmp/runner.sock
88+
```
89+
90+
6. Implementing the `PluginFilter` interface
91+
92+
When you write your custom plugins, you need to implement the `PluginFilter` interface and
93+
inject filters into Spring Boot's object lifecycle management using `@Component`.
94+
95+
code example:
96+
97+
```java
98+
@Component
99+
public class RewriteRequestDemoFilter implements PluginFilter {
100+
......
101+
implementing functions
102+
}
103+
```
104+
105+
You can refer to [development](./development.md) to learn how to write custom plugins.
106+
107+
Demo
108+
-------
109+
110+
A Demo Project that work with apisix-java-plugin-runner and custom filters
111+
can be found at: [java-plugin-runner-demo](https://github.com/tzssangglass/java-plugin-runner-demo-1).

0 commit comments

Comments
 (0)