update docs and readme

README.md

@@ -78,6 +78,24 @@ public DefaultSurenessConfig surenessConfig() {
 }
 ```
 
+#### Load Auth Config 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   
+
+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 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)   
+
+
 #### Add an Interceptor Intercepting All Requests  
 
 The essence of `sureness` is to intercept all rest requests for authenticating and Authorizing.     
@@ -114,23 +132,6 @@ try {
 
 Detail sureness auth exception see: [Default Sureness Auth Exception](docs/default-exception.md)   
 
-#### Load Auth Config 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   
-
-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 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)   
-
 **Have Fun**      
 
 ## Advanced Use  

README_CN.md

@@ -87,6 +87,21 @@ public DefaultSurenessConfig surenessConfig() {
 }
 ```
 
+#### 配置权限账户数据源      
+
+`sureness`认证鉴权，当然也需要我们提供自己的账户数据，角色权限数据等，这些数据可能来自文本，关系数据库，非关系数据库，注解等。  
+我们提供了数据源接口：`SurenessAccountProvider` - 账户数据接口, `PathTreeProvider` - 资源权限数据接口，用户可以实现此接口实现自定义数据源。  
+
+当前我们也提供文本形式的数据源实现 `DocumentResourceDefaultProvider` 和 注解形式的资源权限数据源实现 `AnnotationLoader`。  
+如果是使用了[默认sureness配置-DefaultSurenessConfig](#使用默认配置来配置sureness),其配置的是文本数据源，用户可以直接通过修改`sureness.yml`文件来配置数据。    
+
+文本数据源`sureness.yml`配置使用方式详见文档 [默认文本数据源](docs/cn/default-datasource.md)   
+注解形式的资源权限数据源配置使用方式详见文档 [注解资源权限数据源](docs/cn/annotation-datasource.md)    
+
+我们提供了使用代码`DEMO`：  
+默认文本数据源具体实现，请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
+若权限配置数据来自数据库，请参考[使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)  
+
 #### 添加过滤器拦截所有请求    
 
 `sureness`的本质就拦截所有rest请求对其认证鉴权判断。  
@@ -123,21 +138,6 @@ try {
 
 异常详见 [默认异常类型](docs/cn/default-exception.md)  
 
-#### 配置权限账户数据源      
-
-`sureness`认证鉴权，当然也需要我们提供自己的账户数据，角色权限数据等，这些数据可能来自文本，关系数据库，非关系数据库，注解等。  
-我们提供了数据源接口：`SurenessAccountProvider` - 账户数据接口, `PathTreeProvider` - 资源权限数据接口，用户可以实现此接口实现自定义数据源。  
-
-当前我们也提供文本形式的数据源实现 `DocumentResourceDefaultProvider` 和 注解形式的资源权限数据源实现 `AnnotationLoader`。  
-如果是使用了[默认sureness配置-DefaultSurenessConfig](#使用默认配置来配置sureness),其配置的是文本数据源，用户可以直接通过修改`sureness.yml`文件来配置数据。    
-
-文本数据源`sureness.yml`配置使用方式详见文档 [默认文本数据源](docs/cn/default-datasource.md)   
-注解形式的资源权限数据源配置使用方式详见文档 [注解资源权限数据源](docs/cn/annotation-datasource.md)    
-
-我们提供了使用代码`DEMO`：  
-默认文本数据源具体实现，请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
-若权限配置数据来自数据库，请参考[使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)  
-
 **HAVE FUN**  
 
 ## 进阶扩展  

docs/cn/quickstart.md

 ## 快速开始  
 
-##### <font color="red">使用前一些约定</font>  
+#### <font color="red">使用前一些约定</font>  
 
-- `sureness`尽量简洁,基于`rbac`,但只有(角色-资源)的映射,没有(权限)动作映射
+- `sureness`尽量简洁,基于`rbac`,只有(角色-资源)的映射,没有(权限)动作映射，即 用户-角色-资源  
 - 我们将`restful api`请求视作一个资源,资源格式为: `requestUri===httpMethod`  
   即请求的路径加上其请求方式(`post,get,put,delete...`)作为一个整体被视作一个资源  
   `eg: /api/v2/book===get` `get`方式请求`/api/v2/book`接口数据     
@@ -10,9 +10,9 @@
 
 资源路径匹配详见 [url路径匹配](cn/path-match.md)  
 
-##### 项目中加入sureness  
+#### 项目中加入sureness  
 
-1. 项目使用`maven`构建,加入`maven`坐标  
+项目使用`maven`或`gradle`构建,加入坐标    
 ```
 <dependency>
     <groupId>com.usthe.sureness</groupId>
@@ -20,60 +20,69 @@
     <version>0.4</version>
 </dependency>
 ```
-
-2. 项目使用`gradle`构建,`gradle`坐标  
 ```
 compile group: 'com.usthe.sureness', name: 'sureness-core', version: '0.4'
 ```
 
-3. 项目为普通工程,加入`sureness-core.jar`依赖  
+#### 使用默认配置来配置sureness    
+默认配置使用了文件数据源sureness.yml作为账户权限数据源  
+默认配置支持了jwt, basic auth, digest auth认证  
 ```
-在 mvnrepository 下载jar  
-https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core
+@Bean
+public DefaultSurenessConfig surenessConfig() {
+    return new DefaultSurenessConfig();
+}
 ```
 
-##### 添加拦截所有请求的过滤器入口  
+#### 配置权限账户数据源      
 
-入口拦截器器实现一般可以是 `filter or spring interceptor`  
-在拦截器加入sureness的安全过滤器，如下:  
-入口,一般放在拦截所有请求的`filter`:  
-  
-```
-SurenessSecurityManager.getInstance().checkIn(servletRequest)
-```
+`sureness`认证鉴权，当然也需要我们提供自己的账户数据，角色权限数据等，这些数据可能来自文本，关系数据库，非关系数据库，注解等。  
+我们提供了数据源接口：`SurenessAccountProvider` - 账户数据接口, `PathTreeProvider` - 资源权限数据接口，用户可以实现此接口实现自定义数据源。  
+
+当前我们也提供文本形式的数据源实现 `DocumentResourceDefaultProvider` 和 注解形式的资源权限数据源实现 `AnnotationLoader`。  
+如果是使用了[默认sureness配置-DefaultSurenessConfig](#使用默认配置来配置sureness),其配置的是文本数据源，用户可以直接通过修改`sureness.yml`文件来配置数据。    
+
+文本数据源`sureness.yml`配置使用方式详见文档 [默认文本数据源](cn/default-datasource.md)   
+注解形式的资源权限数据源配置使用方式详见文档 [注解资源权限数据源](cn/annotation-datasource.md)    
 
-##### 实现相关异常处理  
+我们提供了使用代码`DEMO`：  
+默认文本数据源具体实现，请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
+若权限配置数据来自数据库，请参考[使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)  
 
-`sureness`使用异常处理流程,我们需要对`checkIn`抛出的异常做自定义处理,  
-安全过滤器,认证鉴权成功直接通过,失败抛出特定异常,捕获异常,如下: 
+#### 添加过滤器拦截所有请求    
+
+`sureness`的本质就拦截所有rest请求对其认证鉴权判断。  
+入口拦截器器实现一般可以是 `filter or spring interceptor`  
+在拦截器中加入`sureness`的安全过滤器，如下:  
 
 ```
-        try {
-            SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);
-        } catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {
-            // 账户创建相关异常 
-        } catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {
-            // 账户禁用相关异常
-        } catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {
-            // 认证失败相关异常
-        } catch (UnauthorizedException e5) {
-            // 鉴权失败相关异常
-        } catch (RuntimeException e) {
-            // 其他自定义异常
-        }
+SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest)
 ```
-异常详见 [默认异常](cn/default-exception.md)  
 
-##### 加载配置数据  
+#### 实现认证鉴权相关异常处理流程      
+
+`sureness`使用异常处理流程：  
+1. 若认证鉴权成功,`checkIn`会返回包含用户信息的`SubjectSum`对象  
+2. 若中间认证鉴权失败，`checkIn`会抛出不同类型的认证鉴权异常,用户需根据这些异常来继续后面的流程(返回相应的请求响应)
 
-`sureness`认证鉴权当然也需要我们自己的配置数据:账户数据，角色权限数据等  
-这些配置数据可能来自文本，关系数据库，非关系数据库  
-我们提供了配置数据接口`SurenessAccountProvider`, `PathTreeProvider`, 用户可以实现此接口实现自定义配置数据源  
-当前我们也提供默认文本形式的配置数据实现 `DocumentResourceDefaultProvider`, 用户可以配置`sureness.yml`来配置数据  
+这里我们就需要对`checkIn`抛出的异常做自定义处理,认证鉴权成功直接通过,失败抛出特定异常进行处理,如下:  
 
-默认文本数据源配置详见 [默认数据源](cn/default-datasource.md)  
+```
+try {
+    SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);
+} catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {
+    // 账户创建相关异常 
+} catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {
+    // 账户禁用相关异常
+} catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {
+    // 认证失败相关异常
+} catch (UnauthorizedException e5) {
+    // 鉴权失败相关异常
+} catch (SurenessAuthenticationException | SurenessAuthorizationException e) {
+    // 其他自定义异常
+}
+```
 
-我们提供了默认文本数据源使用`DEMO`，默认文本数据源具体实现，请参考 [使用sureness10分钟项目集成案例](cn/sample-bootstrap.md)     
-若权限配置数据来自数据库,请参考 [使用sureness30分钟项目集成案例](cn/sample-tom.md)   
+异常详见 [默认异常类型](cn/default-exception.md)  
 
 **HAVE FUN**  
\ No newline at end of file

docs/quickstart.md

 ## 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`.   
@@ -10,9 +10,9 @@
 
 Resource path matching see: [Uri Match](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>
@@ -20,55 +20,74 @@ Resource path matching see: [Uri Match](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  
-```
-download this jar at mvnrepository  
-https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core
-```
 
-##### Add an Interceptor Intercepting All Requests  
+#### Use the default configuration to configure sureness  
 
-The interceptor can be a filter or a spring interceptor.  
-The interceptor intercepts all request to check them.  
+The default configuration -`DefaultSurenessConfig` uses the document datasource sureness.yml as the auth datasource.  
+It supports jwt, basic auth, digest auth authentication.  
 ```
-SurenessSecurityManager.getInstance().checkIn(servletRequest)
+@Bean
+public DefaultSurenessConfig surenessConfig() {
+    return new DefaultSurenessConfig();
+}
 ```
 
-##### Implement Exception Flow When Exception Throw  
-Authentication passed directly, failure throw exception, catch exception and do something:   
+#### Load Auth Config 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   
+
+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 Document DataSource](default-datasource.md)   
+Annotation DataSource Config Detail, see: [Annotation DataSource](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)   
+
+
+#### Add an Interceptor Intercepting All Requests  
+
+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.  
 ```
-        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
-        }
+SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest)
 ```
 
-Detail sureness exception see: [Default Sureness Exception](default-exception.md)  
+#### Implement Auth Exception Handling Process    
 
-### Load Config DataSource   
+`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)  
 
-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. 
+Here we need to customize the exceptions thrown by `checkIn`, 
+passed directly when auth success, catch exception when auth failure and do something:    
 
-Default Document DataSource Config - sureness.yml, see: [Default DataSource](default-datasource.md)  
+```
+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
+}
+```
 
-If the configuration resource data comes from text, please refer to  [10 Minute Tutorial's Program--sample-bootstrap](sample-bootstrap.md)       
-If the configuration resource data comes from dataBase, please refer to  [30 Minute Tutorial's Program--sample-tom](sample-tom.md)     
+Detail sureness auth exception see: [Default Sureness Auth Exception](default-exception.md)   
 
-**Have Fun**          
\ No newline at end of file
+**Have Fun**      
+ 
\ No newline at end of file