URIUtil (feilong-core 2.0.3 API create by feilong)

java.lang.Object
- com.feilong.core.net.URIUtil

public final class URIUtil
extends Object

处理URI(Uniform Resource Locator) URL(Uniform Resource Identifier) 等.

`URI`和 `URL`的区别:

字段说明

URI
Uniform Resource Identifier 统一资源标识符,用来唯一的标识一个资源
There are two types of URIs: URLs and URNs.
See RFC 1630: Universal Resource Identifiers in WWW: A Unifying Syntax for the Expression of Names and Addresses of Objects on the Network as used in the WWW.

URL
Uniform Resource Locator 统一资源定位器,它是一种具体的URI,即URL可以用来标识一个资源,而且还指明了如何locate这个资源.
See RFC 1738: Uniform Resource Locators (URL)

URN
uniform resource name 统一资源命名,是通过名字来标识资源,
比如mailto:java-net@java.sun.com.

也就是说,URI是以一种抽象的,高层次概念定义统一资源标识,而URL和URN则是具体的资源标识的方式.URL和URN都是一种URI.

一个URI实例可以代表绝对的,也可以是相对的,只要它符合URI的语法规则;
而URL类则不仅符合语义,还包含了定位该资源的信息,因此它不能是相对的,schema必须被指定.

字段	说明
`URI` Uniform Resource Identifier	统一资源标识符,用来唯一的标识一个资源 There are two types of URIs: URLs and URNs. See RFC 1630: Universal Resource Identifiers in WWW: A Unifying Syntax for the Expression of Names and Addresses of Objects on the Network as used in the WWW.
`URL` Uniform Resource Locator	统一资源定位器,它是一种具体的URI,即URL可以用来标识一个资源,而且还指明了如何locate这个资源. See RFC 1738: Uniform Resource Locators (URL)
URN uniform resource name	统一资源命名,是通过名字来标识资源, 比如mailto:java-net@java.sun.com.

关于 `URI` 组成部分:

getQuery() 返回此 URI 的已解码的查询组成部分.

getRawQuery() 返回此 URI 的原始查询组成部分. URI 的查询组成部分(如果定义了)只包含合法的 URI 字符.

关于 URI path parameter(Matrix URIs) MatrixURIs:

Note: relative Matrix URLs are notgenerally implemented so this is just a theoretical discussion.

A URI path parameter is part of a path segment that occurs after its name.

Path parameters offer a unique opportunity to control the representations of resources

Since they can't be manipulated by standard Web forms, they have to be constructed out of band

Since they're part of the path, they're sequential, unlike query strings

Most importantly, however, their behaviour is not explicitly defined.

When defining constraints for the syntax of path parameters, we can take these characteristics into account, and define parameters that stack sequentially, and each take multiple values.

In the last paragraph of section 3.3, The URI specification suggests employing the semicolon ;, equals = and comma , characters for this task. Therefore:

characters 说明示例

semicolon ; will delimit the parameters themselves.
That is, anything in a path segment to the right of a semicolon will be treated as a new parameter like this: /path/name;param1;p2;p3

equals sign = will separate parameter names from their values, should a given parameter take values.
That is, within a path parameter, everything to the right of an equals sign is treated as a value, like this: param=value;p2

comma , will separate individual values passed into a single parameter, like this: ;param=val1,val2,val3

This means that although it may be visually confusing, parameter names can take commas but no equals signs, values can take equals signs but no commas, and no part of the path segment can take semicolons literally. All other sub-delimiters should be percent-encoded. This also means that one's opportunities for self-expression with URI paths are further constrained.

每一个path片段可以有可选的 path参数 (也叫 matrix参数),这是在path片段的最后由";"开始的一些字符.每个参数名和值由"="字符分隔,像这样:"/file;p=1",这定义了path片段 "file"有一个 path参数 "p",其值为"1".
这些参数并不常用 — 这得清楚 — 但是它们确实是存在,而且从 Yahoo RESTful API 文档我们能找到很好的理由去使用它们: Matrix参数可以让程序在GET请求中可以获取部分的数据集.参考数据集的分页 .因为matrix参数可以跟任何数据集的URI格式的path片段,它们可以在内部的path片段中被使用.

characters	说明	示例
semicolon ;	will delimit the parameters themselves. That is, anything in a path segment to the right of a semicolon will be treated as a new parameter	like this: /path/name;param1;p2;p3
equals sign =	will separate parameter names from their values, should a given parameter take values. That is, within a path parameter, everything to the right of an equals sign is treated as a value,	like this: param=value;p2
comma ,	will separate individual values passed into a single parameter,	like this: ;param=val1,val2,val3

Since:: 1.0.0
Author:: feilong
See Also:: URI, URL, URIComponents, MatrixURIs

Method Summary

Methods
Modifier and Type	Method and Description
`static URI`	`create(String uri)` 直接调用 `URI.create(String)` 创造一个URI,异常信息更丰富.
`static URI`	`create(String uriString, String charsetType)` 基于 uri字符串和charset创建 `URI`.
`static String`	`decode(String value, String charsetType)` 使用指定的编码格式 `charsetType` 来解码一个 `application/x-www-form-urlencoded` 格式的字符串 .
`static String`	`encode(String value, String charsetType)` 使用指定的编码 `charsetType`,将普通的字符串转成`application/x-www-form-urlencoded`格式的字符串.
`static String`	`encodeUri(String uriString, String charsetType)` 基于 `uriString`和`charsetType`创建 `URI`.

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

- Method Detail
  - create
```
public static URI create(String uri)
```
    直接调用 URI.create(String) 创造一个URI,异常信息更丰富.
    URI.URI(String) 和 URI.create(String)的区别:
    
    URI.URI(String),如果String对象的URI违反了RFC 2396的语法规则,将会产生一个 URISyntaxException.
    如果知道URI是有效的,不会产生 URISyntaxException,可以使用静态的 URI.create(String)方法
    
    Parameters:
    uri - the uri
    
    Returns:
    如果 uri 是null,抛出 NullPointerException
    如果 uri 是blank,抛出 IllegalArgumentException
    
    Throws:
    
    URIParseException - 如果转换的时候有任何异常
    Since:
    
    1.8.0
    
    See Also:
    URI.URI(String)
  - create
```
public static URI create(String uriString,
         String charsetType)
```
    基于 uri字符串和charset创建 URI.
    
    Parameters:
    uriString - the uri string
    charsetType - 字符编码,建议使用 CharsetType 定义好的常量,如果是null或者 empty,那么参数部分原样返回,自己去处理兼容性问题
    否则会先解码,再加码,因为ie浏览器和chrome 浏览器 url中访问路径 ,带有中文情况下不一致
    
    Returns:
    如果 uriString 是null,抛出 NullPointerException
    如果 uriString 是blank,抛出 IllegalArgumentException
    如果 Exception,抛出 URIParseException
    See Also:
    URI.create(String), encodeUri(String, String), java-request-getquerystring-value-different-between-chrome-and-ie-browser
  - encodeUri
```
public static String encodeUri(String uriString,
               String charsetType)
```
    基于 uriString和charsetType创建 URI.
    示例:
    String pattern = "mailto:venus@163.com?subject={}&body={}"; String uriString = Slf4jUtil.format(pattern, "你好", "我是飞天奔月<br>哈哈哈哈"); String result = URIUtil.encodeUri(uriString, UTF8);
    返回:
    mailto:venus@163.com?subject=%E4%BD%A0%E5%A5%BD&body=%E6%88%91%E6%98%AF%E9%A3%9E%E5%A4%A9%E5%A5%94%E6%9C%88%3Cbr%3E%E5%93%88%E5%93%88%E5%93%88%E5%93%88
    说明:
    适合于一些后台传递url参数需要encode的场景,比如支付宝 show_url(收银台页面上,商品展示的超链接),
    支付宝目前不直接支持中文参数链接,比如 http://www.underarmour.cn/s.htm?keyword=鞋&pageNo=2 ,在支付宝页面源码会显示成 http://www.underarmour.cn/s.htm?keyword=鞋&pageNo=2
    
    此时需要使用
    URIUtil.encodeUri("http://www.underarmour.cn/s.htm?keyword=鞋&pageNo=2", UTF8)
    传递 http://www.underarmour.cn/s.htm?keyword=%E9%9E%8B&pageNo=2
    Parameters:
    uriString - the uri string
    charsetType - 字符编码,建议使用 CharsetType 定义好的常量,如果是null或者 empty,那么参数部分原样返回,自己去处理兼容性问题
    否则会先解码,再加码,因为ie浏览器和chrome 浏览器 url中访问路径 ,带有中文情况下不一致
    
    Returns:
    如果 uriString 是null,抛出 NullPointerException
    如果 uriString 是blank,抛出 IllegalArgumentException
    如果 charsetType 是null或者blank,直接返回 uriString
    Since:
    
    1.4.0
    
    See Also:
    java-request-getquerystring-value-different-between-chrome-and-ie-browser, URI.create(String), ParamUtil.addParameterArrayValueMap(String, Map, String)
  - encode
```
public static String encode(String value,
            String charsetType)
```
    使用指定的编码 charsetType,将普通的字符串转成application/x-www-form-urlencoded格式的字符串.
    说明:
    使用以下规则:
    
    字母/数字字符保持不变, ("a-z"、"A-Z" 和 "0-9") .
    
    特殊字符 "."、"-"、"*" 和 "_" 保持不变.
    
    空格字符 " " 转换为一个加号 "+".
    
    % 转换为 %25
    
    所有其他字符都是不安全的,因此首先使用一些编码机制将它们转换为一个或多个字节,然后每个字节用一个包含 3 个字符的字符串 "%xy" 表示,其中 xy 为该字节的两位十六进制表示形式.
    
    不要用 URLEncoder 或者 URLDecoder来处理整个URL,一般用来处理参数值.
    
    推荐的编码机制是CharsetType.UTF8.
    Parameters:
    value - the value
    charsetType - 字符编码,建议使用 CharsetType 定义好的常量
    
    Returns:
    如果 value 是null或者empty,返回 StringUtils.EMPTY
    如果 charsetType 是null或者empty,返回 value
    See Also:
    URLEncoder.encode(String, String), URL Encoder / Decoder
  - decode
```
public static String decode(String value,
            String charsetType)
```
    使用指定的编码格式 charsetType 来解码一个 application/x-www-form-urlencoded 格式的字符串 .
    说明:
    不要用URLEncoder 或者 URLDecoder来处理整个URL,一般用来处理参数值.
    
    World Wide Web Consortium Recommendation 建议指出,CharsetType.UTF8应该被使用.不这样做可能会带来兼容性能.
    
    如果字符串最后的字符是 "%" 符号,那么URLDecoder将会抛出 exception;如果 "%" 符号在字符串中间,那么不会抛出异常.
    Parameters:
    value - 需要被解码的值
    charsetType - 字符编码,建议使用 CharsetType 定义好的常量
    
    Returns:
    如果 value 是null或者empty,返回 StringUtils.EMPTY
    如果 charsetType 是null或者empty,返回 value
    See Also:
    Exception :: URLDecoder: Incomplete trailing escape (%) pattern, URLDecoder.decode(String, String), "org.springframework.web.util.UriUtils#decode(String, String)"

Class URIUtil

`URI`和 `URL`的区别:

关于 `URI` 组成部分:

关于 URI path parameter(Matrix URIs) MatrixURIs:

Method Summary

Methods inherited from class java.lang.Object

Method Detail

create

`URI.URI(String)` 和 `URI.create(String)`的区别:

create

encodeUri

示例:

说明:

encode

说明:

decode

说明:

Class URIUtil

URI和 URL的区别:

关于 URI 组成部分:

关于 URI path parameter(Matrix URIs) MatrixURIs:

Method Summary

Methods inherited from class java.lang.Object

Method Detail

create

URI.URI(String) 和 URI.create(String)的区别:

create

encodeUri

示例:

说明:

encode

说明:

decode

说明:

`URI`和 `URL`的区别:

关于 `URI` 组成部分:

`URI.URI(String)` 和 `URI.create(String)`的区别: