update en docs and readme

README.md

@@ -43,7 +43,7 @@
 
 ## Quick Start 
 
-##### <font color="red">Some Conventions</font>  
+#### <font color="red">Some Conventions</font>  
 
 - Based RBAC, only has role-resource, no permission action    
 - We treat restful requests as a resource, resource format like `requestUri===httpMethod`.   
@@ -53,9 +53,9 @@
 
 Resource path matching see: [Uri Match](docs/path-match.md)  
 
-##### Add sureness In Project  
+#### Add sureness In Your Project  
 
-1. When use maven build project, add maven coordinate  
+When use maven or gradle build project, add coordinate  
 ```
 <dependency>
     <groupId>com.usthe.sureness</groupId>
@@ -63,53 +63,70 @@ Resource path matching see: [Uri Match](docs/path-match.md)
     <version>0.4</version>
 </dependency>
 ```
-2. When use gradle build project, add gradle coordinate  
 ```
 compile group: 'com.usthe.sureness', name: 'sureness-core', version: '0.4'
 ```
-3. When not java build project, add sureness-core.jar to classPath  
+
+#### Use the default configuration to configure sureness  
+
+The default configuration -`DefaultSurenessConfig` uses the document datasource sureness.yml as the auth datasource.  
+It supports jwt, basic auth, digest auth authentication.  
 ```
-download this jar at mvnrepository  
-https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core
+@Bean
+public DefaultSurenessConfig surenessConfig() {
+    return new DefaultSurenessConfig();
+}
 ```
 
-##### Add an Interceptor Intercepting All Requests  
+#### Add an Interceptor Intercepting All Requests  
 
-The interceptor can be a filter or a spring interceptor.  
-The interceptor intercepts all request to check them.  
+The essence of `sureness` is to intercept all rest requests for authenticating and Authorizing.     
+The interceptor can be a filter or a spring interceptor, it intercepts all request to check them.  
 ```
-SurenessSecurityManager.getInstance().checkIn(servletRequest)
+SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest)
 ```
 
-##### Implement Exception Flow When Exception Throw  
-Authentication passed directly, failure throw exception, catch exception and do something:   
+#### Implement Auth Exception Handling Process    
+
+`sureness` uses exception handling process:  
+1. If auth success, method - `checkIn` will return a `SubjectSum` object containing user information.  
+2. If auth failure, method - `checkIn` will throw different types of auth exceptions, 
+and users need to continue the subsequent process based on these exceptions.(like return the request response)  
+
+Here we need to customize the exceptions thrown by `checkIn`, 
+passed directly when auth success, catch exception when auth failure and do something:    
 
 ```
-        try {
-            SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);
-        } catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {
-            // Create subject error related execption 
-        } catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {
-            // Account disable related exception
-        } catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {
-            // Authentication failure related exception
-        } catch (UnauthorizedException e5) {
-            // Authorization failure related exception
-        } catch (RuntimeException e) {
-            // other sureness exception
-        }
+try {
+    SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);
+} catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {
+    // Create subject error related execption 
+} catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {
+    // Account disable related exception
+} catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {
+    // Authentication failure related exception
+} catch (UnauthorizedException e5) {
+    // Authorization failure related exception
+} catch (SurenessAuthenticationException | SurenessAuthorizationException e) {
+    // other sureness exception
+}
 ```
 
-Detail sureness exception see: [Default Sureness Exception](docs/default-exception.md)  
+Detail sureness auth exception see: [Default Sureness Auth Exception](docs/default-exception.md)   
 
-### Load Config DataSource   
+### Load Auth Config DataSource   
 
 Sureness need dataSource to authenticate and authorize, eg: role data, user data etc.  
-The dataSource can load from txt, dataBase or no dataBase etc.
-We provide interfaces `SurenessAccountProvider`, `PathTreeProvider` for user implement to load data from the dataSource where they want.
-Also, we provide default dataSource implement which load dataSource from txt(sureness.yml), user can defined their data in sureness.yml. 
+The dataSource can load from txt, dataBase, no dataBase or annotation etc.  
+We provide interfaces `SurenessAccountProvider`, `PathTreeProvider` for user implement to load data from the dataSource where they want.  
+`SurenessAccountProvider` - Account datasource provider interface  
+`PathTreeProvider` - Resource uri-role datasource provider interface   
+
+We provide default dataSource implement which load dataSource from txt(sureness.yml), user can defined their data in sureness.yml.   
+We also provider dataSource implement which load dataSource form annotation - `AnnotationLoader`.   
 
-Default Document DataSource Config - sureness.yml, see: [Default DataSource](docs/default-datasource.md)  
+Default Document DataSource Config - sureness.yml, see: [Default Document DataSource](docs/default-datasource.md)   
+Annotation DataSource Config Detail, see: [Annotation DataSource](docs/annotation-datasource.md)  
 
 If the configuration resource data comes from text, please refer to  [10 Minute Tutorial's Program--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
 If the configuration resource data comes from dataBase, please refer to  [30 Minute Tutorial's Program--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)   
@@ -118,7 +135,7 @@ If the configuration resource data comes from dataBase, please refer to  [30 Min
 
 ## Advanced Use  
 
-If know sureness Process flow, maybe know the extend point  
+If know sureness Process flow, maybe know these extend points    
 
 Sureness supports custom subject, custom subjectCreator, custom processor and more.  
 
@@ -154,7 +171,7 @@ Detail please refer to  [30 Minute Tutorial's Program--sample-tom](sample-tom)
 
 ## Contributing  
 
-Very welcome to Contribute this project, help sureness go further and better. If you have any questions or suggestions about the project code, please contact @tomsun28 directly.
+Very welcome to Contribute this project, go further and better with sureness. If you have any questions or suggestions about the project code, please contact @tomsun28 directly.  
 
 Components of Repository:  
 - [sureness's kernel code--sureness-core](core)  
@@ -163,10 +180,10 @@ Components of Repository:
 - [Sample projects using sureness in each framework(javalin,ktor,quarkus)--samples](samples)  
 
 
-##### Why Is High Performance  
+#### Why Is High Performance  
 
 ![pathRoleMatcher](docs/_images/PathRoleMatcher.svg)  
  
 
-### License  
+## License  
 [`Apache License, Version 2.0`](https://www.apache.org/licenses/LICENSE-2.0.html)
\ No newline at end of file

README_CN.md

@@ -101,7 +101,7 @@ SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletReques
 
 `sureness`使用异常处理流程：  
 1. 若认证鉴权成功,`checkIn`会返回包含用户信息的`SubjectSum`对象  
-2. 若中间认证鉴权失败，`checkIn`会抛出不同类型的认证鉴权异常,用户需根据这些异常来继续后面的流程(返回相应的请求相应)
+2. 若中间认证鉴权失败，`checkIn`会抛出不同类型的认证鉴权异常,用户需根据这些异常来继续后面的流程(返回相应的请求响应)
 
 这里我们就需要对`checkIn`抛出的异常做自定义处理,认证鉴权成功直接通过,失败抛出特定异常进行处理,如下:  
 

docs/_sidebar.md

@@ -2,9 +2,10 @@
   - [Introduce](README.md "introduce")
   - [Quick Start](quickstart.md "quick start greatest")  
   - [URI Match](path-match.md)  
-  - [Default Datasource](default-datasource.md)  
-  - [Default Auth](default-auth.md)
-  - [Default Exception](default-exception.md)  
+  - [Default Document Datasource](default-datasource.md)  
+  - [Annotation Datasource](annotation-datasource.md)  
+  - [Default Auth Types](default-auth.md)  
+  - [Default Auth Exception](default-exception.md)  
   
 - Advanced Extend
   - [Extend Point](extend-point.md)

docs/annotation-datasource.md

+## Annotation Auth DataSource   
+
+Sureness need dataSource to authenticate and authorize, eg: role data, user data etc.  
+The dataSource can load from txt, dataBase, no dataBase or annotation etc.  
+We provide interfaces `SurenessAccountProvider`, `PathTreeProvider` for user implement to load data from the dataSource where they want.  
+`SurenessAccountProvider` - Account datasource provider interface.   
+`PathTreeProvider` - Resource uri-role datasource provider interface.  
+
+The way of `sureness` to implement the annotation dataSource is not to judge the aop before calling the method, 
+but to scan the data in the annotation as the auth dataSource when startup, 
+which facilitates the unification of the process and the independence of the framework.    
+
+Here is an introduction to show how to use annotation config auth data.
+
+1. First of all, we need to configure the annotation dataSource as the auth dataSource in the sureness startup configuration.  
+
+```
+@Bean
+TreePathRoleMatcher pathRoleMatcher() {
+    // Instantiate the resource permission path matcher, which will match the required role information 
+    // according to the requested path and existing resource permission data.
+    DefaultPathRoleMatcher pathRoleMatcher = new DefaultPathRoleMatcher();
+    // Instantiate the resource permission data loader - `AnnotationLoader`, 
+    // which implements the PathTreeProvider interface.    
+    AnnotationLoader annotationLoaderProvider = new AnnotationLoader();
+    // Set the package path to be scanned by AnnotationLoader, which will scan the 
+    // @RequiresRoles, @WithoutAuth annotations on all class methods under the package path to obtain data.
+    annotationLoaderProvider.setScanPackages(Arrays.asList("com.usthe.sureness.sample.tom.controller"));
+    // Set the AnnotationLoader dataSource as the sureness auth dataSource. 
+    pathRoleMatcher.addPathTreeProvider(annotationLoaderProvider);
+    pathRoleMatcher.buildTree();
+    return pathRoleMatcher;
+}
+```
+
+2. Use annotations in the provided interface methods, eg:  
+```
+@RequiresRoles(roles = {"role1", "role2"}, mapping = "/resource", method = "post")  
+Means that the resource /resource===post requires role role1 or role2 to access
+```
+```
+@WithoutAuth(mapping = "/resource/*", method = "put")  
+Means that the resource /resource/*===put can be accessed by any request
+```
+
+3. Suggest    
+Although the annotation auth data is more convenient for us to develop, it is hard-coded in the code and cannot 
+dynamically modify the permission role configuration data. It is not very suitable for large projects.   
+`sureness` provides the function of loading multiple data sources at the same time, that is, 
+we can simultaneously use the annotation dataSource and database auth dataSource in the sureness configuration.   
+For the permission configuration that is not frequently modified, we can configure it to annotations, 
+and for other permission data that needs to be dynamically modified, we configure it in the database.   
\ No newline at end of file