momo-jun commented on code in PR #361: URL: https://github.com/apache/pulsar-site/pull/361#discussion_r1064242264
########## docs/develop-plugin.md: ########## @@ -6,6 +6,125 @@ sidebar_label: "Plugin" You can develop various plugins for Pulsar, such as entry filters, protocol handlers, interceptors, and so on. +## Additional Servlets + +This chapter describes what additional servlets are and how to use them. + +### What is an additional servlet? + +Pulsar offers a multitude of REST APIs to interact with it. To expose additional custom logic as a REST API, Pulsar offers the concept of additional servlets. These servlets run as plugins in either the broker or the pulsar proxy. + +### How to use an additional servlet? + +Take a look at [this example implementation](https://github.com/apache/pulsar/blob/master/tests/docker-images/java-test-plugins/src/main/java/org/apache/pulsar/tests/integration/plugins/RandomAdditionalServlet.java), or follow the steps below: + +1. Create a Maven project. + +2. Implement the `AdditionalServlet` or `AdditionalServletWithPulsarService` interface. + +3. Package your project into a NAR file. + +4. Configure the `broker.conf` file (or the `standalone.conf` file) and restart your broker. + +#### Step 1: Create a Maven project + +For how to create a Maven project, see [here](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html). + +#### Step 2: Implement the `AdditionalServlet` interface + +1. Add a dependency for `pulsar-broker` in the `pom.xml` file as displayed. Otherwise, you can not find the [`AdditionalServlet`](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/web/plugin/servlet/AdditionalServlet.java) interface. + + ```xml + + <dependency> + <groupId>org.apache.pulsar</groupId> + <artifactId>pulsar-broker</artifactId> + <version>${pulsar.version}</version> + <scope>provided</scope> + </dependency> + + ``` + +2. Implement the methods of the `AdditionalServlet` interface. + + - `loadConfig` allows you to configure your servlet by loading configuration properties from the `PulsarConfiguration`. + + - `getBasePath` defines the path your servlet will be loaded under. + + - `getServletHolder` returns the `ServletHolder` for this servlet. + + - `close` allows you to free up resources. + +3. Describe a NAR file. + + Create an `additional_servlet.yml` file in the `resources/META-INF/services` directory to describe a NAR file. + + ```conf + name: my-servlet + description: Describes my-servlet + additionalServletClass: org.my.package.MyServlet + + ``` + +#### Step 3: package your project into a NAR file Review Comment: ```suggestion #### Step 3: Package your project into a NAR file ``` ########## docs/develop-plugin.md: ########## @@ -6,6 +6,125 @@ sidebar_label: "Plugin" You can develop various plugins for Pulsar, such as entry filters, protocol handlers, interceptors, and so on. +## Additional Servlets + +This chapter describes what additional servlets are and how to use them. + +### What is an additional servlet? + +Pulsar offers a multitude of REST APIs to interact with it. To expose additional custom logic as a REST API, Pulsar offers the concept of additional servlets. These servlets run as plugins in either the broker or the pulsar proxy. + +### How to use an additional servlet? + +Take a look at [this example implementation](https://github.com/apache/pulsar/blob/master/tests/docker-images/java-test-plugins/src/main/java/org/apache/pulsar/tests/integration/plugins/RandomAdditionalServlet.java), or follow the steps below: + +1. Create a Maven project. + +2. Implement the `AdditionalServlet` or `AdditionalServletWithPulsarService` interface. + +3. Package your project into a NAR file. + +4. Configure the `broker.conf` file (or the `standalone.conf` file) and restart your broker. + +#### Step 1: Create a Maven project + +For how to create a Maven project, see [here](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html). + +#### Step 2: Implement the `AdditionalServlet` interface + +1. Add a dependency for `pulsar-broker` in the `pom.xml` file as displayed. Otherwise, you can not find the [`AdditionalServlet`](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/web/plugin/servlet/AdditionalServlet.java) interface. + + ```xml + + <dependency> + <groupId>org.apache.pulsar</groupId> + <artifactId>pulsar-broker</artifactId> + <version>${pulsar.version}</version> + <scope>provided</scope> + </dependency> + + ``` + +2. Implement the methods of the `AdditionalServlet` interface. + + - `loadConfig` allows you to configure your servlet by loading configuration properties from the `PulsarConfiguration`. + + - `getBasePath` defines the path your servlet will be loaded under. + + - `getServletHolder` returns the `ServletHolder` for this servlet. + + - `close` allows you to free up resources. + +3. Describe a NAR file. + + Create an `additional_servlet.yml` file in the `resources/META-INF/services` directory to describe a NAR file. + + ```conf + name: my-servlet + description: Describes my-servlet + additionalServletClass: org.my.package.MyServlet + + ``` + +#### Step 3: package your project into a NAR file + +1. Add the compiled plugin of the NAR file to your `pom.xml` file. + + ```xml + <build> + <finalName>${project.artifactId}</finalName> + <plugins> + <plugin> + <groupId>org.apache.nifi</groupId> + <artifactId>nifi-nar-maven-plugin</artifactId> + <version>1.2.0</version> + <extensions>true</extensions> + <configuration> + <finalName>${project.artifactId}-${project.version}</finalName> + </configuration> + <executions> + <execution> + <id>default-nar</id> + <phase>package</phase> + <goals> + <goal>nar</goal> + </goals> + </execution> + </executions> + </plugin> + </plugins> + </build> + ``` + +2. Generate a NAR file in the `target` directory. + + ```script + + mvn clean install + + ``` + +#### Step 4: configure and restart broker Review Comment: ```suggestion #### Step 4: Configure and restart broker ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
