RetrofitUrlManager (manager API)

java.lang.Object
- me.jessyan.retrofiturlmanager.RetrofitUrlManager

```
public class RetrofitUrlManager
extends java.lang.Object
```
================================================ RetrofitUrlManager 以简洁的 Api, 让 Retrofit 不仅支持多 BaseUrl 还可以在 App 运行时动态切换任意 BaseUrl, 在多 BaseUrl 场景下也不会影响到其他不需要切换的 BaseUrl
想要更深入的使用本框架必须要了解2个术语 pathSegments 和 PathSize "https://www.github.com/wiki/part?name=jess" 其中的 "/wiki" 和 "/part" 就是 pathSegment, PathSize 就是 pathSegment 的 Size 这个 Url 的 PathSize 就是 2, 可以粗略理解为域名后面跟了几个 "/" PathSize 就是几
本框架分为三种模式, 普通模式 (默认)、高级模式 (需要手动开启)、超级模式 (需要手动开启)
普通模式: 普通模式只能替换域名, 比如使用 "https:www.google.com" 作为 Retrofit 的 BaseUrl 可以被替换但是以 "https:www.google.com/api" 作为 BaseUrl 还是只能替换其中的域名 "https:www.google.com" 详细替换规则可以查看 DomainUrlParser
高级模式: 高级模式只能替换 startAdvancedModel(String) 中传入的 BaseUrl, 但可以替换拥有多个 pathSegments 的 BaseUrl 如 "https:www.google.com/api", 需要手动开启高级模式 startAdvancedModel(String) 详细替换规则可以查看 AdvancedUrlParser
超级模式: 详细替换规则可以查看 SuperUrlParser 超级模式属于高级模式的加强版, 优先级高于高级模式, 在高级模式中, 需要传入一个 BaseUrl (您传入 Retrofit 的 BaseUrl) 作为被替换的基准如这个传入的 BaseUrl 为 "https://www.github.com/wiki/part" (PathSize = 2), 那框架会将所有需要被替换的 Url 中的域名以及域名后面的前两个 pathSegments 使用您传入 putDomain(String, String) 方法的 Url 替换掉但如果突然有一小部分的 Url 只想将 "https://www.github.com/wiki" (PathSize = 1) 替换掉, 后面的 pathSegment '/part' 想被保留下来这时项目中就出现了多个 PathSize 不同的需要被替换的 BaseUrl
使用高级模式实现这种需求略显麻烦, 所以我创建了超级模式, 让每一个 Url 都可以随意指定不同的 BaseUrl (PathSize 自己定) 作为被替换的基准使 RetrofitUrlManager 可以从容应对各种复杂的需求
超级模式也需要手动开启, 但与高级模式不同的是, 开启超级模式并不需要调用 API, 只需要在 Url 中加入 IDENTIFICATION_PATH_SIZE + PathSize
至此三种模式替换 BaseUrl 的自由程度 (可扩展性) 排名, 从小到大依次是: 普通模式 (只能替换域名) < 高级模式 (只能替换 startAdvancedModel(String) 中传入的 BaseUrl) < 超级模式 (每个 Url 都可以随意指定可被替换的 BaseUrl, pathSize 随意变换)
三种模式在使用上的复杂程度排名, 从小到大依次是: 普通模式 (无需做过多配置) < 高级模式 (App 初始化时调用一次 startAdvancedModel(String) 即可) < 超级模式 (每个需要被替换 BaseUrl 的 Url 中都需要加入 IDENTIFICATION_PATH_SIZE + PathSize)
由此可见，自由度越强, 操作也越复杂, 所以可以根据自己的需求选择不同的模式, 并且也可以在需求变化时随意升级或降级这三种模式
Created by JessYan on 17/07/2017 14:29 Contact me Follow me ================================================

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`DOMAIN_NAME_HEADER`
`static java.lang.String`	`IDENTIFICATION_IGNORE` 如果在 Url 地址中加入此标识符, 框架将不会对此 Url 进行任何切换 BaseUrl 的操作
`static java.lang.String`	`IDENTIFICATION_PATH_SIZE` 如果在 Url 地址中加入此标识符, 意味着您想对此 Url 开启超级模式, 框架会将 '=' 后面的数字作为 PathSize, 来确认最终需要被超级模式替换的 BaseUrl

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clearAllDomain()` 清理所有 Domain(BaseUrl)
`int`	`domainSize()` 存放 Domain(BaseUrl) 的容器, 当前的大小
`okhttp3.HttpUrl`	`fetchDomain(java.lang.String domainName)` 取出对应 `domainName` 的 Url(BaseUrl)
`okhttp3.HttpUrl`	`getBaseUrl()` 获取 BaseUrl
`okhttp3.HttpUrl`	`getGlobalDomain()` 获取全局 BaseUrl
`static RetrofitUrlManager`	`getInstance()`
`int`	`getPathSize()` 获取 PathSegments 的总大小
`boolean`	`haveDomain(java.lang.String domainName)` 存放 Domain(BaseUrl) 的容器中是否存在这个 `domainName`
`boolean`	`isAdvancedModel()` 是否开启高级模式
`boolean`	`isRun()` 框架是否在运行
`okhttp3.Request`	`processRequest(okhttp3.Request request)` 对 `Request` 进行一些必要的加工, 执行切换 BaseUrl 的相关逻辑
`void`	`putDomain(java.lang.String domainName, java.lang.String domainUrl)` 存放 Domain(BaseUrl) 的映射关系
`void`	`registerUrlChangeListener(onUrlChangeListener listener)` 注册监听器(当 Url 的 BaseUrl 被切换时会被回调的监听器)
`void`	`removeDomain(java.lang.String domainName)` 移除某个 `domainName`
`void`	`removeGlobalDomain()` 移除全局 BaseUrl
`void`	`setDebug(boolean debug)` 开启 Debug 模式下可以打印日志
`void`	`setGlobalDomain(java.lang.String globalDomain)` 全局动态替换 BaseUrl, 优先级: Header中配置的 BaseUrl > 全局配置的 BaseUrl 除了作为备用的 BaseUrl, 当您项目中只有一个 BaseUrl, 但需要动态切换这种方式不用在每个接口方法上加入 Header, 就能实现动态切换 BaseUrl
`java.lang.String`	`setPathSizeOfUrl(java.lang.String url, int pathSize)` 将 url 地址和 pathSize 作为参数传入此方法, 并使用此方法返回的 Url 地址进行网络请求, 则会使此 Url 地址使用超级模式
`void`	`setRun(boolean run)` 控制框架是否运行, 在每个域名地址都已经确定, 不需要再动态更改时可设置为 `false`
`java.lang.String`	`setUrlNotChange(java.lang.String url)` 将 url 地址作为参数传入此方法, 并使用此方法返回的 Url 地址进行网络请求, 则会使此 Url 地址忽略掉本框架的所有更改效果
`void`	`setUrlParser(UrlParser parser)` 可自行实现 `UrlParser` 动态切换 Url 解析策略
`void`	`startAdvancedModel(okhttp3.HttpUrl baseUrl)` 开启高级模式, 高级模式可以替换拥有多个 pathSegments 的 BaseUrl, 如: https://www.github.com/wiki/part 高级模式的解析规则, 请看 `AdvancedUrlParser` 注意, 如果没有开启高级模式, 默认为普通默认, 只能替换域名, 如: https://www.github.com
`void`	`startAdvancedModel(java.lang.String baseUrl)` 开启高级模式, 高级模式可以替换拥有多个 pathSegments 的 BaseUrl, 如: https://www.github.com/wiki/part 高级模式的解析规则, 请看 `AdvancedUrlParser` 注意, 如果没有开启高级模式, 默认为普通默认, 只能替换域名, 如: https://www.github.com
`void`	`unregisterUrlChangeListener(onUrlChangeListener listener)` 注销监听器(当 Url 的 BaseUrl 被切换时会被回调的监听器)
`okhttp3.OkHttpClient.Builder`	`with(okhttp3.OkHttpClient.Builder builder)` 将 `OkHttpClient.Builder` 传入, 配置一些本框架需要的参数

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DOMAIN_NAME_HEADER
```
public static final java.lang.String DOMAIN_NAME_HEADER
```
    See Also:
    
    Constant Field Values
  - IDENTIFICATION_IGNORE
```
public static final java.lang.String IDENTIFICATION_IGNORE
```
    如果在 Url 地址中加入此标识符, 框架将不会对此 Url 进行任何切换 BaseUrl 的操作
    
    See Also:
    
    Constant Field Values
  - IDENTIFICATION_PATH_SIZE
```
public static final java.lang.String IDENTIFICATION_PATH_SIZE
```
    如果在 Url 地址中加入此标识符, 意味着您想对此 Url 开启超级模式, 框架会将 '=' 后面的数字作为 PathSize, 来确认最终需要被超级模式替换的 BaseUrl
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getInstance
```
public static final RetrofitUrlManager getInstance()
```
  - with
```
public okhttp3.OkHttpClient.Builder with(okhttp3.OkHttpClient.Builder builder)
```
    将 OkHttpClient.Builder 传入, 配置一些本框架需要的参数
    
    Parameters:
    
    builder - OkHttpClient.Builder
    
    Returns:
    
    OkHttpClient.Builder
  - processRequest
```
public okhttp3.Request processRequest(okhttp3.Request request)
```
    对 Request 进行一些必要的加工, 执行切换 BaseUrl 的相关逻辑
    
    Parameters:
    
    request - Request
    
    Returns:
    
    Request
  - isRun
```
public boolean isRun()
```
    框架是否在运行
    
    Returns:
    
    true 为正在运行, false 为未运行
  - setRun
```
public void setRun(boolean run)
```
    控制框架是否运行, 在每个域名地址都已经确定, 不需要再动态更改时可设置为 false
    
    Parameters:
    
    run - true 为正在运行, false 为未运行
  - setDebug
```
public void setDebug(boolean debug)
```
    开启 Debug 模式下可以打印日志
    
    Parameters:
    
    debug - true 开启 Debug 模式
  - startAdvancedModel
```
public void startAdvancedModel(java.lang.String baseUrl)
```
    开启高级模式, 高级模式可以替换拥有多个 pathSegments 的 BaseUrl, 如: https://www.github.com/wiki/part 高级模式的解析规则, 请看 AdvancedUrlParser 注意, 如果没有开启高级模式, 默认为普通默认, 只能替换域名, 如: https://www.github.com
    注意, 遇到这个坑, 请别怪框架!!! Retrofit 的 BaseUrl 含有可被覆盖 pathSegment 的规则: 举例: 您设置给 Retrofit 的 BaseUrl 是 "http://www.github.com/a/b/" 然后您在接口方法上给的注解是 @GET("/path"), 这时 Retrofit 生成的最终路径是 "http://www.github.com/path" "/a/b/" 被剪切掉了, 为什么? 因为您在 "path" 前面加上了 "/", "/" 会让 Retrofit 认为把您只想保留 BaseUrl 中的域名如果去掉 "/", @GET("path") 得到的最终路径才是 "http://www.github.com/a/b/path"
    所以如果在最终路径中, BaseUrl 的 "/a/b/" 因为您不熟悉规则而被剪切, 这时您应该在 startAdvancedModel(HttpUrl) 中传入被剪切的实际 BaseUrl "http://www.github.com", 而不是 http://www.github.com/a/b/, 否则框架会理解错误!
    
    Parameters:
    
    baseUrl - 您当时传入 Retrofit 的 BaseUrl
    
    See Also:
    
    AdvancedUrlParser
  - startAdvancedModel
```
public void startAdvancedModel(okhttp3.HttpUrl baseUrl)
```
    开启高级模式, 高级模式可以替换拥有多个 pathSegments 的 BaseUrl, 如: https://www.github.com/wiki/part 高级模式的解析规则, 请看 AdvancedUrlParser 注意, 如果没有开启高级模式, 默认为普通默认, 只能替换域名, 如: https://www.github.com
    注意, 遇到这个坑, 请别怪框架!!! Retrofit 的 BaseUrl 含有可被覆盖 pathSegment 的规则: 举例: 您设置给 Retrofit 的 BaseUrl 是 "http://www.github.com/a/b/" 然后您在接口方法上给的注解是 @GET("/path"), 这时 Retrofit 生成的最终路径是 "http://www.github.com/path" "/a/b/" 被剪切掉了, 为什么? 因为您在 "path" 前面加上了 "/", "/" 会让 Retrofit 认为把您只想保留 BaseUrl 中的域名如果去掉 "/", @GET("path") 得到的最终路径才是 "http://www.github.com/a/b/path"
    所以如果在最终路径中, BaseUrl 的 "/a/b/" 因为您不熟悉规则而被剪切, 这时您应该在 startAdvancedModel(HttpUrl) 中传入被剪切的实际 BaseUrl "http://www.github.com", 而不是 http://www.github.com/a/b/, 否则框架会理解错误!
    
    Parameters:
    
    baseUrl - 您当时传入 Retrofit 的 BaseUrl
    
    See Also:
    
    AdvancedUrlParser
  - getPathSize
```
public int getPathSize()
```
    获取 PathSegments 的总大小
    
    Returns:
    
    PathSegments 的 size
  - isAdvancedModel
```
public boolean isAdvancedModel()
```
    是否开启高级模式
    
    Returns:
    
    true 为开启, false 为未开启
  - getBaseUrl
```
public okhttp3.HttpUrl getBaseUrl()
```
    获取 BaseUrl
    
    Returns:
    
    baseUrl
  - setUrlNotChange
```
public java.lang.String setUrlNotChange(java.lang.String url)
```
    将 url 地址作为参数传入此方法, 并使用此方法返回的 Url 地址进行网络请求, 则会使此 Url 地址忽略掉本框架的所有更改效果
    使用场景: 比如当您使用了 setGlobalDomain(String url) 配置了全局 BaseUrl 后, 想请求一个与全局 BaseUrl 不同的第三方服务商地址获取图片
    
    Parameters:
    
    url - Url 地址
    
    Returns:
    
    处理后的 Url 地址
  - setPathSizeOfUrl
```
public java.lang.String setPathSizeOfUrl(java.lang.String url,
                                         int pathSize)
```
    将 url 地址和 pathSize 作为参数传入此方法, 并使用此方法返回的 Url 地址进行网络请求, 则会使此 Url 地址使用超级模式
    什么是超级模式? 请看 RetrofitUrlManager 上面的注释
    
    Parameters:
    
    url - Url 地址
    
    pathSize - pathSize
    
    Returns:
    
    处理后的 Url 地址
  - setGlobalDomain
```
public void setGlobalDomain(java.lang.String globalDomain)
```
    全局动态替换 BaseUrl, 优先级: Header中配置的 BaseUrl > 全局配置的 BaseUrl 除了作为备用的 BaseUrl, 当您项目中只有一个 BaseUrl, 但需要动态切换这种方式不用在每个接口方法上加入 Header, 就能实现动态切换 BaseUrl
    
    Parameters:
    
    globalDomain - 全局 BaseUrl
  - getGlobalDomain
```
public okhttp3.HttpUrl getGlobalDomain()
```
    获取全局 BaseUrl
  - removeGlobalDomain
```
public void removeGlobalDomain()
```
    移除全局 BaseUrl
  - putDomain
```
public void putDomain(java.lang.String domainName,
                      java.lang.String domainUrl)
```
    存放 Domain(BaseUrl) 的映射关系
    
    Parameters:
    
    domainName -
    
    domainUrl -
  - fetchDomain
```
public okhttp3.HttpUrl fetchDomain(java.lang.String domainName)
```
    取出对应 domainName 的 Url(BaseUrl)
    
    Parameters:
    
    domainName -
    
    Returns:
  - removeDomain
```
public void removeDomain(java.lang.String domainName)
```
    移除某个 domainName
    
    Parameters:
    
    domainName - domainName
  - clearAllDomain
```
public void clearAllDomain()
```
    清理所有 Domain(BaseUrl)
  - haveDomain
```
public boolean haveDomain(java.lang.String domainName)
```
    存放 Domain(BaseUrl) 的容器中是否存在这个 domainName
    
    Parameters:
    
    domainName - domainName
    
    Returns:
    
    true 为存在, false 为不存在
  - domainSize
```
public int domainSize()
```
    存放 Domain(BaseUrl) 的容器, 当前的大小
    
    Returns:
    
    容量大小
  - setUrlParser
```
public void setUrlParser(UrlParser parser)
```
    可自行实现 UrlParser 动态切换 Url 解析策略
    
    Parameters:
    
    parser - UrlParser
  - registerUrlChangeListener
```
public void registerUrlChangeListener(onUrlChangeListener listener)
```
    注册监听器(当 Url 的 BaseUrl 被切换时会被回调的监听器)
    
    Parameters:
    
    listener - 监听器列表
  - unregisterUrlChangeListener
```
public void unregisterUrlChangeListener(onUrlChangeListener listener)
```
    注销监听器(当 Url 的 BaseUrl 被切换时会被回调的监听器)
    
    Parameters:
    
    listener - 监听器列表

Class RetrofitUrlManager

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DOMAIN_NAME_HEADER

IDENTIFICATION_IGNORE

IDENTIFICATION_PATH_SIZE

Method Detail

getInstance

with

processRequest

isRun

setRun

setDebug

startAdvancedModel

startAdvancedModel

getPathSize

isAdvancedModel

getBaseUrl

setUrlNotChange

setPathSizeOfUrl

setGlobalDomain

getGlobalDomain

removeGlobalDomain

putDomain

fetchDomain

removeDomain

clearAllDomain

haveDomain

domainSize

setUrlParser

registerUrlChangeListener

unregisterUrlChangeListener