Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit de48ff1

Browse files
ericluoliuericluoliu
authored
docs: add documentation for writing plugins using Maven JAR (#169)
1 parent 7b4fbb5 commit de48ff1

File tree

1 file changed

+157
-0
lines changed

1 file changed

+157
-0
lines changed

‎docs/en/latest/writing-filters.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
<!--
2+
#
3+
# Licensed to the Apache Software Foundation (ASF) under one or more
4+
# contributor license agreements. See the NOTICE file distributed with
5+
# this work for additional information regarding copyright ownership.
6+
# The ASF licenses this file to You under the Apache License, Version 2.0
7+
# (the "License"); you may not use this file except in compliance with
8+
# the License. You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
#
18+
-->
19+
20+
# Overview
21+
22+
This document explains how to develop Java plugins using apisix-java-plugin-runner's official Maven release.
23+
24+
A Demo Project can be found at: https://github.com/tzssangglass/java-plugin-runner-demo-1
25+
26+
___
27+
28+
Create a new Maven Spring Boot Project.
29+
30+
Add the GAV of `apisix-java-plugin-runner` in `pom.xml`.
31+
```
32+
<dependency>
33+
<groupId>org.apache.apisix</groupId>
34+
<artifactId>apisix-runner-starter</artifactId>
35+
<version>0.3.0</version>
36+
</dependency>
37+
```
38+
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.
39+
40+
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*
41+
42+
```
43+
<dependency>
44+
<groupId>org.springframework.boot</groupId>
45+
<artifactId>spring-boot-starter</artifactId>
46+
<exclusions>
47+
<exclusion>
48+
<groupId>ch.qos.logback</groupId>
49+
<artifactId>logback-classic</artifactId>
50+
</exclusion>
51+
<exclusion>
52+
<groupId>org.apache.logging.log4j</groupId>
53+
<artifactId>log4j-to-slf4j</artifactId>
54+
</exclusion>
55+
</exclusions>
56+
</dependency>
57+
```
58+
The final pom.xml file should look similar to
59+
```
60+
<?xml version="1.0" encoding="UTF-8"?>
61+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
62+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
63+
<modelVersion>4.0.0</modelVersion>
64+
<parent>
65+
<groupId>org.springframework.boot</groupId>
66+
<artifactId>spring-boot-starter-parent</artifactId>
67+
<version>2.7.1</version>
68+
<relativePath/> <!-- lookup parent from repository -->
69+
</parent>
70+
<groupId>com.example</groupId>
71+
<artifactId>demo</artifactId>
72+
<version>0.0.1-SNAPSHOT</version>
73+
<name>demo</name>
74+
<description>demo</description>
75+
<properties>
76+
<java.version>11</java.version>
77+
</properties>
78+
<dependencies>
79+
<dependency>
80+
<groupId>org.springframework.boot</groupId>
81+
<artifactId>spring-boot-starter</artifactId>
82+
<exclusions>
83+
<exclusion>
84+
<groupId>ch.qos.logback</groupId>
85+
<artifactId>logback-classic</artifactId>
86+
</exclusion>
87+
<exclusion>
88+
<groupId>org.apache.logging.log4j</groupId>
89+
<artifactId>log4j-to-slf4j</artifactId>
90+
</exclusion>
91+
</exclusions>
92+
</dependency>
93+
<dependency>
94+
<groupId>org.projectlombok</groupId>
95+
<artifactId>lombok</artifactId>
96+
<optional>true</optional>
97+
</dependency>
98+
<dependency>
99+
<groupId>org.springframework.boot</groupId>
100+
<artifactId>spring-boot-starter-test</artifactId>
101+
<scope>test</scope>
102+
</dependency>
103+
<groupId>org.apache.apisix</groupId>
104+
<artifactId>apisix-runner-starter</artifactId>
105+
<version>0.3.0</version>
106+
</dependency>
107+
</dependencies>
108+
<build>
109+
<plugins>
110+
<plugin>
111+
<groupId>org.springframework.boot</groupId>
112+
<artifactId>spring-boot-maven-plugin</artifactId>
113+
<configuration>
114+
<excludes>
115+
<exclude>
116+
<groupId>org.projectlombok</groupId>
117+
<artifactId>lombok</artifactId>
118+
</exclude>
119+
</excludes>
120+
</configuration>
121+
</plugin>
122+
</plugins>
123+
</build>
124+
</project>
125+
```
126+
127+
In the Java main class, include the line
128+
```
129+
@SpringBootApplication(scanBasePackages = {"your-filter's-package-name","org.apache.apisix.plugin.runner"})
130+
```
131+
*scanBasePackages* allows Spring Boot to read the *@Component* classes that exist inside of the Maven JAR along with the implemented Java filter.
132+
133+
An example main class looks like
134+
```
135+
package com.example.demo;
136+
137+
import org.springframework.boot.SpringApplication;
138+
import org.springframework.boot.autoconfigure.SpringBootApplication;
139+
140+
@SpringBootApplication(scanBasePackages = {"com.example.demo","org.apache.apisix.plugin.runner"})
141+
public class DemoApplication {
142+
public static void main(String[] args) {
143+
SpringApplication.run(DemoApplication.class, args);
144+
}
145+
146+
}
147+
```
148+
149+
In *~/src/main/resources/application.properties*, add
150+
```
151+
socket.file = /tmp/runner.sock
152+
```
153+
This allows our java-plugin-runner to communicate with the main APISIX process.
154+
155+
Finally, build your Java plugin! Be sure to label each filter class as a Spring *@Component* while following the guide at:
156+
https://github.com/apache/apisix-java-plugin-runner/blob/main/docs/en/latest/development.md
157+

0 commit comments

Comments
 (0)