Polish document and rearrange package for Quarkus and JAX-RS adapter

Signed-off-by: Eric Zhao <[email protected]>
jianghu-coding · Jun 17, 2020 · 07df281 · 07df281
1 parent d59d2d3
commit 07df281
Show file tree

Hide file tree

Showing 14 changed files with 84 additions and 88 deletions.
diff --git a/sentinel-adapter/sentinel-jax-rs-adapter/README.md b/sentinel-adapter/sentinel-jax-rs-adapter/README.md
@@ -1,6 +1,6 @@
-# Sentinel for jax-rs
+# Sentinel adapter for JAX-RS
 
-Sentinel provides filter integration to enable flow control for web requests.
+Sentinel provides integration to enable fault-tolerance and flow control for JAX-RS web requests.
 Add the following dependency in `pom.xml` (if you are using Maven):
 
 ```xml
@@ -13,7 +13,7 @@ Add the following dependency in `pom.xml` (if you are using Maven):
 
 ## SentinelJaxRsProviderFilter
 
-the `SentinelJaxRsProviderFilter` is auto activated in pure jax-rs application.
+The `SentinelJaxRsProviderFilter` is auto activated in pure JAX-RS application.
 
 For Spring web applications you can configure with Spring bean:
 
@@ -30,50 +30,54 @@ public class FilterConfig {
 
 ## DefaultExceptionMapper
 
-Sentinel provides DefaultExceptionMapper to map Throwable to Response(with Status.INTERNAL_SERVER_ERROR), in order to let SentinelJaxRsProviderFilter to be called and exit the sentinel entry.
+Sentinel provides DefaultExceptionMapper to map Throwable to Response (with Status.INTERNAL_SERVER_ERROR),
+in order to let SentinelJaxRsProviderFilter to be called and exit the Sentinel entry.
 
-according to `3.3.4 Exceptions` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf):
->Checked exceptions and throwables that have not been mapped and cannot be thrown directly MUSTbe wrapped in a container-specific exception that is then thrown and allowed to propagate to the un-derlying container.
+According to `3.3.4 Exceptions` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf):
 
-if WebApplicationException or its subclasses is thrown, there are automated converted to Response and can enter response filter.
+> Checked exceptions and throwables that have not been mapped and cannot be thrown directly MUST be wrapped in a container-specific exception that is then thrown and allowed to propagate to the underlying container.
 
-if throw exception which is not WebApplicationException or its subclass, and not matched by custom exception mapper, then the response filter cannot be called. for this case, I thank a default exception mapper maybe introduced.
+If WebApplicationException or its subclasses are thrown, they'll be automatically converted to `Response` and can enter response filter.
+If other kind of exceptions were thrown, and not matched by custom exception mapper, then the response filter cannot be called.
+For this case, a default exception mapper maybe introduced.
 
-according to `4.4 Exception Mapping Providers` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf):
->When choosing an exception mapping provider to map an exception,  an implementation MUST use theprovider whose generic type is the nearest superclass of the exception.  If two or more exception providers are applicable, the one with the highest priority MUST be chosen as described in Section 4.1.3.
+According to `4.4 Exception Mapping Providers` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf):
 
-if user also provide custom exception mapper of `Throwable`, then user has the responsibility to convert it to response and then the response filter can be called.
+> When choosing an exception mapping provider to map an exception,  an implementation MUST use the provider whose generic type is the nearest superclass of the exception.  If two or more exception providers are applicable, the one with the highest priority MUST be chosen as described in Section 4.1.3.
 
-as describe in `6.7.1 exceptions` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf):
->A response mapped from an exception MUST be processed using the ContainerResponsefilter chain and theWriteTointerceptor chain (if an entity is present in the mapped response).
+If user also provides customized exception mapper of `Throwable`, then user has the responsibility to convert it to response and then the response filter can be called.
+
+As describe in `6.7.1 exceptions` of [jaxrs-2_1-final-spec](https://download.oracle.com/otn-pub/jcp/jaxrs-2_1-final-eval-spec/jaxrs-2_1-final-spec.pdf):
+
+> A response mapped from an exception MUST be processed using the ContainerResponse filter chain and the WriteTo interceptor chain (if an entity is present in the mapped response).
 
 ## SentinelJaxRsClientTemplate
 
 For jax-rs client, we provide `SentinelJaxRsClientTemplate` you can use it like this:
 
 ```
-        Response response = SentinelJaxRsClientTemplate.execute(resourceName, new Supplier<Response>() {
-            @Override
-            public Response get() {
-                return client.target(host).path(url).request()
-                        .get();
-            }
-        });
+Response response = SentinelJaxRsClientTemplate.execute(resourceName, new Supplier<Response>() {
+    @Override
+    public Response get() {
+        return client.target(host).path(url).request()
+                .get();
+    }
+});
 ```
 
 or executeAsync like this:
 
 ```
-        Future<Response> future = SentinelJaxRsClientTemplate.executeAsync(resourceName, new Supplier<Future<Response>>() {
-            @Override
-            public Future<Response> get() {
-                return client.target(host).path(url).request()
-                        .async()
-                        .get();
-            }
-        });
+Future<Response> future = SentinelJaxRsClientTemplate.executeAsync(resourceName, new Supplier<Future<Response>>() {
+    @Override
+    public Future<Response> get() {
+        return client.target(host).path(url).request()
+                .async()
+                .get();
+    }
+});
 ```
 
-When a request is blocked, Sentinel jax-rs filter will return Response with status of TOO_MANY_REQUESTS indicating the request is rejected.
+When a request is blocked, Sentinel JAX-RS filter will return Response with status of `TOO_MANY_REQUESTS` indicating the request is rejected.
 
 You can customize it by implement your own `SentinelJaxRsFallback` and register to `SentinelJaxRsConfig`.
diff --git a/sentinel-adapter/sentinel-quarkus-adapter/README.md b/sentinel-adapter/sentinel-quarkus-adapter/README.md
@@ -1,8 +1,10 @@
-# sentinel quarkus adapter
+# Sentinel Quarkus Adapter
 
-sentinel quarkus adapter provides `sentinel-annotation-quarkus-adapter` and `sentinel-jax-rs-quarkus-adapter` to adapt `sentinel-annotation-cdi-interceptor` and `sentinel-jax-rs-adapter` for quarkus
+Sentinel provides `sentinel-annotation-quarkus-adapter` and `sentinel-jax-rs-quarkus-adapter` to
+adapt [sentinel-annotation-cdi-interceptor](https://github.com/alibaba/Sentinel/tree/master/sentinel-extension/sentiel-annotation-cdi-interceptor)
+and [sentinel-jax-rs-adapter](https://github.com/alibaba/Sentinel/tree/master/sentinel-adapter/sentinel-jax-rs-adapter) for Quarkus.
 
-sentinel quarkus adapter also provides `sentinel-native-image-quarkus-adapter` to support running sentinel with quarkus in native image mode.
+The integration module also provides `sentinel-native-image-quarkus-adapter` to support running Sentinel with Quarkus in native image mode.
 
 To use sentinel-jax-rs-quarkus-adapter, you can simply add the following dependency to your `pom.xml`:
 
@@ -24,30 +26,16 @@ To use sentinel-annotation-quarkus-adapter, you can simply add the following dep
 </dependency>
 ```
 
-if your quarkus application want to use both `sentinel-annotation-quarkus-adapter` and `sentinel-jax-rs-quarkus-adapter` , then add these two dependency together to your `pom.xml`:
-
-```xml
-<dependency>
-    <groupId>com.alibaba.csp</groupId>
-    <artifactId>sentinel-jax-rs-quarkus-adapter</artifactId>
-    <version>x.y.z</version>
-</dependency>
-<dependency>
-    <groupId>com.alibaba.csp</groupId>
-    <artifactId>sentinel-annotation-quarkus-adapter</artifactId>
-    <version>x.y.z</version>
-</dependency>
-```
-
-when quarkus application started, you can see the enabled feature like:
+When Quarkus application started, you can see the enabled feature like:
 
 ```
 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, resteasy, sentinel-annotation, sentinel-jax-rs]
 ```
 
-## for quarkus native image
+## For Quarkus native image
 
-if you want to make sentinel with quarkus running in native image mode, you should add the following dependency to your `pom.xml`:
+If you want to integrate Quarkus with Sentinel while running in native image mode,
+you should add the following dependency to your `pom.xml`:
 
 ```xml
 <dependency>
@@ -57,30 +45,28 @@ if you want to make sentinel with quarkus running in native image mode, you shou
 </dependency>
 ```
 
-and then add `--allow-incomplete-classpath` to `quarkus.native.additional-build-args`.
-
-if you use `sentinel-jax-rs-quarkus-adapter` you should set `quarkus.native.auto-service-loader-registration` to true.
+And then add `--allow-incomplete-classpath` to `quarkus.native.additional-build-args`.
 
-you can refer to `sentinel-demo-quarkus`'s `pom.xml` for more details.
+If you're using `sentinel-jax-rs-quarkus-adapter`, you'll need to set `quarkus.native.auto-service-loader-registration` to true.
 
-when quarkus application started, you can see the enabled feature like:
+When Quarkus application started, you can see the enabled feature like:
 
 ```
 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy, sentinel-annotation, sentinel-jax-rs, sentinel-native-image]
 ```
 
-### notes for limitations
+For more details you may refer to the `pom.xml` of [sentinel-demo-quarkus](https://github.com/alibaba/Sentinel/tree/master/sentinel-demo/sentinel-demo-quarkus).
 
-`sentinel-native-image-quarkus-adapter` currently rely on `sentinel-logging-slf4j` to make sentinel run in native image mode easily, because `quarkus-core` provides `Target_org_slf4j_LoggerFactory` to substitue `getLogger` method.
+### Limitations
 
-currently `sentinel-transport-simple-http` can work in native image mode, while `sentinel-transport-netty-http` cannot work in native image mode without extra config or substitutions.
+`sentinel-native-image-quarkus-adapter` currently relies on `sentinel-logging-slf4j` to help Sentinel
+run in native image mode easily, because `quarkus-core` provides `Target_org_slf4j_LoggerFactory` to substitute `getLogger` method.
 
-## references for build native image or AOT
+Currently `sentinel-transport-simple-http` can work in native image mode, while `sentinel-transport-netty-http` cannot work in native image mode without extra config or substitutions.
 
-- [Quarkus - Tips for writing native applications](https://quarkus.io/guides/writing-native-applications-tips)
+## References for build native image or AOT
 
+- [Quarkus - Tips for writing native applications](https://quarkus.io/guides/writing-native-applications-tips)
 - [Quarkus - Class Loading Reference](https://quarkus.io/guides/class-loading-reference)
-
-- [substratevm LIMITATIONS](https://github.com/oracle/graal/blob/master/substratevm/LIMITATIONS.md)
-
+- [SubstrateVM LIMITATIONS](https://github.com/oracle/graal/blob/master/substratevm/LIMITATIONS.md)
 - [Accessing resources in Substrate VM images](https://github.com/oracle/graal/blob/master/substratevm/RESOURCES.md)
diff --git a/...nelAnnotationQuarkusAdapterProcessor.java → ...nelAnnotationQuarkusAdapterProcessor.java b/...nelAnnotationQuarkusAdapterProcessor.java → ...nelAnnotationQuarkusAdapterProcessor.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.annotation.quarkus.adapter.deployment;
+package com.alibaba.csp.sentinel.adapter.quarkus.annotation.deployment;
 
 import com.alibaba.csp.sentinel.annotation.cdi.interceptor.SentinelResourceInterceptor;
 import io.quarkus.arc.deployment.AdditionalBeanBuildItem;

diff --git a/...uarkus/adapter/deployment/FooService.java → ...kus/annotation/deployment/FooService.java b/...uarkus/adapter/deployment/FooService.java → ...kus/annotation/deployment/FooService.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.annotation.quarkus.adapter.deployment;
+package com.alibaba.csp.sentinel.adapter.quarkus.annotation.deployment;
 import com.alibaba.csp.sentinel.annotation.cdi.interceptor.SentinelResourceBinding;
 import com.alibaba.csp.sentinel.slots.block.BlockException;
 

diff --git a/...n/quarkus/adapter/deployment/FooUtil.java → ...uarkus/annotation/deployment/FooUtil.java b/...n/quarkus/adapter/deployment/FooUtil.java → ...uarkus/annotation/deployment/FooUtil.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.annotation.quarkus.adapter.deployment;
+package com.alibaba.csp.sentinel.adapter.quarkus.annotation.deployment;
 
 import com.alibaba.csp.sentinel.slots.block.BlockException;
 

diff --git a/...SentinelAnnotationQuarkusAdapterTest.java → ...SentinelAnnotationQuarkusAdapterTest.java b/...SentinelAnnotationQuarkusAdapterTest.java → ...SentinelAnnotationQuarkusAdapterTest.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.annotation.quarkus.adapter.deployment;
+package com.alibaba.csp.sentinel.adapter.quarkus.annotation.deployment;
 
 import com.alibaba.csp.sentinel.node.ClusterNode;
 import com.alibaba.csp.sentinel.slots.block.flow.FlowRule;

diff --git a/...nel-annotation-quarkus-adapter-runtime/src/main/resources/META-INF/quarkus-extension.yaml b/...nel-annotation-quarkus-adapter-runtime/src/main/resources/META-INF/quarkus-extension.yaml
@@ -1,11 +1,13 @@
 ---
-name: "sentinel annotation extension"
+name: "Sentinel annotation CDI extension"
 metadata:
   keywords:
     - "sentinel"
-    - "rate limit"
-    - "circuit breaker"
+    - "rate-limiting"
+    - "resiliency"
+    - "circuit-breaker"
+    - "fault-tolerance"
   categories:
-    - "rate limit"
-    - "circuit breaker"
+    - "fault-tolerance"
+    - "cloud"
   status: "preview"
diff --git a/...SentinelJaxRsQuarkusAdapterProcessor.java → ...SentinelJaxRsQuarkusAdapterProcessor.java b/...SentinelJaxRsQuarkusAdapterProcessor.java → ...SentinelJaxRsQuarkusAdapterProcessor.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.jaxrs.quarkus.adapter.deployment;
+package com.alibaba.csp.sentinel.adapter.quarkus.jaxrs.deployment;
 
 import io.quarkus.deployment.annotations.BuildProducer;
 import io.quarkus.deployment.annotations.BuildStep;

diff --git a/...ment/SentinelJaxRsQuarkusAdapterTest.java → ...ment/SentinelJaxRsQuarkusAdapterTest.java b/...ment/SentinelJaxRsQuarkusAdapterTest.java → ...ment/SentinelJaxRsQuarkusAdapterTest.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.jaxrs.quarkus.adapter.deployment;
+package com.alibaba.csp.sentinel.adapter.quarkus.jaxrs.deployment;
 
 import com.alibaba.csp.sentinel.Constants;
 import com.alibaba.csp.sentinel.adapter.jaxrs.config.SentinelJaxRsConfig;

diff --git a/...rkus/adapter/deployment/TestResource.java → ...uarkus/jaxrs/deployment/TestResource.java b/...rkus/adapter/deployment/TestResource.java → ...uarkus/jaxrs/deployment/TestResource.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.jaxrs.quarkus.adapter.deployment;
+package com.alibaba.csp.sentinel.adapter.quarkus.jaxrs.deployment;
 
 
 import javax.ws.rs.*;

diff --git a/...entinel-jax-rs-quarkus-adapter-runtime/src/main/resources/META-INF/quarkus-extension.yaml b/...entinel-jax-rs-quarkus-adapter-runtime/src/main/resources/META-INF/quarkus-extension.yaml
@@ -1,11 +1,14 @@
 ---
-name: "sentinel jax rs extension"
+name: "Sentinel extension for JAX-RS"
 metadata:
   keywords:
-    - "resteasy"
-    - "jaxrs"
     - "sentinel"
+    - "rate-limiting"
+    - "resiliency"
+    - "circuit-breaker"
+    - "fault-tolerance"
+    - "jax-rs"
   categories:
-    - "web"
-    - "circuit breaker"
+    - "fault-tolerance"
+    - "cloud"
   status: "preview"
diff --git a/...veimage/SentinelNativeImageProcessor.java → ...veimage/SentinelNativeImageProcessor.java b/...veimage/SentinelNativeImageProcessor.java → ...veimage/SentinelNativeImageProcessor.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.nativeimage;
+package com.alibaba.csp.sentinel.adapter.quarkus.nativeimage;
 
 import com.alibaba.csp.sentinel.slots.DefaultSlotChainBuilder;
 import io.quarkus.deployment.annotations.BuildProducer;

diff --git a/...entinel/nativeimage/SentinelRecorder.java → ...quarkus/nativeimage/SentinelRecorder.java b/...entinel/nativeimage/SentinelRecorder.java → ...quarkus/nativeimage/SentinelRecorder.java
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.alibaba.csp.sentinel.nativeimage;
+package com.alibaba.csp.sentinel.adapter.quarkus.nativeimage;
 
 import com.alibaba.csp.sentinel.command.vo.NodeVo;
 import com.alibaba.csp.sentinel.slots.block.authority.AuthorityRule;

diff --git a/...l-native-image-quarkus-adapter-runtime/src/main/resources/META-INF/quarkus-extension.yaml b/...l-native-image-quarkus-adapter-runtime/src/main/resources/META-INF/quarkus-extension.yaml
@@ -1,12 +1,13 @@
 ---
-name: "sentinel native image extension"
+name: "Sentinel native image extension"
 metadata:
   keywords:
     - "sentinel"
-    - "rate limit"
-    - "circuit breaker"
-    - "native image"
+    - "rate-limiting"
+    - "circuit-breaker"
+    - "native-image"
+    - "fault-tolerance"
   categories:
-    - "rate limit"
-    - "circuit breaker"
+    - "cloud"
+    - "fault-tolerance"
   status: "preview"