`这样的html标签，以及`<` `"` 这样的html转义字符，严重影响了直接阅读代码时的直观性，而直接阅读代码的几率其实比看Html版的JavaDoc大得多。\n\n另外IDE对JavaDoc的格式化也要求``之类的标签来换行，可以配置让IDE不对JavaDoc的格式化。\n\n----\n\n**Rule 8. 【推荐】注释不要为了英文而英文**\n\n如果没有国际化要求，中文能表达得更清晰时还是用中文。\n\n----\n\n**Rule 9. 【推荐】TODO 标记，清晰说明代办事项和处理人**\n\n“对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释. ”\n\n清晰描述待修改的事项，保证过几个月后仍然能够清楚要做什么修改。\n\n如果近期会处理的事项，写明处理人。如果远期的，写明提出人。\n\n通过 IDE 和 Sonar 的标记扫描，经常清理此类标记，线上故障经常来源于这些标记但未处理的代码。\n\n正例：\n\n```java\n// TODO(who): to do what.\n// TODO(who): when to do what.\n// TODO(calvin): use xxx to replace yyy.\n```\n\n反例：\n\n```java\n// TODO: refactor it\n```\n\n不推荐使用 FIXME 标记。这样，在项目中搜索 TODO 就可以得到完整的 TODO list，而不需要搜索 TODO 和 FIXME。\n\n* [Sonar: Track uses of \"TODO\" tags](https://rules.sonarsource.com/java/RSPEC-1135)\n\n----\n\n**Rule 10. 【推荐】合理处理注释掉的代码**\n\n如果后续会恢复此段代码，在目标代码上方用`///`说明注释动机，而不是简单的注释掉代码。\n\n如果很大概率不再使用，则直接删除（版本管理工具保存了历史代码）。\n\n* [Sonar: Sections of code should not be \"commented out\"](https://rules.sonarsource.com/java/RSPEC-125)\n\n----\n"
},
{
"path": "docs/standard/chapter04.md",
"content": "# (四) 方法设计\n\n**Rule 1. 【推荐】方法的长度度量**\n\n方法尽量不要超过100行，或其他团队共同商定的行数。\n\n另外，方法长度超过8000个字节码时，将不会被JIT编译成二进制码。\n\n\n* [Sonar-107: Methods should not have too many lines](https://rules.sonarsource.com/java/RSPEC-107)，默认值改为100\n* Facebook-Contrib:Performance - This method is too long to be compiled by the JIT\n\n----\n\n**Rule 2. 【推荐】方法的语句在同一个抽象层级上**\n\n反例：一个方法里，前20行代码在进行很复杂的基本价格计算，然后调用一个折扣计算函数，再调用一个赠品计算函数。\n\n此时可将前20行也封装成一个价格计算函数，使整个方法在同一抽象层级上。\n\n----\n\n**Rule 3. 【推荐】为了帮助阅读及方法内联，将小概率发生的异常处理及其他极小概率进入的代码路径，封装成独立的方法**\n\n```java\nif(seldomHappenCase) {\n hanldMethod();\n}\n\ntry {\n ...\n} catch(SeldomHappenException e) {\n handleException();\n}\n```\n\n----\n\n**Rule 4. 【推荐】尽量减少重复的代码，抽取方法**\n\n超过5行以上重复的代码，都可以考虑抽取公用的方法。\n\n----\n\n**Rule 5. 【推荐】方法参数最好不超过3个，最多不超过7个**\n\n1）如果多个参数同属于一个对象，直接传递对象。\n\n例外: 你不希望依赖整个对象，传播了类之间的依赖性。\n\n\n2）将多个参数合并为一个新创建的逻辑对象。\n\n例外: 多个参数之间毫无逻辑关联。\n\n\n3）将函数拆分成多个函数，让每个函数所需的参数减少。\n\n* [Sonar-107: Methods should not have too many parameters](https://rules.sonarsource.com/java/RSPEC-107)\n\n----\n\n**Rule 6.【推荐】下列情形，需要进行参数校验**\n\n1） 调用频次低的方法。\n\n2） 执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，代价更大。\n\n3） 需要极高稳定性和可用性的方法。\n\n4） 对外提供的开放接口，不管是RPC/HTTP/公共类库的API接口。\n\n如果使用Apache Validate 或 Guava Precondition进行校验，并附加错误提示信息时，注意不要每次校验都做一次字符串拼接。\n\n```java\n//WRONG\nValidate.isTrue(length > 2, \"length is \"+keys.length+\", less than 2\", length);\n//RIGHT\nValidate.isTrue(length > 2, \"length is %d, less than 2\", length);\n```\n\n----\n\n**Rule 7.【推荐】下列情形，不需要进行参数校验**\n\n1） 极有可能被循环调用的方法。\n\n\n2） 底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。\n\n比如，一般DAO层与Service层都在同一个应用中，所以DAO层的参数校验，可以省略。\n\n\n3） 被声明成private，或其他只会被自己代码所调用的方法，如果能够确定在调用方已经做过检查，或者肯定不会有问题则可省略。\n\n即使忽略检查，也尽量在方法说明里注明参数的要求，比如vjkit中的@NotNull，@Nullable标识。\n\n----\n\n**Rule 8.【推荐】禁用assert做参数校验**\n\nassert断言仅用于测试环境调试，无需在生产环境时进行的校验。因为它需要增加-ea启动参数才会被执行。而且校验失败会抛出一个AssertionError(属于Error，需要捕获Throwable）\n\n因此在生产环境进行的校验，需要使用Apache Commons Lang的Validate或Guava的Precondition。\n\n----\n\n**Rule 9.【推荐】返回值可以为Null，可以考虑使用JDK8的Optional类**\n\n不强制返回空集合，或者空对象。但需要添加注释充分说明什么情况下会返回null值。\n\n本手册明确`防止NPE是调用者的责任`。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回null的情况。\n\nJDK8的Optional类的使用这里不展开。\n\n----\n\n**Rule 10.【推荐】返回值可以为内部数组和集合**\n\n如果觉得被外部修改的可能性不大，或没有影响时，不强制在返回前包裹成Immutable集合，或进行数组克隆。\n\n----\n\n**Rule 11.【推荐】不能使用有继承关系的参数类型来重载方法**\n\n因为方法重载的参数类型是根据编译时表面类型匹配的，不根据运行时的实际类型匹配。\n\n```java\nclass A {\n void hello(List list);\n void hello(ArrayList arrayList);\n}\n\nList arrayList = new ArrayList();\n\n// 下句调用的是hello(List list)，因为arrayList的定义类型是List\na.hello(arrayList);\n```\n\n----\n\n**Rule 12.【强制】正被外部调用的接口，不允许修改方法签名，避免对接口的调用方产生影响**\n\n只能新增新接口，并对已过时接口加@Deprecated注解，并清晰地说明新接口是什么。\n\n----\n\n**Rule 13.【推荐】不使用`@Deprecated`的类或方法**\n\n接口提供方既然明确是过时接口并提供新接口，那么作为调用方来说，有义务去考证过时方法的新实现是什么。\n\n比如java.net.URLDecoder 中的方法decode(String encodeStr) 这个方法已经过时，应该使用双参数decode(String source, String encode)。\n\n----\n\n**Rule 14.【推荐】不使用不稳定方法，如com.sun.\\*包下的类，底层类库中internal包下的类**\n\n`com.sun.*`，`sun.*`包下的类，或者底层类库中名称为internal的包下的类，都是不对外暴露的，可随时被改变的不稳定类。\n\n* [Sonar-1191: Classes from \"sun.*\" packages should not be used](https://rules.sonarsource.com/java/RSPEC-1191)\n\n----\n"
},
{
"path": "docs/standard/chapter05.md",
"content": "# (五) 类设计\n\n**Rule 1. 【推荐】类成员与方法的可见性最小化**\n\n任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。思考：如果是一个private的方法，想删除就删除，可是一个public的service方法，或者一个public的成员变量，删除一下，不得手心冒点汗吗？\n\n例外：为了单元测试，有时也可能将访问范围扩大，此时需要加上JavaDoc说明或vjkit中的`@VisibleForTesting`注解。\n\n----\n\n**Rule 2.【推荐】 减少类之间的依赖**\n\n比如如果A类只依赖B类的某个属性，在构造函数和方法参数中，只传入该属性。让阅读者知道，A类只依赖了B类的这个属性，而不依赖其他属性，也不会调用B类的任何方法。\n\n```java\na.foo(b); //WRONG\n\na.foo(b.bar); //RIGHT\n```\n----\n\n**Rule 3.【推荐】 定义变量与方法参数时，尽量使用接口而不是具体类**\n\n使用接口可以保持一定的灵活性，也能向读者更清晰的表达你的需求：变量和参数只是要求有一个Map，而不是特定要求一个HashMap。\n\n例外：如果变量和参数要求某种特殊类型的特性，则需要清晰定义该参数类型，同样是为了向读者表达你的需求。\n\n----\n\n**Rule 4. 【推荐】类的长度度量**\n\n类尽量不要超过300行，或其他团队共同商定的行数。\n\n对过大的类进行分拆时，可考虑其内聚性，即类的属性与类的方法的关联程度，如果有些属性没有被大部分的方法使用，其内聚性是低的。\n\n----\n\n**Rule 5.【推荐】 构造函数如果有很多参数，且有多种参数组合时，建议使用Builder模式**\n\n```java\nExecutor executor = new ThreadPoolBuilder().coreThread(10).queueLenth(100).build();\n```\n\n即使仍然使用构造函数，也建议使用chain constructor模式，逐层加入默认值传递调用，仅在参数最多的构造函数里实现构造逻辑。\n\n```java\npublic A(){\n A(DEFAULT_TIMEOUT);\n}\n\npublic A(int timeout) {\n ...\n}\n```\n\n----\n\n**Rule 6.【推荐】构造函数要简单，尤其是存在继承关系的时候**\n\n可以将复杂逻辑，尤其是业务逻辑，抽取到独立函数，如init()，start()，让使用者显式调用。\n\n```java\nFoo foo = new Foo();\nfoo.init();\n```\n\n----\n\n**Rule 7.【强制】所有的子类覆写方法，必须加`@Override`注解**\n\n比如有时候子类的覆写方法的拼写有误，或方法签名有误，导致没能真正覆写，加`@Override`可以准确判断是否覆写成功。\n\n而且，如果在父类中对方法签名进行了修改，子类会马上编译报错。\n\n另外，也能提醒阅读者这是个覆写方法。\n\n最后，建议在IDE的Save Action中配置自动添加`@Override`注解，如果无意间错误同名覆写了父类方法也能被发现。\n\n* [Sonar-1161: \"@Override\" should be used on overriding and implementing methods](https://rules.sonarsource.com/java/RSPEC-1161)\n\n----\n\n**Rule 8.【强制】静态方法不能被子类覆写。**\n\n因为它只会根据表面类型来决定调用的方法。\n\n```java\nBase base = new Children();\n\n// 下句实际调用的是父类的静态方法，虽然对象实例是子类的。\nbase.staticMethod();\n```\n\n----\n\n**Rule 9.静态方法访问的原则**\n\n**9.1【推荐】避免通过一个类的对象引用访问此类的静态变量或静态方法，直接用类名来访问即可**\n\n目的是向读者更清晰传达调用的是静态方法。可在IDE的Save Action中配置自动转换。\n\n```java\nint i = objectA.staticMethod(); // WRONG\n\nint i = ClassA.staticMethod(); // RIGHT\n```\n\n* [Sonar-2209: \"static\" members should be accessed statically](https://rules.sonarsource.com/java/RSPEC-2209)\n* [Sonar-2440: Classes with only \"static\" methods should not be instantiated](https://rules.sonarsource.com/java/RSPEC-2440)\n\n\n**9.2 【推荐】除测试用例，不要static import 静态方法**\n\n静态导入后忽略掉的类名，给阅读者造成障碍。\n\n例外：测试环境中的assert语句，大家都太熟悉了。\n\n* [Sonar-3030: Classes should not have too many \"static\" imports](https://rules.sonarsource.com/java/RSPEC-3030) 但IDEA经常自动转换static import，所以暂不作为规则。\n\n\n**9.3【推荐】尽量避免在非静态方法中修改静态成员变量的值**\n\n```java\n// WRONG\npublic void foo() {\n ClassA.staticFiled = 1;\n}\n```\n\n* [Sonar-2696: Instance methods should not write to \"static\" fields](https://rules.sonarsource.com/java/RSPEC-2696)\n* [Sonar-3010: Static fields should not be updated in constructors](https://rules.sonarsource.com/java/RSPEC-3010)\n\n\n----\n\n**Rule 10.【推荐】 内部类的定义原则**\n\n当一个类与另一个类关联非常紧密，处于从属的关系，特别是只有该类会访问它时，可定义成私有内部类以提高封装性。\n\n另外，内部类也常用作回调函数类，在JDK8下建议写成Lambda。\n\n内部类分匿名内部类，内部类，静态内部类三种。\n\n1) 匿名内部类 与 内部类，按需使用：\n\n在性能上没有区别；当内部类会被多个地方调用，或匿名内部类的长度太长，已影响对调用它的方法的阅读时，定义有名字的内部类。\n\n\n2) 静态内部类 与 内部类，优先使用静态内部类：\n\n1. 非静态内部类持有外部类的引用，能访问外类的实例方法与属性。构造时多传入一个引用对性能没有太大影响，更关键的是向阅读者传递自己的意图，内部类会否访问外部类。\n2. 非静态内部类里不能定义static的属性与方法。\n\n* [Sonar-2694: Inner classes which do not reference their owning classes should be \"static\"](https://rules.sonarsource.com/java/RSPEC-2694)\n* [Sonar-1604: Anonymous inner classes containing only one method should become lambdas](https://rules.sonarsource.com/java/RSPEC-1604)\n\n----\n\n**Rule 11.【推荐】使用getter/setter方法，还是直接public成员变量的原则。**\n\n除非因为特殊原因方法内联失败，否则使用getter方法与直接访问成员变量的性能是一样的。\n\n使用getter/setter，好处是可以进一步的处理：\n\n1. 通过隐藏setter方法使得成员变量只读\n\n2. 增加简单的校验逻辑\n\n3. 增加简单的值处理，值类型转换等\n\n建议通过IDE生成getter/setter。\n\n但getter/seter中不应有复杂的业务处理，建议另外封装函数，并且不要以getXX/setXX命名。\n\n\n如果是内部类，以及无逻辑的POJO/VO类，使用getter/setter除了让一些纯OO论者感觉舒服，没有任何的好处，建议直接使用public成员变量。\n\n例外：有些序列化框架只能从getter/setter反射，不能直接反射public成员变量。\n\n----\n\n**Rule 12.【强制】POJO类必须覆写toString方法。**\n\n便于记录日志，排查问题时调用POJO的toString方法打印其属性值。否则默认的Object.toString()只打印`类名@数字`的无效信息。\n\n----\n\n**Rule 13. hashCode和equals方法的处理，遵循如下规则:**\n\n\n**13.1【强制】只要重写equals，就必须重写hashCode。 而且选取相同的属性进行运算。**\n\n\n**13.2【推荐】只选取真正能决定对象是否一致的属性，而不是所有属性，可以改善性能。**\n\n\n**13.3【推荐】对不可变对象，可以缓存hashCode值改善性能（比如String就是例子）。**\n\n\n**13.4【强制】类的属性增加时，及时重新生成toString，hashCode和equals方法。**\n\n\n* [Sonar-1206: \"equals(Object obj)\" and \"hashCode()\" should be overridden in pairs](https://rules.sonarsource.com/java/RSPEC-1206)\n\n----\n\n**Rule 14.【强制】使用 IDE 生成 toString、hashCode 和 equals 方法。**\n\n使用 IDE 生成而不是手写，能保证 toString 有统一的格式，equals 和 hashCode 则避免不正确的 null 值处理。\n\n子类生成 toString 时，还需要勾选父类的属性。\n\n----\n\n**Rule 15. 【强制】Object的equals方法容易抛空指针异常，应使用常量或确定非空的对象来调用equals**\n\n推荐使用java.util.Objects#equals（JDK7引入的工具类）\n\n```java\n\"test\".equals(object); //RIGHT\n\nObjects.equals(object, \"test\"); //RIGHT\n```\n\n* [Sonar-1132: Strings literals should be placed on the left side when checking for equality](https://rules.sonarsource.com/java/RSPEC-1132)\n\n----\n\n**Rule 16.【强制】除了保持兼容性的情况，总是移除无用属性、方法与参数**\n\n特别是private的属性、方法、内部类，private方法上的参数，一旦无用立刻移除。信任代码版本管理系统。\n\n* [Sonar-3985: Unused \"private\" classes should be removed](https://rules.sonarsource.com/java/RSPEC-3985)\n* [Sonar-1068: Unused \"private\" fields should be removed](https://rules.sonarsource.com/java/RSPEC-1068)\n* [Sonar: Unused \"private\" methods should be removed](https://rules.sonarsource.com/java/RSPEC-1144)\n* [Sonar-1481: Unused local variables should be removed](https://rules.sonarsource.com/java/RSPEC-1481)\n* [Sonar-1172: Unused method parameters should be removed](https://rules.sonarsource.com/java/RSPEC-1172) Sonar-VJ版只对private方法的无用参数告警。\n\n\n----\n\n**Rule 17.【推荐】final关键字与性能无关，仅用于下列不可修改的场景**\n\n1） 定义类及方法时，类不可继承，方法不可覆写；\n\n2） 定义基本类型的函数参数和变量，不可重新赋值；\n\n3） 定义对象型的函数参数和变量，仅表示变量所指向的对象不可修改，而对象自身的属性是可以修改的。\n\n----\n\n**Rule 18.【推荐】得墨忒耳法则，不要和陌生人说话**\n\n以下调用，一是导致了对A对象的内部结构(B,C)的紧耦合，二是连串的调用很容易产生NPE，因此链式调用尽量不要过长。\n\n```java\nobj.getA().getB().getC().hello();\n```\n\n----\n"
},
{
"path": "docs/standard/chapter06.md",
"content": "# (六) 控制语句\n\n**Rule 1. 【强制】if, else, for, do, while语句必须使用大括号，即使只有单条语句**\n\n曾经试过合并代码时，因为没加括号，单条语句合并成两条语句后，仍然认为只有单条语句，另一条语句在循环外执行。\n\n其他增加调试语句等情况也经常引起同样错误。\n\n可在IDE的Save Action中配置自动添加。\n\n```java\nif (a == b) {\n ...\n}\n```\n\n例外：一般由IDE生成的equals()函数\n\n* [Sonar-121: Control structures should use curly braces](https://rules.sonarsource.com/java/RSPEC-121) Sonar-VJ版豁免了equals()函数\n\n----\n\n**Rule 2.【推荐】少用if-else方式，多用哨兵语句式以减少嵌套层次**\n\n```java\nif (condition) {\n ...\n return obj;\n}\n\n// 接着写else的业务逻辑代码;\n```\n\n* Facebook-Contrib: Style - Method buries logic to the right (indented) more than it needs to be\n\n----\n\n**Rule 3.【推荐】限定方法的嵌套层次**\n\n所有if/else/for/while/try的嵌套，当层次过多时，将引起巨大的阅读障碍，因此一般推荐嵌套层次不超过4。\n\n通过抽取方法，或哨兵语句（见Rule 2）来减少嵌套。\n\n```java\npublic void applyDriverLicense() {\n if (isTooYoung()) {\n System.out.println(\"You are too young to apply driver license.\");\n return;\n }\n\n if (isTooOld()) {\n System.out.println(\"You are too old to apply driver license.\");\n return;\n }\n\n System.out.println(\"You've applied the driver license successfully.\");\n return;\n}\n```\n\n* [Sonar-134: Control flow statements \"if\", \"for\", \"while\", \"switch\" and \"try\" should not be nested too deeply](https://rules.sonarsource.com/java/RSPEC-134)，增大为4\n\n----\n\n**Rule 4.【推荐】布尔表达式中的布尔运算符(&&,||)的个数不超过4个，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性**\n\n\n```java\n//WRONG\nif ((file.open(fileName, \"w\") != null) && (...) || (...)|| (...)) {\n ...\n}\n\n//RIGHT\nboolean existed = (file.open(fileName, \"w\") != null) && (...) || (...);\nif (existed || (...)) {\n ...\n}\n```\n\n* [Sonar-1067: Expressions should not be too complex](https://rules.sonarsource.com/java/RSPEC-1067)，增大为4\n\n----\n\n**Rule 5.【推荐】简单逻辑，善用三目运算符，减少if-else语句的编写**\n\n```java\ns != null ? s : \"\";\n```\n\n----\n\n**Rule 6.【推荐】减少使用取反的逻辑**\n\n不使用取反的逻辑，有利于快速理解。且大部分情况，取反逻辑存在对应的正向逻辑写法。\n\n```java\n//WRONG\nif (!(x >= 268) { ... }\n\n//RIGHT\nif (x < 268) { ... }\n```\n\n* [Sonar-1940: Boolean checks should not be inverted](https://rules.sonarsource.com/java/RSPEC-1940)\n\n----\n\n**Rule 7.【推荐】表达式中，能造成短路概率较大的逻辑尽量放前面，使得后面的判断可以免于执行**\n\n\n```java\nif (maybeTrue() || maybeFalse()) { ... }\n\nif (maybeFalse() && maybeTrue()) { ... }\n```\n\n----\n\n\n**Rule 8.【强制】switch的规则**\n\n1）在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；\n\n2）在一个switch块内，都必须包含一个default语句并且放在最后，即使它什么代码也没有。\n\n```java\nString animal = \"tomcat\";\n\nswitch (animal) {\ncase \"cat\":\n System.out.println(\"It's a cat.\");\n break;\ncase \"lion\": // 执行到tiger\ncase \"tiger\":\n System.out.println(\"It's a beast.\");\n break;\ndefault:\n // 什么都不做，也要有default\n break;\n}\n```\n\n* [Sonar: \"switch\" statements should end with \"default\" clauses](https://rules.sonarsource.com/java/RSPEC-131)\n\n----\n\n**Rule 9.【推荐】循环体中的语句要考量性能，操作尽量移至循环体外处理**\n\n1）不必要的耗时较大的对象构造；\n\n2）不必要的try-catch（除非出错时需要循环下去）。\n\n----\n\n**Rule 10.【推荐】能用while循环实现的代码，就不用do-while循环**\n\nwhile语句能在循环开始的时候就看到循环条件，便于帮助理解循环内的代码；\n\ndo-while语句要在循环最后才看到循环条件，不利于代码维护，代码逻辑容易出错。\n\n----\n"
},
{
"path": "docs/standard/chapter07.md",
"content": "# (七) 基本类型与字符串\n\n**Rule 1. 原子数据类型(int等)与包装类型(Integer等)的使用原则**\n\n**1.1 【推荐】需要序列化的POJO类属性使用包装数据类型**\n\n\n**1.2 【推荐】RPC方法的返回值和参数使用包装数据类型**\n\n\n**1.3 【推荐】局部变量尽量使用基本数据类型**\n\n\n包装类型的坏处:\n\n1）Integer 24字节，而原子类型 int 4字节。\n\n2）包装类型每次赋值还需要额外创建对象，如Integer var = 200， 除非数值在缓存区间内(见Integer.IntegerCache与Long.LongCache)才会复用已缓存对象。默认缓存区间为-128到127，其中Integer的缓存区间还受启动参数的影响，如-XX:AutoBoxCacheMax=20000。\n\n3）包装类型还有==比较的陷阱（见规则3）\n\n\n包装类型的好处:\n\n1）包装类型能表达 null 的语义。\n\n比如数据库的查询结果可能是null，如果用基本数据类型有NPE风险。又比如显示成交总额涨跌情况，如果调用的RPC服务不成功时，应该返回null，显示成-%，而不是0%。\n\n2）集合需要包装类型，除非使用数组，或者特殊的原子类型集合。\n\n3）泛型需要包装类型，如`Result`。\n\n----\n\n**Rule 2.原子数据类型与包装类型的转换原则**\n\n**2.1【推荐】自动转换(AutoBoxing)有一定成本，调用者与被调用函数间尽量使用同一类型，减少默认转换**\n\n```java\n//WRONG, sum 类型为Long， i类型为long，每次相加都需要AutoBoxing。\nLong sum=0L;\n\nfor( long i = 0; i < 10000; i++) {\n sum+=i;\n}\n\n//RIGHT, 准确使用API返回正确的类型\nInteger i = Integer.valueOf(str);\nint i = Integer.parseInt(str);\n```\n\n* [Sonar-2153: Boxing and unboxing should not be immediately reversed](https://rules.sonarsource.com/java/RSPEC-2153)\n\n\n**2.2 【推荐】自动拆箱有可能产生NPE，要注意处理**\n\n```java\n//如果intObject为null，产生NPE\nint i = intObject;\n```\n\n----\n\n**Rule 3. 数值equals比较的原则**\n\n**3.1【强制】 所有包装类对象之间值的比较，全部使用equals方法比较**\n\n\\==判断对象是否同一个。Integer var = ?在缓存区间的赋值（见规则1），会复用已有对象，因此这个区间内的Integer使用==进行判断可通过，但是区间之外的所有数据，则会在堆上新产生，不会通过。因此如果用\\== 来比较数值，很可能在小的测试数据中通过，而到了生产环境才出问题。\n\n\n**3.2【强制】 BigDecimal需要使用compareTo()**\n\n因为BigDecimal的equals()还会比对精度，2.0与2.00不一致。\n\n* Facebook-Contrib: Correctness - Method calls BigDecimal.equals()\n\n**3.3【强制】 Atomic\\* 系列，不能使用 equals 方法**\n\n因为 Atomic\\* 系列没有覆写 equals 方法。\n\n```java\n// RIGHT\nif (counter1.get() == counter2.get()) {\n // ...\n}\n```\n\n* [Sonar-2204: \".equals()\" should not be used to test the values of \"Atomic\" classes](https://rules.sonarsource.com/java/RSPEC-2204)\n\n**3.4【强制】 double 及 float 的比较，要特殊处理**\n\n因为精度问题，浮点数间的 equals 非常不可靠，在 vjkit 的 NumberUtil 中有对应的封装函数。\n\n```java\nfloat f1 = 0.15f;\nfloat f2 = 0.45f/3; // 实际等于0.14999999\n\n// 反例\nif (f1 == f2) {\n // ...\n}\n\n// 反例\nif (Double.compare(f1, f2) == 0) {\n // ...\n}\n\n// 正例\n// 绝对误差\nstatic final float EPSILON = 0.00001f;\nif (Math.abs(f1 - f2) < EPSILON) {\n // ...\n}\n\n// 正例\n// 相对误差\nstatic final float EPSILON = 0.001f;\nif (Math.abs(f1 - f2) / (Math.abs(f1) + Math.abs(f2)) < EPSILON) {\n // ...\n}\n```\n\n推荐使用“相对误差”的方式比较浮点数。\n\n* [Sonar-1244: Floating point numbers should not be tested for equality](https://rules.sonarsource.com/java/RSPEC-1244)\n\n----\n\n**Rule 4. 数字类型的计算原则**\n\n**4.1【强制】数字运算表达式，因为先进行等式右边的运算，再赋值给等式左边的变量，所以等式两边的类型要一致**\n\n例子1: int与int相除后，哪怕被赋值给float或double，结果仍然是四舍五入取整的int。\n\n需要强制将除数或被除数转换为float或double。\n\n```java\ndouble d = 24/7; //结果是3.0\ndouble d = (double)24/7; //结果是正确的3.42857\n```\n\n例子2： int与int相乘，哪怕被赋值给long，仍然会溢出。\n\n需要强制将乘数的一方转换为long。\n\n```java\nlong l = Integer.MAX_VALUE * 2; // 结果是溢出的－2\nlong l = Integer.MAX_VALUE * 2L; //结果是正确的4294967294\n```\n\n另外，int的最大值约21亿，留意可能溢出的情况。\n\n* [Sonar-2184: Math operands should be cast before assignment](https://rules.sonarsource.com/java/RSPEC-2184)\n\n\n**4.2【强制】数字取模的结果不一定是正数，负数取模的结果仍然负数**\n\n取模做数组下标时，如果不处理负数的情况，很容易ArrayIndexOutOfBoundException。\n\n另外，Integer.MIN_VALUE取绝对值也仍然是负数。因此，vjkit的MathUtil对上述情况做了安全的封装。\n\n```java\n-4 % 3 = -1;\nMath.abs(Integer.MIN_VALUE) = -2147483648;\n```\n\n* Findbugs: Style - Remainder of hashCode could be negative\n\n\n**4.3【推荐】 double 或 float 计算时有不可避免的精度问题**\n\n```java\n\nfloat f = 0.45f/3; //结果是0.14999999\n\ndouble d1 = 0.45d/3; //结果是正确的0.15\n\ndouble d2 = 1.03d - 0.42d; //结果是0.6100000000000001\n\n```\n\n尽量用double而不用float，但如果是金融货币的计算，则必须使用如下选择：\n\n选项1， 使用性能较差的BigDecimal。BigDecimal还能精确控制四舍五入或是其他取舍的方式。\n\n选项2， 在预知小数精度的情况下，将浮点运算放大为整数计数，比如货币以\"分\"而不是以\"元\"计算。\n\n\n* [Sonar-2164: Math should not be performed on floats](https://rules.sonarsource.com/java/RSPEC-2164)\n\n----\n\n**Rule 5. 【推荐】如果变量值仅有有限的可选值，用枚举类来定义常量**\n\n尤其是变量还希望带有名称之外的延伸属性时，如下例：\n\n```java\n//WRONG\npublic String MONDAY = \"MONDAY\";\npublic int MONDAY_SEQ = 1;\n\n//RIGHT\npublic enum SeasonEnum {\n\tSPRING(1), SUMMER(2), AUTUMN(3), WINTER(4);\n\tint seq;\n\tSeasonEnum(int seq) { this.seq = seq; }\n}\n```\n\n业务代码中不要依赖ordinary()函数进行业务运算，而是自定义数字属性，以免枚举值的增减调序造成影响。 例外：永远不会有变化的枚举，比如上例的一年四季。\n\n----\n\n**Rule 6. 字符串拼接的原则**\n\n**6.1 【推荐】 当字符串拼接不在一个命令行内写完，而是存在多次拼接时(比如循环)，使用StringBuilder的append()**\n\n```java\nString s = \"hello\" + str1 + str2; //Almost OK，除非初始长度有问题，见第3点.\n\nString s = \"hello\"; //WRONG\nif (condition) {\n s += str1;\n}\n\nString str = \"start\"; //WRONG\nfor (int i = 0; i < 100; i++) {\n str = str + \"hello\";\n}\n```\n\n反编译出的字节码文件显示，其实每条用`+`进行字符拼接的语句，都会new出一个StringBuilder对象，然后进行append操作，最后通过toString方法返回String对象。所以上面两个错误例子，会重复构造StringBuilder，重复toString()造成资源浪费。\n\n\n* [Sonar-1643: Strings should not be concatenated using '+' in a loop](https://rules.sonarsource.com/java/RSPEC-1643)\n\n\n**6.2 【强制】 字符串拼接对象时，不要显式调用对象的toString()**\n\n如上，`+`实际是StringBuilder，本身会调用对象的toString()，且能很好的处理null的情况。\n\n```java\n//WRONG\nstr = \"result:\" + myObject.toString(); // myObject 为 null时，抛 NPE\n\n//RIGHT\nstr = \"result:\" + myObject; // myObject 为 null 时，输出 result:null\n```\n\n\n**6.3【强制】使用StringBuilder，而不是有所有方法都有同步修饰符的StringBuffer**\n\n因为内联不成功，逃逸分析并不能抹除StringBuffer上的同步修饰符\n\n* [Sonar-1149: Synchronized classes Vector, Hashtable, Stack and StringBuffer should not be used](https://rules.sonarsource.com/java/RSPEC-1149)\n\n\n**6.4 【推荐】当拼接后字符串的长度远大于16时，指定StringBuilder的大概长度，避免容量不足时的成倍扩展**\n\n\n**6.5 【推荐】如果字符串长度很大且频繁拼接，可考虑ThreadLocal重用StringBuilder对象**\n\n参考BigDecimal的toString()实现，及vjkit中的StringBuilderHolder。\n\n----\n\n**Rule 7. 【推荐】字符操作时，优先使用字符参数，而不是字符串，能提升性能**\n\n```java\n//WRONG\nstr.indexOf(\"e\");\n\n//RIGHT\nstringBuilder.append('a');\nstr.indexOf('e');\nstr.replace('m','z');\n```\n\n其他包括split等方法，在JDK String中未提供针对字符参数的方法，可考虑使用Apache Commons StringUtils 或Guava的Splitter。\n\n* [Sonar-3027: String function use should be optimized for single characters](https://rules.sonarsource.com/java/RSPEC-3027)\n\n----\n\n**Rule 8. 【推荐】利用好正则表达式的预编译功能，可以有效加快正则匹配速度**\n\n反例：\n```java\n//直接使用String的matches()方法\nresult = \"abc\".matches(\"[a-zA-z]\");\n\n//每次重新构造Pattern\nPattern pattern = Pattern.compile(\"[a-zA-z]\");\nresult = pattern.matcher(\"abc\").matches();\n```\n\n正例：\n```java\n//在某个地方预先编译Pattern，比如类的静态变量\nprivate static Pattern pattern = Pattern.compile(\"[a-zA-z]\");\n...\n//真正使用Pattern的地方\nresult = pattern.matcher(\"abc\").matches();\n```\n\n----\n"
},
{
"path": "docs/standard/chapter08.md",
"content": "# (八) 集合处理\n\n**Rule 1. 【推荐】底层数据结构是数组的集合，指定集合初始大小**\n\n底层数据结构为数组的集合包括 ArrayList，HashMap，HashSet，ArrayDequeue等。\n\n数组有大小限制，当超过容量时，需要进行复制式扩容，新申请一个是原来容量150% or 200%的数组，将原来的内容复制过去，同时浪费了内存与性能。HashMap/HashSet的扩容，还需要所有键值对重新落位，消耗更大。\n\n\n默认构造函数使用默认的数组大小，比如ArrayList默认大小为10，HashMap为16。因此建议使用ArrayList(int initialCapacity)等构造函数，明确初始化大小。\n\n\nHashMap/HashSet的初始值还要考虑加载因子:\n\n为了降低哈希冲突的概率(Key的哈希值按数组大小取模后，如果落在同一个数组下标上，将组成一条需要遍历的Entry链)，默认当HashMap中的键值对达到数组大小的75%时，即会触发扩容。因此，如果预估容量是100，即需要设定`100/0.75 +1＝135`的数组大小。vjkit的MapUtil的Map创建函数封装了该计算。\n\n如果希望加快Key查找的时间，还可以进一步降低加载因子，加大初始大小，以降低哈希冲突的概率。\n\n----\n\n**Rule 2. 【推荐】尽量使用新式的foreach语法遍历Collection与数组**\n\nforeach是语法糖，遍历集合的实际字节码等价于基于Iterator的循环。\n\nforeach代码一来代码简洁，二来有效避免了有多个循环或嵌套循环时，因为不小心的复制粘贴，用错了iterator或循环计数器(i,j)的情况。\n\n----\n\n**Rule 3. 【强制】不要在foreach循环里进行元素的remove/add操作，remove元素可使用Iterator方式**\n\n```java\n//WRONG\nfor (String str : list) {\n if (condition) {\n list.remove(str);\n }\n}\n\n//RIGHT\nIterator it = list.iterator();\nwhile (it.hasNext()) {\n String str = it.next();\n if (condition) {\n it.remove();\n }\n}\n```\n\n* Facebook-Contrib: Correctness - Method modifies collection element while iterating\n* Facebook-Contrib: Correctness - Method deletes collection element while iterating\n\n----\n\n**Rule 4. 【强制】使用entrySet遍历Map类集合Key/Value，而不是keySet\t方式进行遍历**\n\nkeySet遍历的方式，增加了N次用key获取value的查询。\n\n* [Sonar-2864:\"entrySet()\" should be iterated when both the key and value are needed](https://rules.sonarsource.com/java/RSPEC-2864)\n\n----\n\n**Rule 5. 【强制】当对象用于集合时，下列情况需要重新实现hashCode()和 equals()**\n\n1） 以对象做为Map的KEY时；\n\n2） 将对象存入Set时。\n\n上述两种情况，都需要使用hashCode和equals比较对象，默认的实现会比较是否同一个对象（对象的引用相等）。\n\n另外，对象放入集合后，会影响hashCode()，equals()结果的属性，将不允许修改。\n\n* [Sonar-2141:Classes that don't define \"hashCode()\" should not be used in hashes](https://rules.sonarsource.com/java/RSPEC-2141)\n\n----\n\n**Rule 6. 【强制】高度注意各种Map类集合Key/Value能不能存储null值的情况**\n\n| Map | Key | Value |\n| -------- | -------- |-------- |\n|HashMap|Nullable | Nullable|\n|ConcurrentHashMap| NotNull| NotNull|\n|TreeMap| NotNull| Nullable |\n\n由于HashMap的干扰，很多人认为ConcurrentHashMap是可以置入null值。同理，Set中的value实际是Map中的key。\n\n----\n\n**Rule 7. 【强制】长生命周期的集合，里面内容需要及时清理，避免内存泄漏**\n\n长生命周期集合包括下面情况，都要小心处理。\n\n1） 静态属性定义；\n\n2） 长生命周期对象的属性；\n\n3） 保存在ThreadLocal中的集合。\n\n如无法保证集合的大小是有限的，使用合适的缓存方案代替直接使用HashMap。\n\n另外，如果使用WeakHashMap保存对象，当对象本身失效时，就不会因为它在集合中存在引用而阻止回收。但JDK的WeakHashMap并不支持并发版本，如果需要并发可使用Guava Cache的实现。\n\n----\n\n**Rule 8. 【强制】集合如果存在并发修改的场景，需要使用线程安全的版本**\n\n1) 著名的反例，HashMap扩容时，遇到并发修改可能造成100%CPU占用。\n\n推荐使用`java.util.concurrent(JUC)`工具包中的并发版集合，如ConcurrentHashMap等，优于使用Collections.synchronizedXXX()系列函数进行同步化封装(等价于在每个方法都加上synchronized关键字)。\n\n\n例外：ArrayList所对应的CopyOnWriteArrayList，每次更新时都会复制整个数组，只适合于读多写很少的场景。如果频繁写入，可能退化为使用Collections.synchronizedList(list)。\n\n\n2) 即使线程安全类仍然要注意函数的正确使用。\n\n例如：即使用了 ConcurrentHashMap，但直接使用 get/put 方法，仍然可能会多线程间互相覆盖。\n\n```java\n//WRONG\nE e = map.get(key);\nif (e == null) {\n e = new E();\n map.put(key, e); //仍然能两条线程并发执行put，互相覆盖\n}\nreturn e;\n\n//RIGHT\nE e = map.get(key);\nif (e == null) {\n e = new E();\n E previous = map.putIfAbsent(key, e);\n if(previous != null) {\n return previous;\n }\n}\nreturn e;\n```\n----\n\n**Rule 9. 【推荐】正确使用集合泛型的通配符**\n\n`List`并不是`List`的子类，如果希望泛型的集合能向上向下兼容转型，而不仅仅适配唯一类，则需定义通配符，可以按需要extends 和 super的字面意义，也可以遵循`PECS(Producer Extends Consumer Super)`原则:\n\n1) 如果集合要被读取，定义成``\n\n```java\nClass Stack{\n public void pushAll(Iterable src){\n for (E e: src)\n push(e);\n }\n}\n\nStack stack = new Stack();\nIterable integers = ...;\nstack.pushAll(integers);\n```\n\n\n2) 如果集合要被写入，定义成``\n\n```java\nClass Stack{\n public void popAll(Collection dist){\n while(!isEmpty())\n \t dist.add(pop);\n }\n}\n\nStack stack = new Stack();\nCollection objects = ...;\nstack.popAll(objects);\n```\n----\n\n**Rule 10. 【推荐】`List`, `List` 与 `List`的选择**\n\n定义成`List`，会被IDE提示需要定义泛型。 如果实在无法确定泛型，就仓促定义成`List`来蒙混过关的话，该list只能读，不能增改。定义成`List`呢，如规则9所述，`List` 并不是`List`的子类，除非函数定义使用了通配符。\n\n因此实在无法明确其泛型时，使用`List`也是可以的。\n\n----\n\n**Rule 11. 【推荐】如果Key只有有限的可选值，先将Key封装成Enum，并使用EnumMap**\n\nEnumMap，以Enum为Key的Map，内部存储结构为`Object[enum.size]`，访问时以`value = Object[enum.ordinal()]`获取值，同时具备HashMap的清晰结构与数组的性能。\n\n```java\npublic enum COLOR {\n RED, GREEN, BLUE, ORANGE;\n}\n\nEnumMap moodMap = new EnumMap (COLOR.class);\n```\n\n* [Sonar-1640: Maps with keys that are enum values should be replaced with EnumMap](https://rules.sonarsource.com/java/RSPEC-1640)\n\n----\n\n**Rule 12. 【推荐】Array 与 List互转的正确写法**\n\n```java\n// list -> array，构造数组时不需要设定大小\nString[] array = (String[])list.toArray(); //WRONG;\nString[] array = list.toArray(new String[0]); //RIGHT\nString[] array = list.toArray(new String[list.size()]); //RIGHT，但list.size()可用0代替。\n\n\n// array -> list\n//非原始类型数组，且List不能再扩展\nList list = Arrays.asList(array);\n\n//非原始类型数组， 但希望List能再扩展\nList list = new ArrayList(array.length);\nCollections.addAll(list, array);\n\n//原始类型数组，JDK8\nList myList = Arrays.stream(intArray).boxed().collect(Collectors.toList());\n\n//原始类型数组，JDK7则要自己写个循环来加入了\n```\nArrays.asList(array)，如果array是原始类型数组如int[]，会把整个array当作List的一个元素，String[] 或 Foo[]则无此问题。\nCollections.addAll()实际是循环加入元素，性能相对较低，同样会把int[]认作一个元素。\n\n* Facebook-Contrib: Correctness - Impossible downcast of toArray() result\n* Facebook-Contrib: Correctness - Method calls Array.asList on an array of primitive values\n\n----\n"
},
{
"path": "docs/standard/chapter09.md",
"content": "# (九) 并发处理\n\n**Rule 1. 【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯**\n\n1）创建单条线程时直接指定线程名称\n\n```java\nThread t = new Thread();\nt.setName(\"cleanup-thread\");\n```\n\n2） 线程池则使用guava或自行封装的ThreadFactory，指定命名规则。\n\n```java\n//guava 或自行封装的ThreadFactory\nThreadFactory threadFactory = new ThreadFactoryBuilder().setNameFormat(threadNamePrefix + \"-%d\").build();\n\nThreadPoolExecutor executor = new ThreadPoolExecutor(..., threadFactory, ...);\n```\n\n----\n\n**Rule 2. 【推荐】尽量使用线程池来创建线程**\n\n除特殊情况，尽量不要自行创建线程，更好的保护线程资源。\n\n```java\n//WRONG\nThread thread = new Thread(...);\nthread.start();\n```\n\n同理，定时器也不要使用Timer，而应该使用ScheduledExecutorService。\n\n因为Timer只有单线程，不能并发的执行多个在其中定义的任务，而且如果其中一个任务抛出异常，整个Timer也会挂掉，而ScheduledExecutorService只有那个没捕获到异常的任务不再定时执行，其他任务不受影响。\n\n----\n\n**Rule 3. 【强制】线程池不允许使用 Executors去创建，避资源耗尽风险**\n\nExecutors返回的线程池对象的弊端 ：\n\n1）FixedThreadPool 和 SingleThreadPool:\n\n允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。\n\n\n2）CachedThreadPool 和 ScheduledThreadPool:\n\n允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。\n\n\n应通过 new ThreadPoolExecutor(xxx,xxx,xxx,xxx)这样的方式，更加明确线程池的运行规则，合理设置Queue及线程池的core size和max size，建议使用vjkit封装的ThreadPoolBuilder。\n\n----\n\n**Rule 4. 【强制】正确停止线程**\n\nThread.stop()不推荐使用，强行的退出太不安全，会导致逻辑不完整，操作不原子，已被定义成Deprecate方法。\n\n停止单条线程，执行Thread.interrupt()。\n\n停止线程池：\n\n* ExecutorService.shutdown(): 不允许提交新任务，等待当前任务及队列中的任务全部执行完毕后退出；\n\n* ExecutorService.shutdownNow(): 通过Thread.interrupt()试图停止所有正在执行的线程，并不再处理还在队列中等待的任务。\n\n最优雅的退出方式是先执行shutdown()，再执行shutdownNow()，vjkit的`ThreadPoolUtil`进行了封装。\n\n注意，Thread.interrupt()并不保证能中断正在运行的线程，需编写可中断退出的Runnable，见规则5。\n\n----\n\n**Rule 5. 【强制】编写可停止的Runnable**\n\n执行Thread.interrupt()时，如果线程处于sleep(), wait(), join(), lock.lockInterruptibly()等blocking状态，会抛出InterruptedException，如果线程未处于上述状态，则将线程状态设为interrupted。\n\n因此，如下的代码无法中断线程:\n\n```java\npublic void run() {\n\n while (true) { //WRONG，无判断线程状态。\n sleep();\n }\n\n public void sleep() {\n try {\n\t Thread.sleep(1000);\n\t} catch (InterruptedException e) {\n\t logger.warn(\"Interrupted!\", e); //WRONG，吃掉了异常，interrupt状态未再传递\n\t}\n }\n}\n```\n\n\n**5.1 正确处理InterruptException**\n\n因为InterruptException异常是个必须处理的Checked Exception，所以run()所调用的子函数很容易吃掉异常并简单的处理成打印日志，但这等于停止了中断的传递，外层函数将收不到中断请求，继续原有循环或进入下一个堵塞。\n\n正确处理是调用`Thread.currentThread().interrupt();` 将中断往外传递。\n\n```java\n//RIGHT\npublic void myMethod() {\n try {\n ...\n } catch (InterruptedException e) {\n Thread.currentThread().interrupt();\n }\n}\n```\n\n* [Sonar-2142: \"InterruptedException\" should not be ignored](https://rules.sonarsource.com/java/RSPEC-2142)\n\n\n\n**5.2 主循环及进入阻塞状态前要判断线程状态**\n\n```java\n//RIGHT\npublic void run() {\n try {\n while (!Thread.isInterrupted()) {\n // do stuff\n }\n } catch (InterruptedException e) {\n logger.warn(\"Interrupted!\", e);\n }\n}\n```\n\n其他如Thread.sleep()的代码，在正式sleep前也会判断线程状态。\n\n----\n\n**Rule 6. 【强制】Runnable中必须捕获一切异常**\n\n如果Runnable中没有捕获RuntimeException而向外抛出，会发生下列情况：\n\n1) ScheduledExecutorService执行定时任务，任务会被中断，该任务将不再定时调度，但线程池里的线程还能用于其他任务。\n\n2) ExecutorService执行任务，当前线程会中断，线程池需要创建新的线程来响应后续任务。\n\n3) 如果没有在ThreadFactory设置自定义的UncaughtExceptionHanlder，则异常最终只打印在System.err，而不会打印在项目的日志中。\n\n\n因此建议自写的Runnable都要保证捕获异常; 如果是第三方的Runnable，可以将其再包裹一层vjkit中的SafeRunnable。\n\n```java\nexecutor.execute(ThreadPoolUtil.safeRunner(runner));\n```\n\n----\n\n**Rule 7. 【强制】全局的非线程安全的对象可考虑使用ThreadLocal存放**\n\n全局变量包括单例对象，static成员变量。\n\n著名的非线程安全类包括SimpleDateFormat，MD5/SHA1的Digest。\n\n对这些类，需要每次使用时创建。\n\n但如果创建有一定成本，可以使用ThreadLocal存放并重用。\n\nThreadLocal变量需要定义成static，并在每次使用前重置。\n\n```java\nprivate static final ThreadLocal SHA1_DIGEST = new ThreadLocal() {\n @Override\n protected MessageDigest initialValue() {\n try {\n\t return MessageDigest.getInstance(\"SHA\");\n\t} catch (NoSuchAlgorithmException e) {\n\t throw new RuntimeException(\"...\", e);\n\t}\n }\n};\n\npublic void digest(byte[] input) {\n MessageDigest digest = SHA1_DIGEST.get();\n digest.reset();\n return digest.digest(input);\n}\n```\n\n* [Sonar-2885: Non-thread-safe fields should not be static](https://rules.sonarsource.com/java/RSPEC-2885)\n* Facebook-Contrib: Correctness - Field is an instance based ThreadLocal variable\n\n----\n\n**Rule 8. 【推荐】缩短锁**\n\n1） 能锁区块，就不要锁整个方法体；\n\n```java\n//锁整个方法，等价于整个方法体内synchronized(this)\npublic synchronized boolean foo(){};\n\n//锁区块方法，仅对需要保护的原子操作的连续代码块进行加锁。\npublic boolean foo() {\n\tsynchronized(this) {\n\t\t...\n\t\t...\n\t}\n\t//other stuff\n}\n```\n\n2）能用对象锁，就不要用类锁。\n\n```java\n//对象锁，只影响使用同一个对象加锁的线程\nsynchronized(this) {\n\t...\n}\n\n//类锁，使用类对象作为锁对象，影响所有线程。\nsynchronized(A.class) {\n\t...\n}\n```\n\n----\n\n**Rule 10. 【推荐】选择分离锁，分散锁甚至无锁的数据结构**\n\n* 分离锁：\n\n1） 读写分离锁ReentrantReadWriteLock，读读之间不加锁，仅在写读和写写之间加锁；\n\n2） Array Base的queue一般是全局一把锁，而Linked Base的queue一般是队头队尾两把锁。\n\n\n\n* 分散锁（又称分段锁）：\n\n1）如JDK7的ConcurrentHashMap，分散成16把锁；\n\n2）对于经常写，少量读的计数器，推荐使用JDK8或vjkit封装的LongAdder对象性能更好（内部分散成多个counter，减少乐观锁的使用，取值时再相加所有counter）\n\n\n\n* 无锁的数据结构：\n\n1）完全无锁无等待的结构，如JDK8的ConcurrentHashMap；\n\n2）基于CAS的无锁有等待的数据结构，如AtomicXXX系列。\n\n----\n\n**Rule 11. 【推荐】基于ThreadLocal来避免锁**\n\n比如Random实例虽然是线程安全的，但其实它的seed的访问是有锁保护的。因此建议使用JDK7的ThreadLocalRandom，通过在每个线程里放一个seed来避免了加锁。\n\n----\n\n**Rule 12. 【推荐】规避死锁风险**\n\n对多个资源多个对象的加锁顺序要一致。\n\n如果无法确定完全避免死锁，可以使用带超时控制的tryLock语句加锁。\n\n----\n\n**Rule 13. 【推荐】volatile修饰符，AtomicXX系列的正确使用**\n\n多线程共享的对象，在单一线程内的修改并不保证对所有线程可见。使用volatile定义变量可以解决（解决了可见性）。\n\n但是如果多条线程并发进行基于当前值的修改，如并发的counter++，volatile则无能为力（解决不了原子性）。\n\n此时可使用Atomic*系列:\n\n```java\nAtomicInteger count = new AtomicInteger();\ncount.addAndGet(2);\n```\n\n但如果需要原子地同时对多个AtomicXXX的Counter进行操作，则仍然需要使用synchronized将改动代码块加锁。\n\n----\n\n**Rule 14. 【推荐】延时初始化的正确写法**\n\n通过双重检查锁（double-checked locking）实现延迟初始化存在隐患，需要将目标属性声明为volatile型，为了更高的性能，还要把volatile属性赋予给临时变量，写法复杂。\n\n所以如果只是想简单的延迟初始化，可用下面的静态类的做法，利用JDK本身的class加载机制保证唯一初始化。\n\n```java\nprivate static class LazyObjectHolder {\n static final LazyObject instance = new LazyObject();\n}\n\npublic void myMethod() {\n LazyObjectHolder.instance.doSomething();\n}\n```\n\n* [Sonar-2168: Double-checked locking should not be used](https://rules.sonarsource.com/java/RSPEC-2168)\n\n----\n"
},
{
"path": "docs/standard/chapter10.md",
"content": "# (十) 异常处理\n\n**Rule 1. 【强制】创建异常的消耗大，只用在真正异常的场景**\n\n构造异常时，需要获得整个调用栈，有一定消耗。\n\n不要用来做流程控制，条件控制，因为异常的处理效率比条件判断低。\n\n发生概率较高的条件，应该先进行检查规避，比如：IndexOutOfBoundsException，NullPointerException等，所以如果代码里捕获这些异常通常是个坏味道。\n\n```java\n//WRONG\ntry {\n return obj.method();\n} catch (NullPointerException e) {\n return false;\n}\n\n//RIGHT\nif (obj == null) {\n return false;\n}\n```\n\n* [Sonar-1696: \"NullPointerException\" should not be caught](https://rules.sonarsource.com/java/RSPEC-1696)\n\n----\n\n**Rule 2. 【推荐】在特定场景，避免每次构造异常**\n\n如上，异常的构造函数需要获得整个调用栈。\n\n如果异常频繁发生，且不需要打印完整的调用栈时，可以考虑绕过异常的构造函数。\n\n1） 如果异常的message不变，将异常定义为静态成员变量;\n\n下例定义静态异常，并简单定义一层的StackTrace。`ExceptionUtil`见vjkit。\n\n```java\nprivate static RuntimeException TIMEOUT_EXCEPTION = ExceptionUtil.setStackTrace(new RuntimeException(\"Timeout\"),\nMyClass.class, \"mymethod\");\n\n...\n\nthrow TIMEOUT_EXCEPTION;\n```\n\n\n2） 如果异常的message会变化，则对静态的异常实例进行clone()再修改message。\n\nException默认不是Cloneable的，`CloneableException`见vjkit。\n\n```java\nprivate static CloneableException TIMEOUT_EXCEPTION = new CloneableException(\"Timeout\") .setStackTrace(My.class,\n \"hello\");\n\n...\n\nthrow TIMEOUT_EXCEPTION.clone(\"Timeout for 40ms\");\n```\n\n\n3）自定义异常，也可以考虑重载fillStackTrace()为空函数，但相对没那么灵活，比如无法按场景指定一层的StackTrace。\n\n----\n\n**Rule 3. 【推荐】自定义异常，建议继承`RuntimeException`**\n\n详见《Clean Code》，争论已经结束，不再推荐原本初衷很好的CheckedException。\n\n因为CheckedException需要在抛出异常的地方，与捕获处理异常的地方之间，层层定义throws XXX来传递Exception，如果底层代码改动，将影响所有上层函数的签名，导致编译出错，对封装的破坏严重。对CheckedException的处理也给上层程序员带来了额外的负担。因此其他语言都没有CheckedException的设计。\n\n----\n\n**Rule 4. 【推荐】异常日志应包含排查问题的足够信息**\n\n异常信息应包含排查问题时足够的上下文信息。\n\n捕获异常并记录异常日志的地方，同样需要记录没有包含在异常信息中，而排查问题需要的信息，比如捕获处的上下文信息。\n\n```java\n//WRONG\nnew TimeoutException(\"timeout\");\nlogger.error(e.getMessage(), e);\n\n\n//RIGHT\nnew TimeoutException(\"timeout:\" + eclapsedTime + \", configuration:\" + configTime);\nlogger.error(\"user[\" + userId + \"] expired:\" + e.getMessage(), e);\n```\n\n* Facebook-Contrib: Style - Method throws exception with static message string\n\n----\n\n**Rule 5. 异常抛出的原则**\n\n\n**5.1 【推荐】尽量使用JDK标准异常，项目标准异常**\n\n尽量使用JDK标准的Runtime异常如`IllegalArgumentException`，`IllegalStateException`，`UnsupportedOperationException`，项目定义的Exception如`ServiceException`。\n\n\n**5.2 【推荐】根据调用者的需要来定义异常类，直接使用`RuntimeException`是允许的**\n\n是否定义独立的异常类，关键是调用者会如何处理这个异常，如果没有需要特别的处理，直接抛出RuntimeException也是允许的。\n\n----\n\n**Rule 6. 异常捕获的原则**\n\n**6.1 【推荐】按需要捕获异常，捕获`Exception`或`Throwable`是允许的**\n\n如果无特殊处理逻辑，统一捕获Exception统一处理是允许的。\n\n捕获Throwable是为了捕获Error类异常，包括其实无法处理的`OOM` `StackOverflow` `ThreadDeath`，以及类加载，反射时可能抛出的`NoSuchMethodError` `NoClassDefFoundError`等。\n\n\n**6.2【推荐】多个异常的处理逻辑一致时，使用JDK7的语法避免重复代码**\n\n```java\ntry {\n ...\n} catch (AException | BException | CException ex) {\n handleException(ex);\n}\n```\n\n* [Sonar-2147: Catches should be combined](https://rules.sonarsource.com/java/RSPEC-2147)\n\n----\n\n**Rule 7.异常处理的原则**\n\n**7.1 【强制】捕获异常一定要处理；如果故意捕获并忽略异常，须要注释写明原因**\n\n方便后面的阅读者知道，此处不是漏了处理。\n\n```java\n//WRONG\ntry {\n} catch(Exception e) {\n}\n\n//RIGHT\ntry {\n} catch(Exception ignoredExcetpion) {\n\t//continue the loop\n}\n```\n\n\n**7.2 【强制】异常处理不能吞掉原异常，要么在日志打印，要么在重新抛出的异常里包含原异常**\n\n```java\n //WRONG\nthrow new MyException(\"message\");\n\n//RIGHT 记录日志后抛出新异常，向上次调用者屏蔽底层异常\nlogger.error(\"message\", ex);\nthrow new MyException(\"message\");\n\n//RIGHT 传递底层异常\nthrow new MyException(\"message\", ex);\n```\n\n* [Sonar-1166: Exception handlers should preserve the original exceptions](https://rules.sonarsource.com/java/RSPEC-1166)，其中默认包含了InterruptedException, NumberFormatException，NoSuchMethodException等若干例外\n\n\n**7.3 【强制】如果不想处理异常，可以不进行捕获。但最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容**\n\n----\n\n**Rule 8. finally块的处理原则**\n\n**8.1 【强制】必须对资源对象、流对象进行关闭，或使用语法try-with-resource**\n\n关闭动作必需放在finally块，不能放在try块 或 catch块，这是经典的错误。\n\n更加推荐直接使用JDK7的try-with-resource语法自动关闭Closeable的资源，无需在finally块处理，避免潜在问题。\n\n```java\ntry (Writer writer = ...) {\n writer.append(content);\n}\n```\n\n\n**8.2 【强制】如果处理过程中有抛出异常的可能，也要做try-catch，否则finally块中抛出的异常，将代替try块中抛出的异常**\n\n```java\n//WRONG\ntry {\n ...\n throw new TimeoutException();\n} finally {\n file.close();//如果file.close()抛出IOException, 将代替TimeoutException\n}\n\n//RIGHT, 在finally块中try－catch\ntry {\n ...\n throw new TimeoutException();\n} finally {\n IOUtil.closeQuietly(file); //该方法中对所有异常进行了捕获\n}\n```\n\n* [Sonar-1163: Exceptions should not be thrown in finally blocks](https://rules.sonarsource.com/java/RSPEC-1163)\n\n\n**8.3 【强制】不能在finally块中使用return，finally块中的return将代替try块中的return及throw Exception**\n\n```java\n//WRONG\ntry {\n ...\n return 1;\n} finally {\n return 2; //实际return 2 而不是1\n}\n\ntry {\n ...\n throw TimeoutException();\n} finally {\n return 2; //实际return 2 而不是TimeoutException\n}\n```\n\n* [Sonar-1143: Jump statements should not occur in \"finally\" blocks](https://rules.sonarsource.com/java/RSPEC-1143)\n\n----\n"
},
{
"path": "docs/standard/chapter11.md",
"content": "# (十一) 日志规约\n\n**Rule 1. 【强制】应用中不可直接使用日志库（Log4j、Logback）中的API，而应使用日志框架SLF4J中的API**\n\n使用门面模式的日志框架，有利于维护各个类的日志处理方式统一。\n\n```java\nimport org.slf4j.Logger;\nimport org.slf4j.LoggerFactory;\n\nprivate static Logger logger = LoggerFactory.getLogger(Foo.class);\n```\n\n----\n\n**Rule 2. 【推荐】对不确定会否输出的日志，采用占位符或条件判断**\n\n```java\n//WRONG\nlogger.debug(\"Processing trade with id: \" + id + \" symbol: \" + symbol);\n```\n\n如果日志级别是info，上述日志不会打印，但是会执行1)字符串拼接操作，2)如果symbol是对象，还会执行toString()方法，浪费了系统资源，最终日志却没有打印。\n\n```java\n//RIGHT\nlogger.debug(\"Processing trade with id: {} symbol : {} \", id, symbol);\n```\n\n\n但如果symbol.getMessage()本身是个消耗较大的动作，占位符在此时并没有帮助，须要改为条件判断方式来完全避免它的执行。\n\n```java\n//WRONG\nlogger.debug(\"Processing trade with id: {} symbol : {} \", id, symbol.getMessage());\n\n//RIGHT\nif (logger.isDebugEnabled()) {\n logger.debug(\"Processing trade with id: \" + id + \" symbol: \" + symbol.getMessage());\n}\n```\n\n----\n\n**Rule 3. 【推荐】对确定输出，而且频繁输出的日志，采用直接拼装字符串的方式**\n\n如果这是一条WARN，ERROR级别的日志，或者确定输出的INFO级别的业务日志，直接字符串拼接，比使用占位符替换，更加高效。\n\nSlf4j的占位符并没有魔术，每次输出日志都要进行占位符的查找，字符串的切割与重新拼接。\n\n```java\n//RIGHT\nlogger.info(\"I am a business log with id: \" + id + \" symbol: \" + symbol);\n\n//RIGHT\nlogger.warn(\"Processing trade with id: \" + id + \" symbol: \" + symbol);\n```\n\n----\n\n**Rule 4. 【推荐】尽量使用异步日志**\n\n低延时的应用，使用异步输出的形式(以AsyncAppender串接真正的Appender)，可减少IO造成的停顿。\n\n需要正确配置异步队列长度及队列满的行为，是丢弃还是等待可用，业务上允许丢弃的尽量选丢弃。\n\n----\n\n**Rule 5. 【强制】禁止使用性能很低的System.out()打印日志信息**\n\n同理也禁止e.printStackTrace();\n\n例外: 应用启动和关闭时，担心日志框架还未初始化或已关闭。\n\n* [Sonar-106: Standard outputs should not be used directly to log anything](https://rules.sonarsource.com/java/RSPEC-106)\n* [Sonar-1148: Throwable.printStackTrace(...) should not be called](https://rules.sonarsource.com/java/RSPEC-1148)\n\n----\n\n**Rule 6. 【强制】禁止配置日志框架输出日志打印处的类名，方法名及行号的信息**\n\n日志框架在每次打印时，通过主动获得当前线程的StackTrace来获取上述信息的消耗非常大，尽量通过Logger名本身给出足够信息。\n\n----\n\n**Rule 7. 【推荐】谨慎地记录日志，避免大量输出无效日志，信息不全的日志**\n\n大量地输出无效日志，不利于系统性能，也不利于快速定位错误点。\n\n记录日志时请思考：这些日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？\n\n----\n\n**Rule 8. 【推荐】使用warn级别而不是error级别，记录外部输入参数错误的情况**\n\n如非必要，请不在此场景打印error级别日志，避免频繁报警。\n\nerror级别只记录系统逻辑出错、异常或重要的错误信息。\n\n----\n"
},
{
"path": "docs/standard/chapter12.md",
"content": "# (十二) 其他规约\n\n**Rule 1. 【参考】尽量不要让魔法值（即未经定义的数字或字符串常量）直接出现在代码中**\n\n```java\n //WRONG\n String key = \"Id#taobao_\"+tradeId;\n cache.put(key, value);\n```\n例外：-1,0,1,2,3 不认为是魔法数\n\n* [Sonar-109: Magic numbers should not be used](https://rules.sonarsource.com/java/RSPEC-109) 但现实中所谓魔法数还是太多，该规则不能被真正执行。\n\n----\n\n**Rule 2. 【推荐】时间获取的原则**\n\n1）获取当前毫秒数System.currentTimeMillis() 而不是new Date().getTime()，后者的消耗要大得多。\n\n\n2）如果要获得更精确的，且不受NTP时间调整影响的流逝时间，使用System.nanoTime()获得机器从启动到现在流逝的纳秒数。\n\n\n3）如果希望在测试用例中控制当前时间的值，则使用vjkit的Clock类封装，在测试和生产环境中使用不同的实现。\n\n----\n\n**Rule 3. 【推荐】变量声明尽量靠近使用的分支**\n\n不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法)，而是在第一次需要使用它时才声明。\n\n否则如果方法已经退出或进入其他分支，就白白初始化了变量。\n\n```java\n//WRONG\nFoo foo = new Foo();\n\nif(ok){\n\treturn;\n}\n\nfoo.bar();\n```\n\n----\n\n**Rule 4. 【推荐】不要像C那样一行里做多件事情**\n\n```java\n //WRONG\nfooBar.fChar = barFoo.lchar = 'c';\nargv++; argc--;\nint level, size;\n```\n\n* [Sonar-1659: Multiple variables should not be declared on the same line](https://rules.sonarsource.com/java/RSPEC-1659)\n\n----\n\n**Rule 5. 【推荐】不要为了性能而使用JNI本地方法**\n\nJava在JIT后并不比C代码慢，JNI方法因为要反复跨越JNI与Java的边界反而有额外的性能损耗。\n\n因此JNI方法仅建议用于调用\"JDK所没有包括的, 对特定操作系统的系统调用\"\n\n----\n\n**Rule 6. 【推荐】正确使用反射，减少性能损耗**\n\n获取Method/Field对象的性能消耗较大, 而如果对Method与Field对象进行缓存再反复调用，则并不会比直接调用类的方法与成员变量慢（前15次使用NativeAccessor，第15次后会生成GeneratedAccessorXXX，bytecode为直接调用实际方法）\n\n```java\n//用于对同一个方法多次调用\nprivate Method method = ....\n\npublic void foo(){\n method.invoke(obj, args);\n}\n\n//用于仅会对同一个方法单次调用\nReflectionUtils.invoke(obj, methodName, args);\n```\n\n----\n\n**Rule 7.【推荐】可降低优先级的常见代码检查规则**\n\n1. 接口内容的定义中，去除所有modifier，如public等。 (多个public也没啥，反正大家都看惯了)\n\n2. 工具类，定义private构造函数使其不能被实例化。（命名清晰的工具类，也没人会去实例化它，对静态方法通过类来访问也能避免实例化）\n\n----\n"
},
{
"path": "docs/standard/merge.bat",
"content": "@echo off\ntype README.md > vip-java-standard.md\ntype chapter01.md >> vip-java-standard.md\ntype chapter02.md >> vip-java-standard.md\ntype chapter03.md >> vip-java-standard.md\ntype chapter04.md >> vip-java-standard.md\ntype chapter05.md >> vip-java-standard.md\ntype chapter06.md >> vip-java-standard.md\ntype chapter07.md >> vip-java-standard.md\ntype chapter08.md >> vip-java-standard.md\ntype chapter09.md >> vip-java-standard.md\ntype chapter10.md >> vip-java-standard.md\ntype chapter11.md >> vip-java-standard.md\ntype chapter12.md >> vip-java-standard.md\ntype ali.md >> vip-java-standard.md\n\necho vip-java-standard.md is ready to be converted to pdf by any tools you like.\necho press any key to exit.\n\npause > nul\nexit\n"
},
{
"path": "docs/standard/merge.sh",
"content": "#!/bin/sh\n\ncat README.md > vip-java-standard.md\ncat chapter01.md >> vip-java-standard.md\ncat chapter02.md >> vip-java-standard.md\ncat chapter03.md >> vip-java-standard.md\ncat chapter04.md >> vip-java-standard.md\ncat chapter05.md >> vip-java-standard.md\ncat chapter06.md >> vip-java-standard.md\ncat chapter07.md >> vip-java-standard.md\ncat chapter08.md >> vip-java-standard.md\ncat chapter09.md >> vip-java-standard.md\ncat chapter10.md >> vip-java-standard.md\ncat chapter11.md >> vip-java-standard.md\ncat chapter12.md >> vip-java-standard.md\ncat ali.md >> vip-java-standard.md\n\necho vip-java-standard.md is ready to be converted to pdf by any tools you like.\n"
},
{
"path": "pom.xml",
"content": "\n\t4.0.0 \n\t\n\t\torg.sonatype.oss \n\t\toss-parent \n\t\t7 \n\t \n\n\tcom.vip.vjtools \n\tvjtools \n\t1.0.9-SNAPSHOT \n\tvjtools \n\tpom \n\n\tVJTools - VIP's core libraries and tools \n\n\t\n\t\tUTF-8 \n\t \n\n\n\t\n\t\t\n\t\t\tsonatype-nexus-snapshots \n\t\t\thttps://oss.sonatype.org/content/repositories/snapshots \n\t\t \n\t\t\n\t\t\tsonatype-nexus-releases \n\t\t\thttps://oss.sonatype.org/service/local/staging/deploy/maven2 \n\t\t \n\t \n\n\t\n\t\t\n\t\t\tjdk7 \n\t\t\t\n\t\t\t\t1.7 \n\t\t\t \n\t\t\t\n\t\t\t\tvjkit \n\t\t\t\tvjstar \n\t\t\t\tvjmap \n\t\t\t\tvjtop \n\t\t\t\tvjmxcli \n\t\t\t \n\t\t \n\n\t\t\n\t\t\tjdk8 \n\t\t\t\n\t\t\t\t1.8 \n\t\t\t \n\t\t\t\n\t\t\t\tvjkit \n\t\t\t\tvjstar \n\t\t\t\tvjmap \n\t\t\t\tvjtop \n\t\t\t\tvjmxcli \n\t\t\t\tstandard/sonar-vj \n\t\t\t \n\t\t \n\n\t\t\n\t\t\tjdk9 \n\t\t\t\n\t\t\t\t9 \n\t\t\t \n\t\t\t\n\t\t\t\tvjkit \n\t\t\t\tvjstar \n\t\t\t \n\t\t \n\n\t\t\n\t\t\trelease \n\t\t\t\n\t\t\t\tvjkit \n\t\t\t\tvjmap \n\t\t\t\tvjtop \n\t\t\t\tvjmxcli \n\t\t\t \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\torg.apache.maven.plugins \n\t\t\t\t\t\tmaven-release-plugin \n\t\t\t\t\t\t2.5.3 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\tv.@{project.version} \n\t\t\t\t\t\t \n\t\t\t\t\t \n\n\t\t\t\t\t\n\t\t\t\t\t\torg.apache.maven.plugins \n\t\t\t\t\t\tmaven-gpg-plugin \n\t\t\t\t\t\t1.6 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\tsign-artifacts \n\t\t\t\t\t\t\t\tverify \n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t\tsign \n\t\t\t\t\t\t\t\t \n\t\t\t\t\t\t\t \n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t \n\t\t\t \n\t\t \n\n\t \n\n\t\n\t\tscm:git:https://github.com/vipshop/vjtools.git \n\t\tscm:git:https://github.com/vipshop/vjtools.git \n\t\thttps://github.com/vipshop/vjtools \n\t v.1.0.2 \n \n\n\thttps://github.com/vipshop/vjtools \n\n\t\n\t\t\n\t\t\tApache License 2.0 \n\t\t\thttp://www.apache.org/licenses/LICENSE-2.0.txt \n\t\t\trepo \n\t\t \n\t \n\n\t\n\t\t\n\t\t\n\t\t\tcalvin \n\t\t\tCalvin Xiao \n\t\t\tcalvin.xiao at vipshop.com \n\t\t\t\n\t\t\t\tdeveloper \n\t\t\t \n\t\t\t+8 \n\t\t \n\t \n \n"
},
{
"path": "standard/README.md",
"content": "# Java Standard\n\n| Project | Description |\n| -------- | -------- |\n| [standard](https://vipshop.github.io/vjtools/#/standard/) | 唯品会Java开发手册 |\n| [code formatter](formatter) | IDE格式化模板 |\n| [sonar rule](sonar-vj) | Sonar规则定制示例 |"
},
{
"path": "standard/formatter/README.md",
"content": "# 公司通用代码格式化模板\n\n定制原因详见[《唯品会Java开发手册》 第二章:格式规约](https://vipshop.github.io/vjtools/#/standard/chapter02)，同时参考了一些Intellij IDEA默认模板的部分设置。\n\n将下列profile下载并导入IDE即可，导入后Profile名称为`vipshop2.0`：\n\n* [Eclipse Code Formatter Profile](https://raw.githubusercontent.com/vipshop/vjtools/master/standard/formatter/vjtools-code-conventions-eclipse.xml)\n* [Intellij Code Formatter Profile](https://raw.githubusercontent.com/vipshop/vjtools/master/standard/formatter/vjtools-code-conventions-idea.xml)\n\n因为Intellij导入Eclipse Profile存在问题，因此同时提供了两者的Profile。\n\n## 1. 与 Eclipse 4.6 的`Eclipse [build-in]`模板的区别\n\n* 不格式化JavaDoc\n* 注释行宽从80改为120\n* 打开format on/off标志\n* 参考Intellij IDEA默认模板的修改(见后)\n\n\n注意：Eclipse后来的build-in模板，代码行宽已经默认120。\n\n## 2. 与IDEA默认模板的区别\n\n\n本模板参考了Intellij IDEA默认模板中如下部分： \n\n* 简单的if语句，如果没有括号，则格式化成同一行。(勾选Control Statement->if else->Keep simple 'if' on one line)\n\n```java\nif (2 < 3) return;\n```\n\n当然，我们还是建议用括号，此处格式化成一行只是兜底的保护。\n\n* 主动输入的空行，最多可保留两行 (Blank Lines->Existing blank lines -> Number of empty lines to preserve 从1 改为 2)\n\n* switch 和 case 之间缩进(勾选Indentation-> Indent->Statements within switch body)\n\n```java\nswitch (a) {\n case 0:\n doCase0();\n break;\n default:\n doDefault(); \n}\n```\n\n* 数组构造时不要那么多空格(取消White Space->Arrays->Array Initializers->before opening brace,after opening brace,before closing brace)\n\n```java\nint[] a = new int[]{1, 2, 3}; \n```"
},
{
"path": "standard/formatter/vjtools-code-conventions-eclipse.xml",
"content": "\n\n\n\n\n\n\n\n \n \n"
},
{
"path": "standard/formatter/vjtools-code-conventions-idea.xml",
"content": "\n \n \n \n \n "
},
{
"path": "standard/sonar-vj/README.md",
"content": "# Sonar VJ 规则\n\n## 概述\n\n我们使用[Sonar](https://www.sonarqube.org/)代码检查工具来辅助[《唯品会Java开发手册》](https://vipshop.github.io/vjtools/#/standard/)的落地。选择的原因是它同时提供了服务端的公共报表，及IDE端的Sonar Lint插件，而且对比PMD与FindBugs，规则也相对容易定制。\n\n因为Sonar有些规则存在误报的情况，我们在力所能及的范围内对规则的实现进行了修改，以符合我们的规范。\n\n## 实现方式\n\n根据[Writing Custom Java Rules 101](https://docs.sonarqube.org/display/PLUG/Writing+Custom+Java+Rules+101)，从[Sample Project](https://github.com/SonarSource/sonar-custom-rules-examples/tree/master/java-custom-rules)复制创建，对[Sonar Java](https://github.com/SonarSource/sonar-java/tree/master/java-checks/src/main/java/org/sonar/java/checks)规则进行修改。\n\n\n## 使用方式\n\n官方的Sonar Java Plugin在不断更新，以下修改未必对应其最新版，仅作为修改示例供大家参考(修改部分在代码中以//VJ 标注)。 \n\n如果需要直接使用，编译后扔进sonar的lib目录，重启sonar后取消对原规则的检查，改为使用这些编号一样，带标题带VJ字样的规则即可。\n\n## 修改规则列表\n\n| 编号 | 等级 | 规则描述 | 修改 |\n| -------- | -------- |-------- | -------- |\n| 1068| Major | Unused \"private\" fields should be removed | 忽略由Lombok自动生成的getter/setter的类，私有变量不算无用变量 |\n| 1172| Major | Unused method parameters should be removed | 只检查private方法是否有无用参数, 忽略其他公共方法 |\n| 1166| Major | Exception handlers should preserve the original exceptions | 忽略异常变量名含ignore字样的检查，可以不进行处理，如catch(Exception ignore) |\n| 121| Major | Control structures should use curly braces | if语句忽略一般由IDE生成的equals()方法，以及if(condition) return;的单行模式|\n| 1068| Major |Limited dependence should be placed on operator precedence rules in expressions| 忽略三目运算符，不需要加括号来清晰优先级 |\n| 115| Minor| Constant names should comply with a naming convention| 忽略对枚举成员的全大写检查 |\n| 1312| Minor| IP addresses should not be hardcoded | 忽略对\"127.0.0.1\"的检查 |\n| 1291| Info | Track uses of \"NOSONAR\" comments| 忽略行内含 Exception/Throwable, System.in/System.err的//NOSOANR 检查 |\n"
},
{
"path": "standard/sonar-vj/pom.xml",
"content": "\n\n\t4.0.0 \n\n\tcom.vip \n\tsonar-vj \n\t1.0.9-SNAPSHOT \n\tsonar-plugin \n\n\t\n\t\t6.7.1 \n\t\t5.0.1.12818 \n\t\t1.21 \n\t\t2.6.2 \n\t\tUTF-8 \n\t \n\n\n\t\n\t\t\n\t\t\torg.sonarsource.sonarqube \n\t\t\tsonar-plugin-api \n\t\t\t${sonar.version} \n\t\t\tprovided \n\t\t \n\n\t\t\n\t\t\torg.sonarsource.java \n\t\t\tsonar-java-plugin \n\t\t\tsonar-plugin \n\t\t\t${java.plugin.version} \n\t\t\tprovided \n\t\t \n\n\t\t\n\t\t\torg.sonarsource.java \n\t\t\tjava-frontend \n\t\t\t${java.plugin.version} \n\t\t \n\n\t\t\n\t\t\torg.sonarsource.sslr-squid-bridge \n\t\t\tsslr-squid-bridge \n\t\t\t2.6.1 \n\t\t\t\n\t\t\t\t\n\t\t\t\t\torg.codehaus.sonar.sslr \n\t\t\t\t\tsslr-core \n\t\t\t\t \n\t\t\t\t\n\t\t\t\t\torg.codehaus.sonar \n\t\t\t\t\tsonar-plugin-api \n\t\t\t\t \n\t\t\t\t\n\t\t\t\t\torg.codehaus.sonar.sslr \n\t\t\t\t\tsslr-xpath \n\t\t\t\t \n\t\t\t\t\n\t\t\t\t\torg.slf4j \n\t\t\t\t\tjcl-over-slf4j \n\t\t\t\t \n\t\t\t\t\n\t\t\t\t\torg.slf4j \n\t\t\t\t\tslf4j-api \n\t\t\t\t \n\t\t\t \n\t\t \n\n\t\t\n\t\t\tcom.google.code.gson \n\t\t\tgson \n\t\t\t${gson.version} \n\t\t \n\n\t\t\n\t\t\torg.sonarsource.sslr \n\t\t\tsslr-testing-harness \n\t\t\t${sslr.version} \n\t\t\ttest \n\t\t \n\n\t\t\n\t\t\torg.slf4j \n\t\t\tslf4j-api \n\t\t\t1.6.2 \n\t\t \n\n\t\t\n\t\t\tjunit \n\t\t\tjunit \n\t\t\t4.11 \n\t\t\ttest \n\t\t \n\t\t\n\t\t\torg.assertj \n\t\t\tassertj-core \n\t\t\t3.6.1 \n\t\t\ttest \n\t\t \n\t\t\n\t\t\tch.qos.logback \n\t\t\tlogback-classic \n\t\t\t0.9.30 \n\t\t\ttest \n\t\t \n\t \n\n\t\n\t\t\n\n\t\t\t\n\t\t\t\torg.sonarsource.sonar-packaging-maven-plugin \n\t\t\t\tsonar-packaging-maven-plugin \n\t\t\t\t1.17 \n\t\t\t\ttrue \n\t\t\t\t\n\t\t\t\t\tvj-rules \n\t\t\t\t\tVJ Rules \n\t\t\t\t\tcom.vip.vjkit.sonarvj.SonarPlugin \n\t\t\t\t\tvip sonar java plugin \n\t\t\t\t\ttrue \n\t\t\t\t\t6.7 \n\t\t\t\t \n\t\t\t \n\n\n\t\t\t\n\t\t\t\torg.apache.maven.plugins \n\t\t\t\tmaven-compiler-plugin \n\t\t\t\t3.7.0 \n\t\t\t\t\n\t\t\t\t\t1.8 \n\t\t\t\t\t1.8 \n\t\t\t\t \n\t\t\t \n\t\t \n\t \n \n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarCheckRegistrar.java",
"content": "package com.vip.vjkit.sonarvj;\n\nimport com.vip.vjkit.sonarvj.checks.*;\nimport org.sonar.plugins.java.api.CheckRegistrar;\nimport org.sonar.plugins.java.api.JavaCheck;\n\nimport java.util.Arrays;\n\npublic class SonarCheckRegistrar implements CheckRegistrar {\n\n\t@Override\n\tpublic void register(RegistrarContext registrarContext) {\n\t\tregistrarContext.registerClassesForRepository(SonarDefinition.REPOSITORY_KEY, Arrays.asList(checkClasses()),\n\t\t\t\tArrays.asList(testCheckClasses()));\n\t}\n\n\tpublic static Class[] checkClasses() {\n\t\treturn new Class[] { BadConstantNameCheck.class, OperatorPrecedenceCheck.class,\n\t\t\t\tUnusedMethodParameterCheck.class, UnusedPrivateFieldCheck.class, MissingCurlyBracesCheck.class,\n\t\t\t\tHardcodedIpCheck.class, NoSonarCheck.class, CatchUsesExceptionWithContextCheck.class };\n\t}\n\n\tpublic static Class[] testCheckClasses() {\n\t\treturn new Class[] {};\n\t}\n}"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarDefinition.java",
"content": "\npackage com.vip.vjkit.sonarvj;\n\nimport com.google.common.annotations.VisibleForTesting;\nimport com.google.common.collect.Iterables;\nimport com.google.common.io.Resources;\nimport com.google.gson.Gson;\nimport org.apache.commons.lang.StringUtils;\nimport org.sonar.api.rule.RuleStatus;\nimport org.sonar.api.rules.RuleType;\nimport org.sonar.api.server.debt.DebtRemediationFunction;\nimport org.sonar.api.server.rule.RulesDefinition;\nimport org.sonar.api.server.rule.RulesDefinitionAnnotationLoader;\nimport org.sonar.api.utils.AnnotationUtils;\nimport org.sonar.check.Cardinality;\nimport org.sonar.squidbridge.annotations.RuleTemplate;\n\nimport javax.annotation.Nullable;\nimport java.io.IOException;\nimport java.net.URL;\nimport java.nio.charset.StandardCharsets;\nimport java.util.List;\nimport java.util.Locale;\n\n/**\n * Declare rule metadata in server repository of rules.\n * That allows to list the rules in the page \"Rules\".\n */\npublic class SonarDefinition implements RulesDefinition {\n\n // don't change that because the path is hard coded in CheckVerifier\n private static final String RESOURCE_BASE_PATH = \"/com/vip/java/rules\";\n\n public static final String REPOSITORY_KEY = \"v-squid\";\n\n private final Gson gson = new Gson();\n\n @Override\n public void define(Context context) {\n NewRepository repository = context\n .createRepository(REPOSITORY_KEY, \"java\")\n .setName(\"VIPAnalyzer \");\n\n List checks = SonarRulesList.getChecks();\n new RulesDefinitionAnnotationLoader().load(repository, Iterables.toArray(checks, Class.class));\n\n for (Class ruleClass : checks) {\n newRule(ruleClass, repository);\n }\n repository.done();\n }\n\n @VisibleForTesting\n protected void newRule(Class ruleClass, NewRepository repository) {\n\n org.sonar.check.Rule ruleAnnotation = AnnotationUtils.getAnnotation(ruleClass, org.sonar.check.Rule.class);\n if (ruleAnnotation == null) {\n throw new IllegalArgumentException(\"No Rule annotation was found on \" + ruleClass);\n }\n String ruleKey = ruleAnnotation.key();\n if (StringUtils.isEmpty(ruleKey)) {\n throw new IllegalArgumentException(\"No key is defined in Rule annotation of \" + ruleClass);\n }\n NewRule rule = repository.rule(ruleKey);\n if (rule == null) {\n throw new IllegalStateException(\"No rule was created for \" + ruleClass + \" in \" + repository.key());\n }\n ruleMetadata(ruleClass, rule);\n\n rule.setTemplate(AnnotationUtils.getAnnotation(ruleClass, RuleTemplate.class) != null);\n if (ruleAnnotation.cardinality() == Cardinality.MULTIPLE) {\n throw new IllegalArgumentException(\"Cardinality is not supported, use the RuleTemplate annotation instead for \" + ruleClass);\n }\n }\n\n private String ruleMetadata(Class ruleClass, NewRule rule) {\n String metadataKey = rule.key();\n org.sonar.java.RspecKey rspecKeyAnnotation = AnnotationUtils.getAnnotation(ruleClass, org.sonar.java.RspecKey.class);\n if (rspecKeyAnnotation != null) {\n metadataKey = rspecKeyAnnotation.value();\n rule.setInternalKey(metadataKey);\n }\n addHtmlDescription(rule, metadataKey);\n addMetadata(rule, metadataKey);\n return metadataKey;\n }\n\n private void addMetadata(NewRule rule, String metadataKey) {\n URL resource = SonarDefinition.class.getResource(RESOURCE_BASE_PATH + \"/\" + metadataKey + \"_java.json\");\n if (resource != null) {\n RuleMetatada metatada = gson.fromJson(readResource(resource), RuleMetatada.class);\n rule.setSeverity(metatada.defaultSeverity.toUpperCase(Locale.US));\n rule.setName(metatada.title);\n rule.addTags(metatada.tags);\n rule.setType(RuleType.valueOf(metatada.type));\n rule.setStatus(RuleStatus.valueOf(metatada.status.toUpperCase(Locale.US)));\n if (metatada.remediation != null) {\n rule.setDebtRemediationFunction(metatada.remediation.remediationFunction(rule.debtRemediationFunctions()));\n rule.setGapDescription(metatada.remediation.linearDesc);\n }\n }\n }\n\n private static void addHtmlDescription(NewRule rule, String metadataKey) {\n URL resource = SonarDefinition.class.getResource(RESOURCE_BASE_PATH + \"/\" + metadataKey + \"_java.html\");\n if (resource != null) {\n rule.setHtmlDescription(readResource(resource));\n }\n }\n\n private static String readResource(URL resource) {\n try {\n return Resources.toString(resource, StandardCharsets.UTF_8);\n } catch (IOException e) {\n throw new IllegalStateException(\"Failed to read: \" + resource, e);\n }\n }\n\n private static class RuleMetatada {\n String title;\n String status;\n @Nullable\n Remediation remediation;\n\n String type;\n String[] tags;\n String defaultSeverity;\n }\n\n private static class Remediation {\n String func;\n String constantCost;\n String linearDesc;\n String linearOffset;\n String linearFactor;\n\n public DebtRemediationFunction remediationFunction(DebtRemediationFunctions drf) {\n if (func.startsWith(\"Constant\")) {\n return drf.constantPerIssue(constantCost.replace(\"mn\", \"min\"));\n }\n if (\"Linear\".equals(func)) {\n return drf.linear(linearFactor.replace(\"mn\", \"min\"));\n }\n return drf.linearWithOffset(linearFactor.replace(\"mn\", \"min\"), linearOffset.replace(\"mn\", \"min\"));\n }\n }\n\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarPlugin.java",
"content": "package com.vip.vjkit.sonarvj;\n\nimport org.sonar.api.Plugin;\n\n/**\n * Created by cloud.huang on 18/1/5.\n */\npublic class SonarPlugin implements Plugin {\n @Override\n public void define(Context context) {\n context.addExtension(SonarDefinition.class);\n context.addExtension(SonarCheckRegistrar.class);\n }\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarRulesList.java",
"content": "package com.vip.vjkit.sonarvj;\n\nimport com.google.common.collect.ImmutableList;\nimport com.vip.vjkit.sonarvj.checks.*;\nimport org.sonar.plugins.java.api.JavaCheck;\n\nimport java.util.List;\n\n/**\n * Created by cloud.huang on 18/1/5.\n */\npublic class SonarRulesList {\n\n public static List getChecks() {\n return ImmutableList.builder().addAll(getJavaChecks()).addAll(getJavaTestChecks()).build();\n }\n\n public static List> getJavaChecks() {\n return ImmutableList.>builder()\n .add(BadConstantNameCheck.class)\n .add(OperatorPrecedenceCheck.class)\n .add(UnusedPrivateFieldCheck.class)\n .add(UnusedMethodParameterCheck.class)\n .add(MissingCurlyBracesCheck.class)\n .add(HardcodedIpCheck.class)\n .add(NoSonarCheck.class)\n .add(CatchUsesExceptionWithContextCheck.class)\n .build();\n }\n\n public static List> getJavaTestChecks() {\n return ImmutableList.>builder()\n .build();\n }\n\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/BadConstantNameCheck.java",
"content": "/*\n * SonarQube Java Copyright (C) 2012-2018 SonarSource SA mailto:info AT sonarsource DOT com\n *\n * This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General\n * Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any\n * later version.\n *\n * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied\n * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more\n * details.\n *\n * You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to\n * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.\n */\npackage com.vip.vjkit.sonarvj.checks;\n\nimport java.util.List;\nimport java.util.regex.Pattern;\n\nimport org.sonar.check.Rule;\nimport org.sonar.check.RuleProperty;\nimport org.sonar.java.checks.serialization.SerializableContract;\nimport org.sonar.java.resolve.JavaType;\nimport org.sonar.plugins.java.api.IssuableSubscriptionVisitor;\nimport org.sonar.plugins.java.api.JavaFileScannerContext;\nimport org.sonar.plugins.java.api.semantic.Type;\nimport org.sonar.plugins.java.api.tree.ClassTree;\nimport org.sonar.plugins.java.api.tree.Modifier;\nimport org.sonar.plugins.java.api.tree.ModifierKeywordTree;\nimport org.sonar.plugins.java.api.tree.Tree;\nimport org.sonar.plugins.java.api.tree.VariableTree;\n\nimport com.google.common.collect.ImmutableList;\n\n/**\n * 不对枚举的命名进行检查\n * \n * 另顺便修正了isConstantTyp一个BUG,加强了报错信息\n * \n * https://github.com/SonarSource/sonar-java/blob/master/java-checks/src/main/java/org/sonar/java/checks/naming/BadConstantNameCheck.java\n * \n * 0d54578 Jan 8, 2018\n */\n@Rule(key = \"S115\")\npublic class BadConstantNameCheck extends IssuableSubscriptionVisitor {\n\n\tprivate static final String DEFAULT_FORMAT = \"^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$\";\n\t@RuleProperty(key = \"format\", description = \"Regular expression used to check the constant names against.\", defaultValue = \"\"\n\t\t\t+ DEFAULT_FORMAT)\n\tpublic String format = DEFAULT_FORMAT;\n\n\tprivate Pattern pattern = null;\n\n\t@Override\n\tpublic List nodesToVisit() {\n\t\t// VJ Replace\n\t\treturn ImmutableList.of(Tree.Kind.CLASS, Tree.Kind.INTERFACE, Tree.Kind.ANNOTATION_TYPE);\n\t\t// return ImmutableList.of(Tree.Kind.CLASS, Tree.Kind.ENUM, Tree.Kind.INTERFACE, Tree.Kind.ANNOTATION_TYPE);\n\t}\n\n\t@Override\n\tpublic void scanFile(JavaFileScannerContext context) {\n\t\tif (pattern == null) {\n\t\t\tpattern = Pattern.compile(format, Pattern.DOTALL);\n\t\t}\n\t\tsuper.scanFile(context);\n\t}\n\n\t@Override\n\tpublic void visitNode(Tree tree) {\n\t\tClassTree classTree = (ClassTree) tree;\n\t\tfor (Tree member : classTree.members()) {\n\t\t\tif (member.is(Tree.Kind.VARIABLE) && hasSemantic()) {\n\t\t\t\tVariableTree variableTree = (VariableTree) member;\n\t\t\t\tType symbolType = variableTree.type().symbolType();\n\t\t\t\t if (isConstantType(symbolType) && (classTree.is(Tree.Kind.INTERFACE, Tree.Kind.ANNOTATION_TYPE) || isStaticFinal(variableTree))) {\n\t\t\t checkName(variableTree);\n\t\t\t }\n\t\t\t}\n\t\t\t// VJ Remove //\n\t\t\t// else if (member.is(Tree.Kind.ENUM_CONSTANT)) {\n\t\t\t// checkName((VariableTree) member);\n\t\t\t// }\n\t\t}\n\t}\n\n\t//VJ: 加上symbolType instanceof JavaType的判断，防止数组转换出错\n\tprivate static boolean isConstantType(Type symbolType) {\n\t\treturn symbolType.isPrimitive() || symbolType.is(\"java.lang.String\") || symbolType.is(\"java.lang.Byte\") ||\n\t\t\t\tsymbolType.is(\"java.lang.Character\") ||\n\t\t\t\tsymbolType.is(\"java.lang.Short\") ||\n\t\t\t\tsymbolType.is(\"java.lang.Integer\") ||\n\t\t\t\tsymbolType.is(\"java.lang.Long\") ||\n\t\t\t\tsymbolType.is(\"java.lang.Float\") ||\n\t\t\t\tsymbolType.is(\"java.lang.Double\") ||\n\t\t\t\tsymbolType.is(\"java.lang.Boolean\");\n\t}\n\n\tprivate void checkName(VariableTree variableTree) {\n\t\tString name = variableTree.simpleName().name();\n\t\tif (!SerializableContract.SERIAL_VERSION_UID_FIELD.equals(name)\n\t\t\t\t&& !pattern.matcher(name).matches()) {\n\t\t\t//VJ 报错信息加上变量名\n\t\t\treportIssue(variableTree.simpleName(),\n\t\t\t\t\t\"Rename this constant name '\" + name + \"' to match the regular expression '\" + format + \"'.\");\n\t\t}\n\t}\n\n\tprivate static boolean isStaticFinal(VariableTree variableTree) {\n\t\tboolean isStatic = false;\n\t\tboolean isFinal = false;\n\t\tfor (ModifierKeywordTree modifierKeywordTree : variableTree.modifiers().modifiers()) {\n\t\t\tModifier modifier = modifierKeywordTree.modifier();\n\t\t\tif (modifier == Modifier.STATIC) {\n\t\t\t\tisStatic = true;\n\t\t\t}\n\t\t\tif (modifier == Modifier.FINAL) {\n\t\t\t\tisFinal = true;\n\t\t\t}\n\t\t}\n\t\treturn isStatic && isFinal;\n\t}\n\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/CatchUsesExceptionWithContextCheck.java",
"content": "package com.vip.vjkit.sonarvj.checks;\n\nimport com.google.common.base.Splitter;\nimport com.google.common.collect.Iterables;\nimport com.google.common.collect.Lists;\nimport org.apache.commons.lang.StringUtils;\nimport org.sonar.check.Rule;\nimport org.sonar.check.RuleProperty;\nimport org.sonar.java.checks.helpers.ExpressionsHelper;\nimport org.sonar.java.matcher.MethodMatcher;\nimport org.sonar.java.matcher.TypeCriteria;\nimport org.sonar.plugins.java.api.JavaFileScanner;\nimport org.sonar.plugins.java.api.JavaFileScannerContext;\nimport org.sonar.plugins.java.api.semantic.Symbol;\nimport org.sonar.plugins.java.api.tree.*;\nimport org.sonar.plugins.java.api.tree.Tree.Kind;\n\nimport java.util.*;\n\n/**\n * catch异常的变量名包含ignore，忽略检查\n */\n@Rule(key = \"S1166\")\npublic class CatchUsesExceptionWithContextCheck extends BaseTreeVisitor implements JavaFileScanner {\n\n private static final String EXCLUDED_EXCEPTION_TYPE = \"java.lang.InterruptedException, \" +\n \"java.lang.NumberFormatException, \" +\n \"java.lang.NoSuchMethodException, \" +\n \"java.text.ParseException, \" +\n \"java.net.MalformedURLException, \" +\n \"java.time.format.DateTimeParseException\";\n\n @RuleProperty(\n key = \"exceptions\",\n description = \"List of exceptions which should not be checked\",\n defaultValue = \"\" + EXCLUDED_EXCEPTION_TYPE)\n public String exceptionsCommaSeparated = EXCLUDED_EXCEPTION_TYPE;\n\n private JavaFileScannerContext context;\n private Deque> validUsagesStack;\n private Iterable exceptions;\n private List exceptionIdentifiers;\n private Set excludedCatchTrees = new HashSet<>();\n\n @Override\n public void scanFile(JavaFileScannerContext context) {\n this.context = context;\n validUsagesStack = new ArrayDeque<>();\n exceptions = Splitter.on(\",\").trimResults().split(exceptionsCommaSeparated);\n exceptionIdentifiers = Lists.newArrayList();\n for (String exception : exceptions) {\n exceptionIdentifiers.add(exception.substring(exception.lastIndexOf('.') + 1));\n }\n if (context.getSemanticModel() != null) {\n scan(context.getTree());\n }\n excludedCatchTrees.clear();\n }\n\n @Override\n public void visitTryStatement(TryStatementTree tree) {\n if (containsEnumValueOf(tree.block())) {\n tree.catches().stream()\n .filter(c -> c.parameter().symbol().type().is(\"java.lang.IllegalArgumentException\"))\n .findAny()\n .ifPresent(excludedCatchTrees::add);\n }\n super.visitTryStatement(tree);\n }\n\n private static boolean containsEnumValueOf(Tree tree) {\n EnumValueOfVisitor visitor = new EnumValueOfVisitor();\n tree.accept(visitor);\n return visitor.hasEnumValueOf;\n }\n\n private static class EnumValueOfVisitor extends BaseTreeVisitor {\n private static final MethodMatcher ENUM_VALUE_OF = MethodMatcher.create()\n .typeDefinition(TypeCriteria.subtypeOf(\"java.lang.Enum\"))\n .name(\"valueOf\")\n .withAnyParameters();\n private boolean hasEnumValueOf = false;\n\n @Override\n public void visitMethodInvocation(MethodInvocationTree tree) {\n if (ENUM_VALUE_OF.matches(tree)) {\n hasEnumValueOf = true;\n }\n super.visitMethodInvocation(tree);\n }\n\n @Override\n public void visitClass(ClassTree tree) {\n // skip anonymous classes\n }\n\n @Override\n public void visitLambdaExpression(LambdaExpressionTree lambdaExpressionTree) {\n // skip lambdas\n }\n }\n\n @Override\n public void visitCatch(CatchTree tree) {\n if (!isExcludedType(tree.parameter().type()) && !excludedCatchTrees.contains(tree)) {\n Symbol exception = tree.parameter().symbol();\n //catch异常的变量名包含ignore，忽略检查\n if (StringUtils.containsIgnoreCase(exception.name(), \"ignore\")) {\n return;\n }\n validUsagesStack.addFirst(Lists.newArrayList(exception.usages()));\n super.visitCatch(tree);\n Collection usages = validUsagesStack.pop();\n if (usages.isEmpty()) {\n context.reportIssue(this, tree.parameter(), \"Either log or rethrow this exception.\");\n }\n }\n }\n\n @Override\n public void visitMemberSelectExpression(MemberSelectExpressionTree tree) {\n IdentifierTree identifier = null;\n ExpressionTree expression = tree.expression();\n if (expression.is(Kind.IDENTIFIER)) {\n identifier = (IdentifierTree) expression;\n } else if (expression.is(Kind.PARENTHESIZED_EXPRESSION) && ((ParenthesizedTree) expression).expression().is(Kind.IDENTIFIER)) {\n identifier = (IdentifierTree) ((ParenthesizedTree) expression).expression();\n }\n if (!validUsagesStack.isEmpty() && identifier != null) {\n Iterator> iterator = validUsagesStack.iterator();\n while (iterator.hasNext()) {\n iterator.next().remove(identifier);\n }\n }\n super.visitMemberSelectExpression(tree);\n\n }\n\n private boolean isExcludedType(Tree tree) {\n return isUnqualifiedExcludedType(tree) ||\n isQualifiedExcludedType(tree);\n }\n\n private boolean isUnqualifiedExcludedType(Tree tree) {\n return tree.is(Kind.IDENTIFIER) &&\n exceptionIdentifiers.contains(((IdentifierTree) tree).name());\n }\n\n private boolean isQualifiedExcludedType(Tree tree) {\n if (!tree.is(Kind.MEMBER_SELECT)) {\n return false;\n }\n return Iterables.contains(exceptions, concatenate((MemberSelectExpressionTree) tree));\n }\n \n public static String concatenate(ExpressionTree tree) {\n if(tree == null) {\n return \"\";\n }\n Deque pieces = new LinkedList<>();\n ExpressionTree expr = tree;\n while (expr.is(Tree.Kind.MEMBER_SELECT)) {\n MemberSelectExpressionTree mse = (MemberSelectExpressionTree) expr;\n pieces.push(mse.identifier().name());\n pieces.push(\".\");\n expr = mse.expression();\n }\n if (expr.is(Tree.Kind.IDENTIFIER)) {\n IdentifierTree idt = (IdentifierTree) expr;\n pieces.push(idt.name());\n }\n\n StringBuilder sb = new StringBuilder();\n for (String piece: pieces) {\n sb.append(piece);\n }\n return sb.toString();\n }\n\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/HardcodedIpCheck.java",
"content": "package com.vip.vjkit.sonarvj.checks;\n\nimport com.google.common.base.Splitter;\n\nimport org.sonar.check.Rule;\nimport org.sonar.java.model.LiteralUtils;\nimport org.sonar.plugins.java.api.JavaFileScanner;\nimport org.sonar.plugins.java.api.JavaFileScannerContext;\nimport org.sonar.plugins.java.api.tree.BaseTreeVisitor;\nimport org.sonar.plugins.java.api.tree.LiteralTree;\nimport org.sonar.plugins.java.api.tree.Tree;\n\nimport java.util.regex.Matcher;\nimport java.util.regex.Pattern;\n/**\n * 忽略127.0.0.1\n * \n * https://github.com/SonarSource/sonar-java/blob/master/java-checks/src/main/java/org/sonar/java/checks/HardcodedIpCheck.java\n * \n * 0d54578 Jan 8, 2018\n */\n@Rule(key = \"S1313\")\npublic class HardcodedIpCheck extends BaseTreeVisitor implements JavaFileScanner {\n\n\tprivate static final Matcher IP = Pattern\n\t\t\t.compile(\"([^\\\\d.]*\\\\/)?(?(?:\\\\d{1,3}\\\\.){3}\\\\d{1,3}(?!\\\\d|\\\\.))(\\\\/.*)?\").matcher(\"\");\n\n\tprivate JavaFileScannerContext context;\n\n\t@Override\n\tpublic void scanFile(final JavaFileScannerContext context) {\n\t\tthis.context = context;\n\t\tscan(context.getTree());\n\t}\n\n\t@Override\n\tpublic void visitLiteral(LiteralTree tree) {\n\t\tif (tree.is(Tree.Kind.STRING_LITERAL)) {\n\t\t\tString value = LiteralUtils.trimQuotes(tree.value());\n\t\t\tIP.reset(value);\n\t\t\tif (IP.matches()) {\n\t\t\t\tString ip = IP.group(\"ip\");\n\n\t\t\t\t// VJ:ADD 忽略127.0.0.1\n\t\t\t\tif (\"127.0.0.1\".equals(ip)) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// VJ:END\n\t\t\t\tif (areAllBelow256(Splitter.on('.').split(ip))) {\n\t\t\t\t\tcontext.reportIssue(this, tree, \"Make this IP \\\"\" + ip + \"\\\" address configurable.\");\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate static boolean areAllBelow256(Iterable numbersAsStrings) {\n\t\tfor (String numberAsString : numbersAsStrings) {\n\t\t\tif (Integer.valueOf(numberAsString) > 255) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn true;\n\t}\n\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/MissingCurlyBracesCheck.java",
"content": "package com.vip.vjkit.sonarvj.checks;\n\nimport com.google.common.collect.ImmutableList;\nimport org.sonar.check.Rule;\nimport org.sonar.plugins.java.api.IssuableSubscriptionVisitor;\nimport org.sonar.plugins.java.api.tree.*;\n\nimport java.util.List;\n\n/**\n * 1. equals 方法忽略if的检查 2. if(conditon) return true; 忽略在同一行的模式\n * \n * https://github.com/SonarSource/sonar-java/blob/master/java-checks/src/main/java/org/sonar/java/checks/MissingCurlyBracesCheck.java\n * \n * 0d54578 Jan 8, 2018\n */\n@Rule(key = \"S121\")\npublic class MissingCurlyBracesCheck extends IssuableSubscriptionVisitor {\n\n\t@Override\n\tpublic List nodesToVisit() {\n\t\treturn ImmutableList.of(Tree.Kind.IF_STATEMENT, Tree.Kind.FOR_EACH_STATEMENT, Tree.Kind.FOR_STATEMENT,\n\t\t\t\tTree.Kind.WHILE_STATEMENT, Tree.Kind.DO_STATEMENT);\n\t}\n\n\t@Override\n\tpublic void visitNode(Tree tree) {\n\t\tswitch (tree.kind()) {\n\t\tcase WHILE_STATEMENT:\n\t\t\tWhileStatementTree whileStatementTree = (WhileStatementTree) tree;\n\t\t\tcheckStatement(whileStatementTree.whileKeyword(), whileStatementTree.statement());\n\t\t\tbreak;\n\t\tcase DO_STATEMENT:\n\t\t\tDoWhileStatementTree doWhileStatementTree = (DoWhileStatementTree) tree;\n\t\t\tcheckStatement(doWhileStatementTree.doKeyword(), doWhileStatementTree.statement());\n\t\t\tbreak;\n\t\tcase FOR_STATEMENT:\n\t\t\tForStatementTree forStatementTree = (ForStatementTree) tree;\n\t\t\tcheckStatement(forStatementTree.forKeyword(), forStatementTree.statement());\n\t\t\tbreak;\n\t\tcase FOR_EACH_STATEMENT:\n\t\t\tForEachStatement forEachStatement = (ForEachStatement) tree;\n\t\t\tcheckStatement(forEachStatement.forKeyword(), forEachStatement.statement());\n\t\t\tbreak;\n\t\tcase IF_STATEMENT:\n\t\t\tcheckIfStatement((IfStatementTree) tree);\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tbreak;\n\t\t}\n\t}\n\n\tprivate void checkIfStatement(IfStatementTree ifStmt) {\n\t\t// equals 方法忽略if的检查, 如果if 与处理函数在同一行忽略。\n\t\tif (isInEqualsMethod(ifStmt)) {\n\t\t\treturn;\n\t\t}\n\n\t\tif (!isSameLine(ifStmt)) {\n\t\t\tcheckStatement(ifStmt.ifKeyword(), ifStmt.thenStatement());\n\t\t}\n\n\t\tStatementTree elseStmt = ifStmt.elseStatement();\n\t\tif (elseStmt != null && !elseStmt.is(Tree.Kind.IF_STATEMENT)) {\n\t\t\tcheckStatement(ifStmt.elseKeyword(), elseStmt);\n\t\t}\n\t}\n\n\tprivate boolean isSameLine(IfStatementTree ifStmt) {\n\t\tStatementTree thenStmt = ifStmt.thenStatement();\n\t\tif (thenStmt.is(Tree.Kind.BLOCK)) {\n\t\t\treturn false;\n\t\t}\n\n\t\treturn ifStmt.firstToken().line() == thenStmt.firstToken().line();\n\t}\n\n\tprivate boolean isInEqualsMethod(IfStatementTree ifStmt) {\n\t\tTree tree = ifStmt.parent();\n\t\twhile (tree != null && !(tree instanceof MethodTree)) {\n\t\t\ttree = tree.parent();\n\t\t}\n\n\t\tif (tree == null) {\n\t\t\treturn false;\n\t\t}\n\n\t\tMethodTree methodTree = (MethodTree) tree;\n\t\tif (methodTree.simpleName().toString().equals(\"equals\")) {\n\t\t\treturn true;\n\t\t}\n\t\treturn false;\n\t}\n\n\tprivate void checkStatement(SyntaxToken reportToken, StatementTree statement) {\n\t\tif (!statement.is(Tree.Kind.BLOCK)) {\n\t\t\treportIssue(reportToken, \"Missing curly brace.\");\n\t\t}\n\t}\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/NoSonarCheck.java",
"content": "/*\n * SonarQube Java Copyright (C) 2012-2018 SonarSource SA mailto:info AT sonarsource DOT com\n *\n * This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General\n * Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any\n * later version.\n *\n * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied\n * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more\n * details.\n *\n * You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to\n * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.\n */\npackage com.vip.vjkit.sonarvj.checks;\n\nimport java.util.Collections;\nimport java.util.List;\n\nimport org.sonar.check.Rule;\nimport org.sonar.java.RspecKey;\nimport org.sonar.plugins.java.api.IssuableSubscriptionVisitor;\nimport org.sonar.plugins.java.api.JavaFileScannerContext;\nimport org.sonar.plugins.java.api.tree.Tree;\n\n/**\n * 忽略在system.out, e.printStacktrace, catch exception 后设置的NONSAR\n * \n * 基于TooLongLineCheck完全重写\n */\n@Rule(key = \"NoSonar\")\n@RspecKey(\"S1291\")\npublic class NoSonarCheck extends IssuableSubscriptionVisitor {\n\tprivate static final String PATTERN = \"NOSONAR\";\n\tprivate static final String[] IGNORE_PATTERNS = new String[] { \"Exception\", \"Throwable\", \"System.out\", \"System.err\",\n\t\t\t\"printStackTrace\" };\n\tprivate static final String MESSAGE = \"//NOSONAR found: \";\n\n\t@Override\n\tpublic List nodesToVisit() {\n\t\treturn Collections.emptyList();\n\t}\n\n\t@Override\n\tpublic void scanFile(JavaFileScannerContext context) {\n\t\tsuper.context = context;\n\t\tsuper.scanFile(context);\n\t\tvisitFile();\n\t}\n\n\tprivate void visitFile() {\n\t\tList lines = context.getFileLines();\n\t\tfor (int i = 0; i < lines.size(); i++) {\n\t\t\tString line = lines.get(i);\n\t\t\tif (line.contains(PATTERN) && !ignoredLine(line)) {\n\t\t\t\taddIssue(i + 1, MESSAGE + line);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate boolean ignoredLine(String line) {\n\t\tfor (String ignorePattern : IGNORE_PATTERNS) {\n\t\t\tif (line.contains(ignorePattern)) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t}\n\t\treturn false;\n\t}\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/OperatorPrecedenceCheck.java",
"content": "/*\n * SonarQube Java\n * Copyright (C) 2012-2017 SonarSource SA\n * mailto:info AT sonarsource DOT com\n *\n * This program is free software; you can redistribute it and/or\n * modify it under the terms of the GNU Lesser General Public\n * License as published by the Free Software Foundation; either\n * version 3 of the License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\n * Lesser General Public License for more details.\n *\n * You should have received a copy of the GNU Lesser General Public License\n * along with this program; if not, write to the Free Software Foundation,\n * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.\n */\npackage com.vip.vjkit.sonarvj.checks;\n\nimport com.google.common.collect.HashBasedTable;\nimport com.google.common.collect.Iterables;\nimport com.google.common.collect.Table;\nimport org.apache.commons.lang.BooleanUtils;\nimport org.sonar.check.Rule;\nimport org.sonar.plugins.java.api.JavaFileScanner;\nimport org.sonar.plugins.java.api.JavaFileScannerContext;\nimport org.sonar.plugins.java.api.tree.*;\n\nimport java.util.*;\n\n/**\n * 三目运算符中的表达式可以不要括号\n * \n * https://github.com/SonarSource/sonar-java/blob/master/java-checks/src/main/java/org/sonar/java/checks/OperatorPrecedenceCheck.java\n * \n * 0d54578 Jan 8, 2018\n */\n@Rule(key = \"S864\")\npublic class OperatorPrecedenceCheck extends BaseTreeVisitor implements JavaFileScanner {\n\n private static final Table OPERATORS_RELATION_TABLE;\n\n private static final Set ARITHMETIC_OPERATORS = EnumSet.of(\n Tree.Kind.MINUS,\n Tree.Kind.REMAINDER,\n Tree.Kind.MULTIPLY,\n Tree.Kind.PLUS\n );\n\n private static final Set EQUALITY_RELATIONAL_OPERATORS = EnumSet.of(\n Tree.Kind.EQUAL_TO,\n Tree.Kind.GREATER_THAN,\n Tree.Kind.GREATER_THAN_OR_EQUAL_TO,\n Tree.Kind.LESS_THAN,\n Tree.Kind.LESS_THAN_OR_EQUAL_TO,\n Tree.Kind.NOT_EQUAL_TO\n );\n\n private static final Set SHIFT_OPERATORS = EnumSet.of(\n Tree.Kind.LEFT_SHIFT,\n Tree.Kind.RIGHT_SHIFT,\n Tree.Kind.UNSIGNED_RIGHT_SHIFT\n );\n\n private static final Tree.Kind[] CONDITIONAL_EXCLUSIONS = new Tree.Kind[]{\n Tree.Kind.METHOD_INVOCATION, Tree.Kind.IDENTIFIER, Tree.Kind.MEMBER_SELECT,\n Tree.Kind.PARENTHESIZED_EXPRESSION, Tree.Kind.TYPE_CAST, Tree.Kind.NEW_CLASS,\n Tree.Kind.ARRAY_ACCESS_EXPRESSION, Tree.Kind.NEW_ARRAY\n };\n\n static {\n OPERATORS_RELATION_TABLE = HashBasedTable.create();\n put(ARITHMETIC_OPERATORS, Iterables.concat(SHIFT_OPERATORS, EnumSet.of(Tree.Kind.AND, Tree.Kind.XOR, Tree.Kind.OR)));\n put(SHIFT_OPERATORS, Iterables.concat(ARITHMETIC_OPERATORS, EnumSet.of(Tree.Kind.AND, Tree.Kind.XOR, Tree.Kind.OR)));\n put(EnumSet.of(Tree.Kind.AND), Iterables.concat(ARITHMETIC_OPERATORS, SHIFT_OPERATORS, EnumSet.of(Tree.Kind.XOR, Tree.Kind.OR)));\n put(EnumSet.of(Tree.Kind.XOR), Iterables.concat(ARITHMETIC_OPERATORS, SHIFT_OPERATORS, EnumSet.of(Tree.Kind.AND, Tree.Kind.OR)));\n put(EnumSet.of(Tree.Kind.OR), Iterables.concat(ARITHMETIC_OPERATORS, SHIFT_OPERATORS, EnumSet.of(Tree.Kind.AND, Tree.Kind.XOR)));\n put(EnumSet.of(Tree.Kind.CONDITIONAL_AND), EnumSet.of(Tree.Kind.CONDITIONAL_OR));\n put(EnumSet.of(Tree.Kind.CONDITIONAL_OR), EnumSet.of(Tree.Kind.CONDITIONAL_AND));\n }\n\n private JavaFileScannerContext context;\n private Deque stack = new LinkedList<>();\n private Set reportedLines = new HashSet<>();\n\n private static void put(Iterable firstSet, Iterable secondSet) {\n for (Tree.Kind first : firstSet) {\n for (Tree.Kind second : secondSet) {\n OPERATORS_RELATION_TABLE.put(first, second, true);\n }\n }\n }\n\n @Override\n public void scanFile(JavaFileScannerContext context) {\n this.context = context;\n reportedLines.clear();\n scan(context.getTree());\n reportedLines.clear();\n }\n\n @Override\n public void visitAnnotation(AnnotationTree tree) {\n stack.push(null);\n for (ExpressionTree argument : tree.arguments()) {\n if (argument.is(Tree.Kind.ASSIGNMENT)) {\n scan(((AssignmentExpressionTree) argument).expression());\n } else {\n scan(argument);\n }\n }\n stack.pop();\n }\n\n @Override\n public void visitArrayAccessExpression(ArrayAccessExpressionTree tree) {\n scan(tree.expression());\n stack.push(null);\n scan(tree.dimension());\n stack.pop();\n }\n\n @Override\n public void visitBinaryExpression(BinaryExpressionTree tree) {\n Tree.Kind peek = stack.peek();\n Tree.Kind kind = tree.kind();\n if (requiresParenthesis(peek, kind)) {\n raiseIssue(tree.operatorToken().line(), tree);\n }\n stack.push(kind);\n super.visitBinaryExpression(tree);\n stack.pop();\n }\n\n private static boolean requiresParenthesis(Tree.Kind kind1, Tree.Kind kind2) {\n return BooleanUtils.isTrue(OPERATORS_RELATION_TABLE.get(kind1, kind2));\n }\n\n @Override\n public void visitIfStatement(IfStatementTree tree) {\n super.visitIfStatement(tree);\n ExpressionTree condition = tree.condition();\n if (condition.is(Tree.Kind.ASSIGNMENT) && EQUALITY_RELATIONAL_OPERATORS.contains(((AssignmentExpressionTree) condition).expression().kind())) {\n raiseIssue(((AssignmentExpressionTree) condition).operatorToken().line(), tree);\n }\n }\n\n @Override\n public void visitMethodInvocation(MethodInvocationTree tree) {\n scan(tree.methodSelect());\n scan(tree.typeArguments());\n for (ExpressionTree argument : tree.arguments()) {\n stack.push(null);\n scan(argument);\n stack.pop();\n }\n }\n\n @Override\n public void visitNewArray(NewArrayTree tree) {\n stack.push(null);\n super.visitNewArray(tree);\n stack.pop();\n }\n\n @Override\n public void visitNewClass(NewClassTree tree) {\n stack.push(null);\n super.visitNewClass(tree);\n stack.pop();\n }\n\n @Override\n public void visitParenthesized(ParenthesizedTree tree) {\n stack.push(null);\n super.visitParenthesized(tree);\n stack.pop();\n }\n\n @Override\n public void visitConditionalExpression(ConditionalExpressionTree tree) {\n checkConditionalOperand(tree.trueExpression());\n checkConditionalOperand(tree.falseExpression());\n super.visitConditionalExpression(tree);\n }\n\n private void checkConditionalOperand(ExpressionTree tree) {\n if (!(tree.is(CONDITIONAL_EXCLUSIONS) || tree instanceof LiteralTree || tree instanceof UnaryExpressionTree)) {\n //VJ ADD 三目运算符中的表达式可以不要括号\n if (tree.parent() != null && tree.parent().kind().equals(Tree.Kind.CONDITIONAL_EXPRESSION)) {\n return;\n }\n //VJ END\n raiseIssue(tree.firstToken().line(), tree);\n }\n }\n\n private void raiseIssue(int line, Tree tree) {\n if (reportedLines.add(line)) {\n context.reportIssue(this, tree, \"Add parentheses to make the operator precedence explicit.\");\n }\n }\n\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/UnusedMethodParameterCheck.java",
"content": "/*\n * SonarQube Java\n * Copyright (C) 2012-2018 SonarSource SA\n * mailto:info AT sonarsource DOT com\n *\n * This program is free software; you can redistribute it and/or\n * modify it under the terms of the GNU Lesser General Public\n * License as published by the Free Software Foundation; either\n * version 3 of the License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU\n * Lesser General Public License for more details.\n *\n * You should have received a copy of the GNU Lesser General Public License\n * along with this program; if not, write to the Free Software Foundation,\n * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.\n */\n\npackage com.vip.vjkit.sonarvj.checks;\n\nimport java.util.ArrayList;\nimport java.util.Collection;\nimport java.util.HashSet;\nimport java.util.List;\nimport java.util.Set;\nimport java.util.stream.Collectors;\n\nimport org.sonar.check.Rule;\nimport org.sonar.java.model.ModifiersUtils;\nimport org.sonar.plugins.java.api.IssuableSubscriptionVisitor;\nimport org.sonar.plugins.java.api.JavaFileScannerContext;\nimport org.sonar.plugins.java.api.semantic.Symbol;\nimport org.sonar.plugins.java.api.semantic.Type;\nimport org.sonar.plugins.java.api.tree.BaseTreeVisitor;\nimport org.sonar.plugins.java.api.tree.ExpressionTree;\nimport org.sonar.plugins.java.api.tree.IdentifierTree;\nimport org.sonar.plugins.java.api.tree.MemberSelectExpressionTree;\nimport org.sonar.plugins.java.api.tree.MethodInvocationTree;\nimport org.sonar.plugins.java.api.tree.MethodTree;\nimport org.sonar.plugins.java.api.tree.Modifier;\nimport org.sonar.plugins.java.api.tree.Tree;\nimport org.sonar.plugins.java.api.tree.VariableTree;\n\nimport com.google.common.collect.ImmutableList;\nimport com.google.common.collect.Lists;\n\n/**\n * 只判读private方法里的无用参数\n * \n * https://github.com/SonarSource/sonar-java/blob/master/java-checks/src/main/java/org/sonar/java/checks/unused/UnusedMethodParameterCheck.java\n * \n * 2c86dbb Jan 12, 2018\n */\n@Rule(key = \"S1172\")\npublic class UnusedMethodParameterCheck extends IssuableSubscriptionVisitor {\n\tprivate static final String AUTHORIZED_ANNOTATION = \"javax.enterprise.event.Observes\";\n\tprivate static final String STRUTS_ACTION_SUPERCLASS = \"org.apache.struts.action.Action\";\n\tprivate static final Collection EXCLUDED_STRUTS_ACTION_PARAMETER_TYPES = ImmutableList.of(\n\t\t\t\"org.apache.struts.action.ActionMapping\", \"org.apache.struts.action.ActionForm\",\n\t\t\t\"javax.servlet.http.HttpServletRequest\", \"javax.servlet.http.HttpServletResponse\");\n\n\t@Override\n\tpublic List nodesToVisit() {\n\t\treturn ImmutableList.of(Tree.Kind.METHOD, Tree.Kind.CONSTRUCTOR);\n\t}\n\n\t@Override\n\tpublic void visitNode(Tree tree) {\n\t\tif (!hasSemantic()) {\n\t\t\treturn;\n\t\t}\n\t\tMethodTree methodTree = (MethodTree) tree;\n\t\tif (methodTree.block() == null || !isIncluded(methodTree)) {\n\t\t\treturn;\n\t\t}\n\t\tList unused = Lists.newArrayList();\n\t\tfor (VariableTree var : methodTree.parameters()) {\n\t\t\tSymbol symbol = var.symbol();\n\t\t\tif (symbol.usages().isEmpty() && !symbol.metadata().isAnnotatedWith(AUTHORIZED_ANNOTATION)\n\t\t\t\t\t&& !isStrutsActionParameter(var)) {\n\t\t\t\tunused.add(var.simpleName());\n\t\t\t}\n\t\t}\n\t\tSet unresolvedIdentifierNames = unresolvedIdentifierNames(methodTree.block());\n\t\t// kill the noise regarding unresolved identifiers, and remove the one with matching names from the list of\n\t\t// unused\n\t\tunused = unused.stream().filter(id -> !unresolvedIdentifierNames.contains(id.name()))\n\t\t\t\t.collect(Collectors.toList());\n\t\tif (!unused.isEmpty()) {\n\t\t\treportUnusedParameters(unused);\n\t\t}\n\t}\n\n\tprivate void reportUnusedParameters(List unused) {\n\t\tList locations = new ArrayList<>();\n\t\tfor (IdentifierTree identifier : unused) {\n\t\t\tlocations.add(new JavaFileScannerContext.Location(\n\t\t\t\t\t\"Remove this unused method parameter \" + identifier.name() + \"\\\".\", identifier));\n\t\t}\n\t\tIdentifierTree firstUnused = unused.get(0);\n\t\tString msg;\n\t\tif (unused.size() > 1) {\n\t\t\tmsg = \"Remove these unused method parameters.\";\n\t\t} else {\n\t\t\tmsg = \"Remove this unused method parameter \\\"\" + firstUnused.name() + \"\\\".\";\n\t\t}\n\t\treportIssue(firstUnused, msg, locations, null);\n\t}\n\n\t// VJ: 改为只判读private方法里的无用参数，替代原isExclude\n\t// 大量删除原来exclude里的复杂判断\n\tprivate static boolean isIncluded(MethodTree tree) {\n\t\treturn isPrivateMethod(tree);\n\t}\n\n\tprivate static boolean isStrutsActionParameter(VariableTree variableTree) {\n\t\tType superClass = variableTree.symbol().enclosingClass().superClass();\n\t\treturn superClass != null && superClass.isSubtypeOf(STRUTS_ACTION_SUPERCLASS)\n\t\t\t\t&& EXCLUDED_STRUTS_ACTION_PARAMETER_TYPES.contains(variableTree.symbol().type().fullyQualifiedName());\n\t}\n\n\tprivate static boolean isPrivateMethod(MethodTree methodTree) {\n\t\treturn ModifiersUtils.hasModifier(methodTree.modifiers(), Modifier.PRIVATE);\n\t}\n\n\tprivate static Set unresolvedIdentifierNames(Tree tree) {\n\t\tUnresolvedIdentifierVisitor visitor = new UnresolvedIdentifierVisitor();\n\t\ttree.accept(visitor);\n\t\treturn visitor.unresolvedIdentifierNames;\n\t}\n\n\tprivate static class UnresolvedIdentifierVisitor extends BaseTreeVisitor {\n\n\t\tprivate Set unresolvedIdentifierNames = new HashSet<>();\n\n\t\t@Override\n\t\tpublic void visitMemberSelectExpression(MemberSelectExpressionTree tree) {\n\t\t\t// skip annotations and identifier, a method parameter will only be used in expression side (before the dot)\n\t\t\tscan(tree.expression());\n\t\t}\n\n\t\t@Override\n\t\tpublic void visitMethodInvocation(MethodInvocationTree tree) {\n\t\t\tExpressionTree methodSelect = tree.methodSelect();\n\t\t\tif (!methodSelect.is(Tree.Kind.IDENTIFIER)) {\n\t\t\t\t// not interested in simple method invocations, we are targeting usage of method parameters\n\t\t\t\tscan(methodSelect);\n\t\t\t}\n\t\t\tscan(tree.typeArguments());\n\t\t\tscan(tree.arguments());\n\t\t}\n\n\t\t@Override\n\t\tpublic void visitIdentifier(IdentifierTree tree) {\n\t\t\tif (tree.symbol().isUnknown()) {\n\t\t\t\tunresolvedIdentifierNames.add(tree.name());\n\t\t\t}\n\t\t\tsuper.visitIdentifier(tree);\n\t\t}\n\t}\n}\n"
},
{
"path": "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/UnusedPrivateFieldCheck.java",
"content": "/*\n * SonarQube Java Copyright (C) 2012-2018 SonarSource SA mailto:info AT sonarsource DOT com\n *\n * This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General\n * Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any\n * later version.\n *\n * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied\n * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more\n * details.\n *\n * You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to\n * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.\n */\n\npackage com.vip.vjkit.sonarvj.checks;\n\nimport java.util.HashSet;\nimport java.util.List;\nimport java.util.Set;\n\nimport org.sonar.check.Rule;\nimport org.sonar.java.model.ExpressionUtils;\nimport org.sonar.java.model.ModifiersUtils;\nimport org.sonar.plugins.java.api.IssuableSubscriptionVisitor;\nimport org.sonar.plugins.java.api.JavaFileScannerContext;\nimport org.sonar.plugins.java.api.semantic.Symbol;\nimport org.sonar.plugins.java.api.tree.AssignmentExpressionTree;\nimport org.sonar.plugins.java.api.tree.ClassTree;\nimport org.sonar.plugins.java.api.tree.ExpressionStatementTree;\nimport org.sonar.plugins.java.api.tree.ExpressionTree;\nimport org.sonar.plugins.java.api.tree.IdentifierTree;\nimport org.sonar.plugins.java.api.tree.ImportTree;\nimport org.sonar.plugins.java.api.tree.MemberSelectExpressionTree;\nimport org.sonar.plugins.java.api.tree.MethodInvocationTree;\nimport org.sonar.plugins.java.api.tree.MethodReferenceTree;\nimport org.sonar.plugins.java.api.tree.MethodTree;\nimport org.sonar.plugins.java.api.tree.Modifier;\nimport org.sonar.plugins.java.api.tree.Tree;\nimport org.sonar.plugins.java.api.tree.Tree.Kind;\nimport org.sonar.plugins.java.api.tree.VariableTree;\n\nimport com.google.common.collect.ArrayListMultimap;\nimport com.google.common.collect.ImmutableList;\nimport com.google.common.collect.ListMultimap;\nimport com.google.common.collect.Lists;\n\n/**\n * 不检查lombok自动生成getter/setter的类\n * \n * https://github.com/SonarSource/sonar-java/blob/master/java-checks/src/main/java/org/sonar/java/checks/unused/UnusedPrivateFieldCheck.java\n * 0d54578 Jan 8, 2018\n */\n@Rule(key = \"S1068\")\npublic class UnusedPrivateFieldCheck extends IssuableSubscriptionVisitor {\n\n\tprivate static final Tree.Kind[] ASSIGNMENT_KINDS = { Tree.Kind.ASSIGNMENT, Tree.Kind.MULTIPLY_ASSIGNMENT,\n\t\t\tTree.Kind.DIVIDE_ASSIGNMENT, Tree.Kind.REMAINDER_ASSIGNMENT, Tree.Kind.PLUS_ASSIGNMENT,\n\t\t\tTree.Kind.MINUS_ASSIGNMENT, Tree.Kind.LEFT_SHIFT_ASSIGNMENT, Tree.Kind.RIGHT_SHIFT_ASSIGNMENT,\n\t\t\tTree.Kind.UNSIGNED_RIGHT_SHIFT_ASSIGNMENT, Tree.Kind.AND_ASSIGNMENT, Tree.Kind.XOR_ASSIGNMENT,\n\t\t\tTree.Kind.OR_ASSIGNMENT };\n\n\tprivate List classes = Lists.newArrayList();\n\tprivate ListMultimap assignments = ArrayListMultimap.create();\n\tprivate Set unknownIdentifiers = new HashSet<>();\n\tprivate boolean hasNativeMethod = false;\n\tprivate boolean lombokClass = false;\n\n\t@Override\n\tpublic List nodesToVisit() {\n\t\treturn ImmutableList.of(Tree.Kind.IMPORT, Tree.Kind.CLASS, Tree.Kind.METHOD, Tree.Kind.EXPRESSION_STATEMENT,\n\t\t\t\tTree.Kind.IDENTIFIER);\n\t}\n\n\t@Override\n\tpublic void scanFile(JavaFileScannerContext context) {\n\t\tsuper.scanFile(context);\n\t\tif (!hasNativeMethod && !lombokClass) {\n\t\t\tclasses.forEach(this::checkClassFields);\n\t\t}\n\t\tclasses.clear();\n\t\tassignments.clear();\n\t\tunknownIdentifiers.clear();\n\t\thasNativeMethod = false;\n\t\tlombokClass = false;\n\t}\n\n\t@Override\n\tpublic void visitNode(Tree tree) {\n\t\tif (!hasSemantic()) {\n\t\t\treturn;\n\t\t}\n\t\tswitch (tree.kind()) {\n\t\tcase METHOD:\n\t\t\tcheckIfNativeMethod((MethodTree) tree);\n\t\t\tbreak;\n\t\tcase CLASS:\n\t\t\tclasses.add((ClassTree) tree);\n\t\t\tbreak;\n\t\tcase IMPORT:// VJ\n\t\t\tcheckIfLombokClass((ImportTree) tree);\n\t\t\tbreak;\n\t\tcase EXPRESSION_STATEMENT:\n\t\t\tcollectAssignment(((ExpressionStatementTree) tree).expression());\n\t\t\tbreak;\n\t\tcase IDENTIFIER:\n\t\t\tcollectUnknownIdentifier((IdentifierTree) tree);\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tthrow new IllegalStateException(\"Unexpected subscribed tree.\");\n\t\t}\n\t}\n\n\t// VJ\n\tprivate void checkIfLombokClass(ImportTree tree) {\n\t\tString importStr = fullQualifiedName(tree.qualifiedIdentifier());\n\t\tif (importStr.contains(\"lombok\")) {\n\t\t\tlombokClass = true;\n\t\t}\n\t}\n\n\t// from WildcardImportsShouldNotBeUsedCheck\n\tprivate static String fullQualifiedName(Tree tree) {\n\t\tif (tree.is(Tree.Kind.IDENTIFIER)) {\n\t\t\treturn ((IdentifierTree) tree).name();\n\t\t} else if (tree.is(Tree.Kind.MEMBER_SELECT)) {\n\t\t\tMemberSelectExpressionTree m = (MemberSelectExpressionTree) tree;\n\t\t\treturn fullQualifiedName(m.expression()) + \".\" + m.identifier().name();\n\t\t}\n\t\tthrow new UnsupportedOperationException(String.format(\"Kind/Class '%s' not supported\", tree.getClass()));\n\t}\n\n\tprivate void collectUnknownIdentifier(IdentifierTree identifier) {\n\t\tif (identifier.symbol().isUnknown() && !isMethodIdentifier(identifier)) {\n\t\t\tunknownIdentifiers.add(identifier.name());\n\t\t}\n\t}\n\n\tprivate static boolean isMethodIdentifier(IdentifierTree identifier) {\n\t\tTree parent = identifier.parent();\n\t\twhile (parent != null && !parent.is(Tree.Kind.METHOD_INVOCATION, Tree.Kind.METHOD_REFERENCE)) {\n\t\t\tparent = parent.parent();\n\t\t}\n\t\tif (parent == null) {\n\t\t\treturn false;\n\t\t}\n\t\tif (parent.is(Tree.Kind.METHOD_INVOCATION)) {\n\t\t\treturn identifier.equals(methodName((MethodInvocationTree) parent));\n\t\t} else {\n\t\t\treturn identifier.equals(((MethodReferenceTree) parent).method());\n\t\t}\n\t}\n\n\t//VJ: copy from MethodsHelper\n\tpublic static IdentifierTree methodName(MethodInvocationTree mit) {\n\t IdentifierTree id;\n\t if (mit.methodSelect().is(Tree.Kind.IDENTIFIER)) {\n\t id = (IdentifierTree) mit.methodSelect();\n\t } else {\n\t id = ((MemberSelectExpressionTree) mit.methodSelect()).identifier();\n\t }\n\t return id;\n\t }\n\t\n\tprivate void checkIfNativeMethod(MethodTree method) {\n\t\tif (ModifiersUtils.hasModifier(method.modifiers(), Modifier.NATIVE)) {\n\t\t\thasNativeMethod = true;\n\t\t}\n\t}\n\n\tprivate void checkClassFields(ClassTree classTree) {\n\t\tclassTree.members().stream().filter(member -> member.is(Tree.Kind.VARIABLE)).map(VariableTree.class::cast)\n\t\t\t\t.forEach(this::checkIfUnused);\n\t}\n\n\tpublic void checkIfUnused(VariableTree tree) {\n\t\tif (hasNoAnnotation(tree)) {\n\t\t\tSymbol symbol = tree.symbol();\n\t\t\tString name = symbol.name();\n\t\t\tif (symbol.isPrivate() && onlyUsedInVariableAssignment(symbol) && !\"serialVersionUID\".equals(name)\n\t\t\t\t\t&& !unknownIdentifiers.contains(name)) {\n\t\t\t\treportIssue(tree.simpleName(), \"Remove this unused \\\"\" + name + \"\\\" private field.\");\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate boolean onlyUsedInVariableAssignment(Symbol symbol) {\n\t\treturn symbol.usages().size() == assignments.get(symbol).size();\n\t}\n\n\tprivate static boolean hasNoAnnotation(VariableTree tree) {\n\t\treturn tree.modifiers().annotations().isEmpty();\n\t}\n\n\tprivate void collectAssignment(ExpressionTree expressionTree) {\n\t\tif (expressionTree.is(ASSIGNMENT_KINDS)) {\n\t\t\taddAssignment(((AssignmentExpressionTree) expressionTree).variable());\n\t\t}\n\t}\n\n\tprivate void addAssignment(ExpressionTree tree) {\n\t\tExpressionTree variable = ExpressionUtils.skipParentheses(tree);\n\t\tif (variable.is(Tree.Kind.IDENTIFIER)) {\n\t\t\taddAssignment((IdentifierTree) variable);\n\t\t} else if (variable.is(Tree.Kind.MEMBER_SELECT)) {\n\t\t\taddAssignment(((MemberSelectExpressionTree) variable).identifier());\n\t\t}\n\t}\n\n\tprivate void addAssignment(IdentifierTree identifier) {\n\t\tSymbol reference = identifier.symbol();\n\t\tif (!reference.isUnknown()) {\n\t\t\tassignments.put(reference, identifier);\n\t\t}\n\t}\n\n}\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1068_java.html",
"content": "VJ update: 使用lobmok的类不告警 \nIf a private field is declared but not used in the program, it can be considered dead code and should therefore be removed. This will\nimprove maintainability because developers will not wonder what the variable is used for.
\nNote that this rule does not take reflection into account, which means that issues will be raised on private fields that are only\naccessed using the reflection API.
\nNoncompliant Code Example \n\npublic class MyClass {\n private int foo = 42;\n\n public int compute(int a) {\n return a * 42;\n }\n\n}\n \nCompliant Solution \n\npublic class MyClass {\n public int compute(int a) {\n return a * 42;\n }\n}\n \nExceptions \nThe Java serialization runtime associates with each serializable class a version number, called serialVersionUID, which is used during\ndeserialization to verify that the sender and receiver of a serialized object have loaded classes for that object that are compatible with respect to\nserialization.
\nA serializable class can declare its own serialVersionUID explicitly by declaring a field named serialVersionUID that\nmust be static, final, and of type long. By definition those serialVersionUID fields should not be reported by this rule:
\n\npublic class MyClass implements java.io.Serializable {\n private static final long serialVersionUID = 42L;\n}\n \nMoreover, this rule doesn't raise any issue on annotated fields.
"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1068_java.json",
"content": "{\n \"title\": \"VJ: Unused \\\"private\\\" fields should be removed\",\n \"type\": \"CODE_SMELL\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"5min\"\n },\n \"tags\": [\n \"cert\",\n \"unused\"\n ],\n \"defaultSeverity\": \"Major\",\n \"ruleSpecification\": \"RSPEC-1068\",\n \"sqKey\": \"S1068\"\n}"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S115_java.html",
"content": "VJ update: 枚举可以是小写 \nShared coding conventions allow teams to collaborate efficiently. This rule checks that all constant names match a provided regular expression.
\nNoncompliant Code Example \nWith the default regular expression ^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$:
\n\npublic class MyClass {\n public static final int first = 1;\n}\n\n \nCompliant Solution \n\npublic class MyClass {\n public static final int FIRST = 1;\n}\n\n \n\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S115_java.json",
"content": "{\n \"title\": \"VJ: Constant names should comply with a naming convention\",\n \"type\": \"CODE_SMELL\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"2min\"\n },\n \"tags\": [\n \"convention\"\n ],\n \"defaultSeverity\": \"Minor\"\n}\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1166_java.html",
"content": "VJ update: catch异常的变量名包含ignore，忽略检查 \nWhen handling a caught exception, the original exception's message and stack trace should be logged or passed forward.
\nNoncompliant Code Example \n\ntry {\n /* ... */\n} catch (Exception e) { // Noncompliant - exception is lost\n LOGGER.info(\"context\");\n}\n\ntry {\n /* ... */\n} catch (Exception e) { // Noncompliant - exception is lost (only message is preserved)\n LOGGER.info(e.getMessage());\n}\n\ntry {\n /* ... */\n} catch (Exception e) { // Noncompliant - original exception is lost\n throw new RuntimeException(\"context\");\n}\n \nCompliant Solution \n\ntry {\n /* ... */\n} catch (Exception e) {\n LOGGER.info(e); // exception is logged\n}\n\ntry {\n /* ... */\n} catch (Exception e) {\n throw new RuntimeException(e); // exception stack trace is propagated\n}\n\ntry {\n /* ... */\n} catch (RuntimeException e) {\n doSomething();\n throw e; // original exception passed forward\n} catch (Exception e) {\n throw new RuntimeException(e); // Conversion into unchecked exception is also allowed\n}\n \nExceptions \nInterruptedException, NumberFormatException, DateTimeParseException, ParseException and\nMalformedURLException exceptions are arguably used to indicate nonexceptional outcomes. Similarly, handling\nNoSuchMethodException is often required when dealing with the Java reflection API.
\nBecause they are part of Java, developers have no choice but to deal with them. This rule does not verify that those particular exceptions are\ncorrectly handled.
\n\nint myInteger;\ntry {\n myInteger = Integer.parseInt(myString);\n} catch (NumberFormatException e) {\n // It is perfectly acceptable to not handle \"e\" here\n myInteger = 0;\n}\n \nSee \n\n CERT, ERR00-J. - Do not suppress or ignore checked exceptions \n OWASP Top 10 2017 Category A10 - Insufficient Logging & Monitoring \n \n\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1166_java.json",
"content": "{\n \"title\": \"VJ：Exception handlers should preserve the original exceptions\",\n \"type\": \"CODE_SMELL\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"10min\"\n },\n \"tags\": [\n \"error-handling\",\n \"owasp-a10\",\n \"cert\",\n \"suspicious\"\n ],\n \"standards\": [\n \"CERT\"\n ],\n \"defaultSeverity\": \"Major\",\n \"ruleSpecification\": \"RSPEC-1166\",\n \"sqKey\": \"S1166\"\n}\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1172_java.html",
"content": "VJ update：只判断private函数 \n\nUnused parameters for private method misleading. Whatever the values passed to such parameters, the behavior will be the same.
\n\nNoncompliant Code Example \n\nprivate void doSomething(int a, int b) { // \"b\" is unused\n compute(a);\n}\n \nCompliant Solution \n\nprivate void doSomething(int a) {\n compute(a);\n}\n \n\nExceptions \nThe rule will not raise issues for protected or public methods
\n\nSee \n\n MISRA C++:2008, 0-1-11 - There shall be no unused parameters (named or unnamed) in nonvirtual functions. \n MISRA C:2012, 2.7 - There should be no unused parameters in functions \n CERT, MSC12-C. - Detect and remove code that has no effect or is never\n executed \n CERT, MSC12-CPP. - Detect and remove code that has no effect \n "
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1172_java.json",
"content": "{\n \"title\": \"VJ: Unused private method parameters should be removed\",\n \"type\": \"CODE_SMELL\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"5min\"\n },\n \"tags\": [\n \"misra\",\n \"cert\",\n \"unused\"\n ],\n \"defaultSeverity\": \"Major\",\n \"ruleSpecification\": \"RSPEC-1172\",\n \"sqKey\": \"S1172\"\n}"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S121_java.html",
"content": "VJ update: IDE自动生成的方法如equals忽略 \nWhile not technically incorrect, the omission of curly braces can be misleading, and may lead to the introduction of errors during maintenance.
\nNoncompliant Code Example \n\nif (condition) // Noncompliant\n executeSomething();\n \nCompliant Solution \n\nif (condition) {\n executeSomething();\n}\n \nSee \n\n MISRA C:2004, 14.8 - The statement forming the body of a switch, while, do ... while or for statement shall be a compound statement \n MISRA C:2004, 14.9 - An if (expression) construct shall be followed by a compound statement. The else keyword shall be followed by either a\n compound statement, or another if statement \n MISRA C++:2008, 6-3-1 - The statement forming the body of a switch, while, do ... while or for statement shall be a compound statement \n MISRA C++:2008, 6-4-1 - An if (condition) construct shall be followed by a compound statement. The else keyword shall be followed by either a\n compound statement, or another if statement \n MISRA C:2012, 15.6 - The body of an iteration-statement or a selection-statement shall be a compound-statement \n CERT, EXP19-C. - Use braces for the body of an if, for, or while statement\n \n CERT, EXP52-J. - Use braces for the body of an if, for, or while statement\n \n \n\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S121_java.json",
"content": "{\n \"title\": \"VJ: Control structures should use curly braces\",\n \"type\": \"CODE_SMELL\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"2min\"\n },\n \"tags\": [\n \"misra\",\n \"cert\",\n \"pitfall\"\n ],\n \"standards\": [\n \"CERT\"\n ],\n \"defaultSeverity\": \"Major\",\n \"ruleSpecification\": \"RSPEC-121\",\n \"sqKey\": \"S121\"\n}\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1291_java.html",
"content": "VJ update: 忽略在异常捕获语句和System.out后的NOSONAR \nAny issue to quality rule can be deactivated with the NOSONAR marker. This marker is pretty useful to exclude false-positive results\nbut it can also be used abusively to hide real quality flaws.
\nThis rule raises an issue when NOSONAR is used.
"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1291_java.json",
"content": "{\n \"title\": \"VJ: Track uses of \\\"NOSONAR\\\" comments\",\n \"type\": \"CODE_SMELL\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"1min\"\n },\n \"tags\": [\n \"bad-practice\"\n ],\n \"defaultSeverity\": \"Info\",\n \"ruleSpecification\": \"RSPEC-1291\",\n \"sqKey\": \"S1291\"\n}"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1313_java.html",
"content": "VJ update: 忽略\"127.0.0.1\" \nHardcoding an IP address into source code is a bad idea for several reasons:
\n\n a recompile is required if the address changes \n it forces the same address to be used in every environment (dev, sys, qa, prod) \n it places the responsibility of setting the value to use in production on the shoulders of the developer \n it allows attackers to decompile the code and thereby discover a potentially sensitive address \n \nNoncompliant Code Example \n\nString ip = \"200.112.44.55\";\nSocket socket = new Socket(ip, 6667);\n \nCompliant Solution \n\nString ip = System.getProperty(\"myapplication.ip\");\nSocket socket = new Socket(ip, 6667);\n \nSee \n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S1313_java.json",
"content": "{\n \"title\": \"VJ: IP addresses should not be hardcoded\",\n \"type\": \"VULNERABILITY\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"30min\"\n },\n \"tags\": [\n \"cert\"\n ],\n \"standards\": [\n \"CERT\"\n ],\n \"defaultSeverity\": \"Minor\",\n \"ruleSpecification\": \"RSPEC-1313\",\n \"sqKey\": \"S1313\"\n}"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S864_java.html",
"content": "VJ update: 三目运算符中的简单表达式可以不要括号 \nThe rules of operator precedence are complicated and can lead to errors. For this reason, parentheses should be used for clarification in complex\nstatements. However, this does not mean that parentheses should be gratuitously added around every operation.
\nThis rule raises issues when && and || are used in combination, when assignment and equality or relational\noperators are used in together in a condition, and for other operator combinations according to the following table:
\n\n \n \n \n +, -, *, /, %<<, >>, >>>&^ | \n \n \n +, -, *, /, % \n x \n x \n x \n x \n \n \n <<, >>, >>>x \n \n x \n x \n x \n \n \n &x \n x \n \n x \n x \n \n \n ^x \n x \n x \n \n x \n \n \n | \n x \n x \n x \n x \n \n \n \n
\nNoncompliant Code Example \n\nx = a + b - c;\nx = a + 1 << b; // Noncompliant\n\nif ( a > b || c < d || a == d) {...}\nif ( a > b && c < d || a == b) {...} // Noncompliant\nif (a = f(b,c) == 1) { ... } // Noncompliant; == evaluated first\n \nCompliant Solution \n\nx = a + b - c;\nx = (a + 1) << b;\n\nif ( a > b || c < d || a == d) {...}\nif ( (a > b && c < d) || a == b) {...}\nif ( (a = f(b,c)) == 1) { ... }\n \nSee \n\n MISRA C:2004, 12.1 - Limited dependence should be placed on C's operator precedence rules in expressions \n MISRA C:2004, 12.2 - The value of an expression shall be the same under any order of evaluation that the standard permits. \n MISRA C:2004, 12.5 - The operands of a logical && or || shall be primary-expressions. \n MISRA C++:2008, 5-0-1 - The value of an expression shall be the same under any order of evaluation that the standard permits. \n MISRA C++:2008, 5-0-2 - Limited dependence should be placed on C++ operator precedence rules in expressions \n MISRA C++:2008, 5-2-1 - Each operand of a logical && or || shall be a postfix-expression. \n MISRA C:2012, 12.1 - The precedence of operators within expressions should be made explicit \n CERT, EXP00-C. - Use parentheses for precedence of operation \n CERT, EXP00-CPP. - Use parentheses for precedence of operation \n CERT, EXP53-J. - Use parentheses for precedence of operation \n MITRE, CWE-783 - Operator Precedence Logic Error \n \n\n"
},
{
"path": "standard/sonar-vj/src/main/resources/com/vip/java/rules/S864_java.json",
"content": "{\n \"title\": \"VJ: Limited dependence should be placed on operator precedence rules in expressions\",\n \"type\": \"CODE_SMELL\",\n \"status\": \"ready\",\n \"remediation\": {\n \"func\": \"Constant\\/Issue\",\n \"constantCost\": \"2min\"\n },\n \"tags\": [\n \"cwe\",\n \"misra\",\n \"cert\"\n ],\n \"standards\": [\n \"CWE\",\n \"CERT\"\n ],\n \"defaultSeverity\": \"Major\",\n \"ruleSpecification\": \"RSPEC-864\",\n \"sqKey\": \"S864\"\n}\n"
},
{
"path": "vjdump/README.md",
"content": "# 1. 概述\n\nVJDump是线上JVM数据紧急收集脚本。 \n\n它可以在紧急场景下（比如马上要对进程进行重启），一键收集jstack、jmap以及GC日志等相关信息，并以zip包保存(默认在目录`/tmp/vjtools/vjdump`下)，保证在紧急情况下仍能收集足够的问题排查信息，减轻运维团队的工作量，以及与开发团队的沟通成本。\n\n收集数据包括：\n* thread dump数据：`jstack -l $PID`\n* vjtop JVM概况及繁忙线程：`vjtop.sh -n 1 $PID` (需要将vjtop.sh 加入用户的PATH变量中)\n* jmap histo 堆对象统计数据：`jmap -histo $PID` & `jmap -histo:live $PID`\n* GC日志(如果JVM有设定GC日志输出)\n* heap dump数据（需指定--liveheap开启）：`jmap -dump:live,format=b,file=${DUMP_FILE} $PID`\n\n# 2. 下载\n\n[vjdump.sh](https://raw.githubusercontent.com/vipshop/vjtools/master/vjdump/vjdump.sh)\n\n# 3. 快速入门\n\n以目标JVM相同用户或root用户运行脚本：\n\n```shell\n\n# 对指定的进程PID进行急诊\nvjdump.sh $pid\n\n\n# 额外收集heap dump信息（jmap -dump:live的信息）\nvjdump.sh --liveheap $pid\n\n```\n\n\n在收集过程中，某些命令如`jmap -histo:live $PID` 会造成JVM停顿，因此仅用于紧急情况或已摘流量的情况。为了避免连续停顿，在每条会造成停顿的收集指令之间，默认插入了1秒的执行间隔。\n"
},
{
"path": "vjdump/README_EN.md",
"content": "# VJDump\nVJDump comes as a handy script for collecting diagnostic data for JVM during urgent failures to\n**allow for complete analysis later**.\n\n# 1.Introduction\nWhen major system failures occur for reasons not yet known, rebooting may be the only option to ease user complaints.\nThere is so little time that even an experienced system admin might forget to pick up all he needs for offline analysis. \n\nVJDump script is written to make us eaiser, which just packs outputs from T\njstack, jmap, gc logs into the form of a single zip file under `/tmp/vjtools/vjdump`.\n\n**[Important]**: Commands like jstack and jmap DO cause stop-of-the-world of the target app. Make sure the target app \nis isolated from user access before you run this full check in production.\n\nItems to be collected by VJDump are:\n* thread dump via `jstack -l $PID`\n* vjtop JVM overview and busy threads snapshot via `vjtop.sh -n 1 -d 3 $PID` (enabled when you have our vjtop installed and \nhave the folder of vjtop.sh appended to the PATH environment variable)\n* jmap histo object statistics via`jmap -histo $PID` & `jmap -histo:live $PID`\n* GC logs if available\n* heap dump (which can be optionally switched on via --liveheap)：`jmap -dump:live,format=b,file=${DUMP_FILE} $PID`\n\n# 2. Download\n[vjdump.sh](https://raw.githubusercontent.com/vipshop/vjtools/master/vjdump/vjdump.sh)\n\n# 3. Getting Started\nUse the following commands under **the same user who started the target process** and collect results in `/tmp/vjtools/vjdump`.\n\n```shell\n\n# collect dignostics for target $pid\nvjdump.sh $pid\n\n\n# include heap dump also via jmap -dump:live, might take longer\nvjdump.sh --liveheap $pid\n\n```\n"
},
{
"path": "vjdump/vjdump.sh",
"content": "#!/bin/bash\n\nUSAGE()\n{\n echo \"usage: $0 [--liveheap][-nz|--nozip][-i|--interval] \"\n}\n\nif [ $# -lt 1 ]; then\n USAGE\n exit -1\nfi\n\nBASEDIR=/tmp/vjtools\nLOGDIR=${BASEDIR}/vjdump\nSLEEP_TIME=1\nCLOSE_COMPRESS=0\nNEED_HEAP_DUMP=0\nPID=\"$1\"\n\nwhile true; do\n case \"$1\" in\n -i|--interval) SLEEP_TIME=\"$2\"; PID=\"$3\"; shift 1;;\n -nz|--nozip) CLOSE_COMPRESS=1; PID=\"$2\"; shift;;\n --liveheap) NEED_HEAP_DUMP=1; PID=\"$2\"; shift;;\n *) break;;\n esac\ndone\n\nCMD=\"$1\"\nshift\n\nSTART()\n{\n if [[ x\"$PID\" == x ]]; then\n echo -e \"The pid is empty, please enter pid\".\n exit -1\n else \n echo -e \"The pid is ${PID}\"\n fi\n\n # try to find $JAVA_HOME if not set\n if [ -z \"$JAVA_HOME\" ] ; then\n JAVA_HOME=`readlink -f \\`which java 2>/dev/null\\` 2>/dev/null | \\\n sed 's/\\jre\\/bin\\/java//' | sed 's/\\/bin\\/java//'`\n fi\n\n if [ ! -f \"$JAVA_HOME/bin/jstack\" ] ; then\n echo -e \"\\033[31m\\$JAVA_HOME not found. please export JAVA_HOME manually.\\033[0m\"\n exit -1\n fi\n\n\n # clean all history logs\n rm -rf ${LOGDIR}/*.log ${LOGDIR}/*jmap_dump_live-*.bin\n mkdir -p ${LOGDIR}\n \n DATE=$(date \"+%Y%m%d%H%M%S\")\n \n echo -e \"\\033[34m$(date '+%Y-%m-%d %H:%M:%S') vjdump begin. command interval is ${SLEEP_TIME}s.\\033[0m\"\n \n # jstack\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process jstack.\"\n JSTACK_LOG=${LOGDIR}/jstack-${PID}-${DATE}.log\n ${JAVA_HOME}/bin/jstack -l $PID > ${JSTACK_LOG}\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mprocess jstack error.\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process jstack.\"\n sleep ${SLEEP_TIME}\n \n # vjtop\n VJTOP_SCRIPT=vjtop.sh\n which $VJTOP_SCRIPT 2>/dev/null\n if [[ $? == 0 ]]; then\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process vjtop.\"\n echo -e \"It will take 3 seconds, please wait.\"\n VJTOP_LOG=${LOGDIR}/vjtop-${PID}-${DATE}.log\n $VJTOP_SCRIPT -n 3 -d 1 $PID > ${VJTOP_LOG}\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mprocess vjtop error.\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process vjtop.\"\n else\n # no vjtop, use other replacement\n # jinfo -flags $PID\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process jinfo -flags.\"\n JINFO_FLAGS_LOG=${LOGDIR}/jinfo-flags-${PID}-${DATE}.log\n ${JAVA_HOME}/bin/jinfo -flags $PID 1>${JINFO_FLAGS_LOG} 2>&1\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mprocess jinfo -flags error.\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process jinfo -flags.\"\n \n #jmap -heap\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process jmap -heap.\"\n JMAP_HEAP_LOG=${LOGDIR}/jmap_heap-${PID}-${DATE}.log\n ${JAVA_HOME}/bin/jmap -heap $PID > ${JMAP_HEAP_LOG}\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mprocess jmap -heap error.\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process jmap -heap.\"\n fi\n \n # jmap -histo\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process jmap -histo.\"\n JMAP_HISTO_LOG=${LOGDIR}/jmap_histo-${PID}-${DATE}.log\n ${JAVA_HOME}/bin/jmap -histo $PID > ${JMAP_HISTO_LOG}\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mprocess jmap -histo error.\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process jmap -histo.\"\n sleep ${SLEEP_TIME}\n \n # jmap -histo:live\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process jmap -histo:live.\"\n JMAP_HISTO_LIVE_LOG=${LOGDIR}/jmap_histo_live-${PID}-${DATE}.log\n ${JAVA_HOME}/bin/jmap -histo:live $PID > ${JMAP_HISTO_LIVE_LOG}\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mprocess jmap -histo:live error.\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process jmap -histo:live.\"\n sleep ${SLEEP_TIME}\n \n # jmap -dump:live\n if [[ $NEED_HEAP_DUMP == 1 ]]; then\n JMAP_DUMP_FILE=${LOGDIR}/jmap_dump_live-${PID}-${DATE}.bin\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process jmap -dump:live.\"\n ${JAVA_HOME}/bin/jmap -dump:live,format=b,file=${JMAP_DUMP_FILE} $PID\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mprocess jmap -dump:live error.\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process jmap -dump:live.\"\n \n sleep ${SLEEP_TIME}\n fi\n \n\n # gc log\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to process gc log.\"\n GCLOG=$(strings /proc/${PID}/cmdline |grep '\\-Xloggc' |cut -d : -f 2)\n if [[ x\"$GCLOG\" == x ]]; then\n echo -e \"No GC log existing.\"\n else\n # \"\\cp\" means unalias cp, it can cover files without prompting\n \\cp -rf $GCLOG ${LOGDIR}/\n if [[ $? != 0 ]]; then\n echo -e \"copy gc log error.\"\n fi\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to process gc log.\"\n\n # packaging\n if [[ $CLOSE_COMPRESS == 1 ]]; then\n echo -e \"The zip option is closed, no zip package will be generated.\"\n else\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to zip all files.\"\n # zip files without heap dump \n if [ -x \"$(command -v zip)\" ]; then\n COMPRESS_FILE=${BASEDIR}/vjdump-${PID}-${DATE}.zip\n zip -j ${COMPRESS_FILE} ${LOGDIR}/*.log\n else\n COMPRESS_FILE=${BASEDIR}/vjdump-${PID}-${DATE}.tar.gz\n (cd ${LOGDIR} && tar -zcvf ${COMPRESS_FILE} *.log)\n fi\n\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mzip files error.\\033[0m\"\n else\n echo -e \"zip files success, the zip file is \\033[34m${ZIP_FILE}\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to zip all files.\"\n \n if [[ $NEED_HEAP_DUMP == 1 ]]; then\n # compress all files\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Begin to zip files which include dump file.\"\n\n if [ -x \"$(command -v zip)\" ]; then\n COMPRESS_FILE_WITH_HEAP_DUMP=${BASEDIR}/vjdump-with-heap-${PID}-${DATE}.zip\n zip -j ${COMPRESS_FILE_WITH_HEAP_DUMP} ${LOGDIR}/*.log ${JMAP_DUMP_FILE}\n else\n COMPRESS_FILE_WITH_HEAP_DUMP=${BASEDIR}/vjdump-with-heap-${PID}-${DATE}.tar.gz\n (cd ${LOGDIR} && tar -zcvf ${COMPRESS_FILE_WITH_HEAP_DUMP} *.log *.bin)\n fi\n\n if [[ $? != 0 ]]; then\n echo -e \"\\033[31mzip files which include dump file error.\\033[0m\"\n else\n echo -e \"zip files which include dump file success, the zip path is \\033[34m${ZIP_FILE_WITH_HEAP_DUMP}\\033[0m\"\n fi\n echo -e \"$(date '+%Y-%m-%d %H:%M:%S') Finish to zip files which include dump file.\"\n fi\n fi\n echo -e \"\\033[34m$(date '+%Y-%m-%d %H:%M:%S') vjdump finish. \\033[0m\"\n}\n\ncase \"$CMD\" in\n help) USAGE;;\n *) START;;\nesac\n"
},
{
"path": "vjkit/README.md",
"content": "# 1. Overview\n\n唯品会Java开发基础类库，综合各门各派众多开源类库的精华而成， 让开发人员避免底层代码的重复开发，默认就拥有最佳实践，尤其在性能的方面。\n\n\n综合众多开源类库的精华而成， 让开发人员避免底层代码的重复开发，默认就拥有最佳实践，尤其在性能的方面。\n\n针对“基础，文本，数字，日期，文件，集合，并发，反射，日志脱敏”这些开发人员的日常，VJKit做了两件事情：\n\n一是对[Guava](https://github.com/google/guava) 与[Common Lang](https://github.com/apache/commons-lang)中最常用的API的提炼归类，避免了大家直面茫茫多的API(但有些工具类如Guava Cache还是建议直接使用，详见[直用三方工具类](docs/direct_3rd.md) )\n\n二是对各门各派的精华的借鉴移植：比如一些大项目的附送基础库： [Netty](https://github.com/netty/netty/)，[ElasticSearch](https://github.com/elastic/elasticsearch)， 一些专业的基础库 ： [Jodd](https://github.com/oblac/jodd/), [commons-io](https://github.com/apache/commons-io), [commons-collections](https://github.com/apache/commons-collections)； 一些大厂的基础库：[Facebook JCommon](https://github.com/facebook/jcommon)，[twitter commons](https://github.com/twitter/commons)\n\n\n具体使用文档请在IDE中阅读JavaDoc，以及对应的单元测试写法。\n\n* [日志脱敏](docs/data_masking.md)\n\n\n# 2. Usage\n\nMaven : \n```\n\n\tcom.vip.vjtools \n\tvjkit \n\t1.0.8 \n \n```\n\nDownload: [](http://search.maven.org/#search|gav|1|g:\"com.vip.vjtools\"%20AND%20a:\"vjkit\")\n\n\n# 3. Dependency\n\n要求JDK 7.0及以上版本。\n\n| Project | Version | Optional|\n|--- | --- | --- |\n|[Guava](https://github.com/google/guava) | 20.0 ||\n|[Apache Common Lang](https://github.com/apache/commons-lang) | 3.7 ||\n|[Slf4j](https://www.slf4j.org) | 1.7.25 ||\n|[Dozer](http://dozermapper.github.io/) | 5.5.1 |Optional for BeanMapper，[选型](https://github.com/vipshop/vjtools/blob/master/vjkit/src/main/java/com/vip/vjtools/vjkit/reflect/BeanMapper.java#L11) |\n\n如果使用Optional的依赖，请参考pom文件在业务项目自行引入\n\n# 4. Sonar Status\n\n[https://sonarcloud.io/dashboard?id=com.vip.vjtools:vjkit](https://sonarcloud.io/dashboard?id=com.vip.vjtools:vjkit)\n\n(sonarcloud use \"Sonar Way\")\n\n\n\n"
},
{
"path": "vjkit/docs/data_masking.md",
"content": "# 1.简介\nvjmask是唯品会的日志脱敏组件，在业务中广泛使用。基于性能和通用性考虑，采用了现在的方案。让使用方用最少的配置和代码，就可以轻松实现敏感信息过滤。\n\n# 2.使用\n## 2.1 依赖\n\n```\n\n com.vip.vjtools \n vjkit \n ${version} \n \n```\n\n## 2.2 最佳实践\n脱敏组件支持对单个字符串进行脱敏，也支持toJSON和toString的序列化脱敏\n\n```\nimport com.vip.vjtools.vjkit.datamasking.DataMask;\n\n// 单个字符串，按中文姓名规则脱敏\nlogger.info(\"some sensitive info:{}\",DataMask.mask(name,SensitiveType.Name));\n//单个字符串，按默认方式脱敏，结果为 \"t***\";\nlogger.info(\"some sensitive info:{}\",DataMask.mask(\"test\")); \n \n//对象json序列化脱敏\nlogger.info(\"some sensitive object:{}\",DataMask.toJSONString(obj));\n//对象toString序列化脱敏\nlogger.info(\"some sensitive object:{}\",DataMask.toString(obj));\n```\n\n对类的序列化脱敏，先要对相关敏感字段标记 @Sensitive，支持字符串类型的字段，包括String、String[]和Collection. 嵌套类的敏感字段也是可以识别的。\n\n```\npublic class User{\n @Sensitive(type = SensitiveType.Phone) type参考2.3\n private String phone;\n}\n```\n\n## 2.3 脱敏规则\n我们已经定义实现了常用的脱敏类型，可以直接使用\n\n敏感信息 | 脱敏要求 | 样例 | SensitiveType\n---|---|---|---\n中文姓名 | 三个字及以下，只显示最后一个字;三个字以上，显示最后两个字 | *明，****小明 | Name\n手机号/固定电话 | 只显示前三后三 | 138*****111 | Phone\n身份证号 | 显示前五个和后二个字符 | 44010************58 | IDCard\n银行卡号 | 显示前四个和后二个字符 | 6228************89 | BankCard\n地址 | 保留前9个字符 | 广东省广州市荔湾区****** | Address\n电子邮箱 | 只显示前一后一及@和后面的内容 | a***b@abc.com | Email\n验证码 | 只显示前一后一 | a**b | Captcha\n护照/军官号 | 只显示前二后二 | EI****64 | Passport\n账号 | 只显示前一后一 | a****b | Account\n密码 | 不显示任意字符 | ********* | Password\n散列 | sha1(source+salt) ，可以通过DataMask.setSalt设置salt，用于希望在日志系统中精确找回这条日志的场景，可以再自己hash获得hash值 | 6b76e070c5b5d1b889295506faa8b98e97da7e87 | Hash\n\n\n# 3.详细介绍\n## 3.1 Annotation标注\n要使用序列化脱敏，先要对敏感字段标注@Sensitive，注意，只对字符串相关的类型字段会生效。\n\n```\n//根据类型来标注\n@Sensitive(type = SensitiveType.Name)\nprivate String name;\n \n//也可以自定义掩码规则\n@Sensitive(keepChars = 2) //首尾保留2个字符串，如果keepChars = {1,3} 表示头部保留1个字符，尾部保留3个字符\nprivate String[] phone;\n \n// 散列的方式\n@Sensitive(type = SensitiveType.Hash)\nprivate String hash;\n \n//默认的方式,只保留第一个字符串\n@Sensitive\nprivate List account;\n```\n\n## 3.2 映射配置\n如果你不想对一个个类字段标注@Sensitive,也可以在resource 目录下新建一个data_mask。properties,添加敏感字段映射\n\n```\n#SensitiveType=字段名称\nName=nickName\n```\n那么nickName字段即使没有标注@Sensitive ，在序列化的时候，也会自动脱敏，按照SentiveType.Name的方式脱敏。 \n\n==注意，标注@Sensitive优先级高于文件配置==\n\n组件中已经默认配置映射了以下配置，sys_data_mask.properties\n\n```\nName=chineseName,userName\nPhone=phone,phoneNum,mobile,tel,telephone\nIDCard=IDCard,IdNo\nBankCard=bankCard\nAddress=address,addr\nEmail=mail,email\nCaptcha=captcha\nPassport=passport\nAccount=account\nPassword=password,passwd\n```\n\n# 4.Benchmark\n我们使用JMH基准测试，测试了2个使用场景。\n## 4.1 场景1\n通用场景，场景1包括了10个左右的Sensitive字段。toJSONString() 平均耗时 0.003ms，toString() 平均耗时0.005ms。\n\n\n```\nBenchmark Mode Score Error Units\nDataMaskTest.testJson(不脱敏) avgt 0.001 ± 0.001 ms/op\nDataMaskTest.testMaskJson avgt 0.003 ± 0.002 ms/op\nDataMaskTest.testMaskToString avgt 0.005 ± 0.003 ms/op\nDataMaskTest.testToString avgt ≈ 10⁻⁴ ms/op\n```\n\n## 4.2 场景2\n极限场景，场景2测试超大的类序列化，有160多个字段需要脱敏，3层嵌套。toJSONString() 平均耗时 0.064ms，toString() 平均耗时0.098ms。\n```\nBenchmark Mode Score Error Units\nDataMaskTest.testJson avgt 0.043 ± 0.025 ms/op\nDataMaskTest.testMaskJson avgt 0.064 ± 0.002 ms/op\nDataMaskTest.testMaskToString avgt 0.098 ± 0.095 ms/op\nDataMaskTest.testToString avgt ≈ 10⁻⁴ ms/op\n```\n\n## 4.3 结论\n脱敏处理的性能和脱敏字段的数量相关。\n\na.如果需要脱敏的字段不多，时间在0.001ms~0.009ms范围内，对于业务来说，不会造成太多额外开销，在可控范围内。\n\nb.如果需要脱敏的字段特别多，建议要性能测试评估\n\nc.toString() 性能比toJson() 要慢，建议是优先使用toJson()\n"
},
{
"path": "vjkit/docs/direct_3rd.md",
"content": "# 建议直接使用的第三方类\n\n\n| Project | Class | \n|--- | --- |\n|Common Lang | StringUtils |\n| | Validate|\n|Guava | Cache |\n| | Ordering |\n|JDK|Arrays|\n| |Collections|\n"
},
{
"path": "vjkit/pom.xml",
"content": "\n\n\t4.0.0 \n\tcom.vip.vjtools \n\tvjkit \n\t1.0.9-SNAPSHOT \n\tjar \n\tvjkit \n\tVIP's core java libraries \n\n\t\n\t\t20.0 \n\t\t3.8.1 \n\t\t1.7.25 \n\t\t1.1.11 \n\t\t5.5.1 \n\t\t2.9.10.4 \n\t\t4.12 \n\t\t2.6.0 \n\t\t2.18.3 \n\t\t1.2.70 \n\n\t\t\n\t\tUTF-8 \n\t\t1.7 \n\t\t${java.version} \n\t\t${java.version} \n\t \n\n\t\n\t\n\n\t\t\n\t\t\n\t\t\tcom.google.guava \n\t\t\tguava \n\t\t\t${guava.version} \n\t\t \n\t\t\n\t\t\torg.apache.commons \n\t\t\tcommons-lang3 \n\t\t\t${commons-lang3.version} \n\t\t \n\n\t\t\n\t\t\n\t\t\torg.slf4j \n\t\t\tslf4j-api \n\t\t\t${slf4j.version} \n\t\t \n\n\t\t\n\t\t\n\t\t\tnet.sf.dozer \n\t\t\tdozer \n\t\t\t${dozer.version} \n\t\t\ttrue \n\t\t \n\n\t\t\n\t\t\n\t\t\tcom.fasterxml.jackson.core \n\t\t\tjackson-databind \n\t\t\t${jackson.version} \n\t\t\ttrue \n\t\t \n\n \n \n com.alibaba \n fastjson \n ${fastjson.version} \n true \n \n\n \n ch.qos.logback \n logback-classic \n ${logback.version} \n true \n \n\n\t\t\n\t\t\n\t\t\tjunit \n\t\t\tjunit \n\t\t\t${junit.version} \n\t\t\ttest \n\t\t \n\n\t\t\n\t\t\torg.assertj \n\t\t\tassertj-core \n\t\t\t${assertj.version} \n\t\t\ttest \n\t\t \n\n\t\t\n\t\t\torg.mockito \n\t\t\tmockito-core \n\t\t\t${mockito.version} \n\t\t\ttest \n\t\t \n\n\t\t\n\t\t\n\t\t\tdom4j \n\t\t\tdom4j \n\t\t\t1.6.1 \n\t\t\ttest \n\t\t \n\n\t\t\n\t\t\n\t\t\tjaxen \n\t\t\tjaxen \n\t\t\t1.1.6 \n\t\t\ttest \n\t\t \n\t\t\n\t\t\torg.skyscreamer \n\t\t\tjsonassert \n\t\t\t1.5.0 \n\t\t\ttest \n\t\t \n\t \n\n\t\n\t\t\n\t\t\trelease \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\torg.apache.maven.plugins \n\t\t\t\t\t\tmaven-javadoc-plugin \n\t\t\t\t\t\t2.10.4 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\tfalse \n\t\t\t\t\t\t \n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\tattach-javadocs \n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t\tjar \n\t\t\t\t\t\t\t\t \n\t\t\t\t\t\t\t \n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\torg.apache.maven.plugins \n\t\t\t\t\t\tmaven-source-plugin \n\t\t\t\t\t\t3.0.1 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\tattach-sources \n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t\tjar \n\t\t\t\t\t\t\t\t \n\t\t\t\t\t\t\t \n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t\t\n\t\t\t\t\t\torg.apache.maven.plugins \n\t\t\t\t\t\tmaven-release-plugin \n\t\t\t\t\t\t2.5.3 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\tv.@{project.version} \n\t\t\t\t\t\t \n\t\t\t\t\t \n\n\t\t\t\t\t\n\t\t\t\t\t\torg.apache.maven.plugins \n\t\t\t\t\t\tmaven-gpg-plugin \n\t\t\t\t\t\t1.6 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\tsign-artifacts \n\t\t\t\t\t\t\t\tverify \n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t\tsign \n\t\t\t\t\t\t\t\t \n\t\t\t\t\t\t\t \n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t \n\t\t\t \n\t\t \n\n\t\t\n\t\t\tsonar \n\t\t\t\n\t\t\t\t1.7 \n\t\t\t\t**/primitive/**/*.java,**/jsr166e/**/*.java,**/SortedArrayList.java,**/WildcardMatcher.java,**/CsvUtil.java \n\t\t\t \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\torg.jacoco \n\t\t\t\t\t\tjacoco-maven-plugin \n\t\t\t\t\t\t0.7.2.201409121644 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\ttrue \n\t\t\t\t\t\t \n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\tagent-for-ut \n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t\tprepare-agent \n\t\t\t\t\t\t\t\t \n\t\t\t\t\t\t\t \n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t\t\n\t\t\t\t\t\torg.sonarsource.scanner.maven \n\t\t\t\t\t\tsonar-maven-plugin \n\t\t\t\t\t\t3.4.0.905 \n\t\t\t\t\t \n\t\t\t\t \n\t\t\t \n\t\t \n\n\t\t\n\t\t\tjdk9 \n\t\t\t\n\t\t\t\t9 \n\t\t\t \n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\torg.apache.maven.plugins \n\t\t\t\t\t\tmaven-surefire-plugin \n\t\t\t\t\t\t2.22.0 \n\t\t\t\t\t\t\n\t\t\t\t\t\t\t--add-modules java.xml.bind \n\t\t\t\t\t\t \n\t\t\t\t\t \n\t\t\t\t \n\t\t\t \n\t\t \n\t \n\n\t\n\t\t\n\t\t\tsonatype-nexus-snapshots \n\t\t\thttps://oss.sonatype.org/content/repositories/snapshots \n\t\t \n\t\t\n\t\t\tsonatype-nexus-releases \n\t\t\thttps://oss.sonatype.org/service/local/staging/deploy/maven2 \n\t\t \n\t \n\n\thttps://github.com/vipshop/vjtools \n\n\t\n\t\t\n\t\t\tApache License 2.0 \n\t\t\thttp://www.apache.org/licenses/LICENSE-2.0.txt \n\t\t\trepo \n\t\t \n\t \n\n\t\n\t\tscm:git:https://github.com/vipshop/vjtools.git \n\t\tscm:git:https://github.com/vipshop/vjtools.git \n\t\thttps://github.com/vipshop/vjtools \n\t v.1.0.2 \n \n\n\t\n\t\t\n\t\t\n\t\t\tcalvin \n\t\t\tCalvin Xiao \n\t\t\tcalvin.xiao at vipshop.com \n\t\t\t\n\t\t\t\tdeveloper \n\t\t\t \n\t\t\t+8 \n\t\t \n\t \n \n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/BooleanUtil.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport org.apache.commons.lang3.BooleanUtils;\n\n/**\n * 1. 从String(true/false, yes/no)，转换为Boolean或boolean\n * \n * 2. 逻辑运算：取反，多个boolean的and,or 计算\n * \n * 封装 {@code org.apache.commons.lang3.BooleanUtils}\n */\npublic class BooleanUtil {\n\n\t/**\n\t * 使用标准JDK，只分析是否忽略大小写的\"true\", str为空时返回false\n\t */\n\tpublic static boolean toBoolean(String str) {\n\t\treturn Boolean.parseBoolean(str);\n\t}\n\n\t/**\n\t * 使用标准JDK，只分析是否忽略大小写的\"true\", str为空时返回null\n\t */\n\tpublic static Boolean toBooleanObject(String str) {\n\t\treturn str != null ? Boolean.valueOf(str) : null;\n\t}\n\n\t/**\n\t * 使用标准JDK，只分析是否忽略大小写的\"true\", str为空时返回defaultValue\n\t */\n\tpublic static Boolean toBooleanObject(String str, Boolean defaultValue) {\n\t\treturn str != null ? Boolean.valueOf(str) : defaultValue;\n\t}\n\n\t/**\n\t * 支持true/false, on/off, y/n, yes/no的转换, str为空或无法分析时返回null\n\t */\n\tpublic static Boolean parseGeneralString(String str) {\n\t\treturn BooleanUtils.toBooleanObject(str);\n\t}\n\n\t/**\n\t * 支持true/false,on/off, y/n, yes/no的转换, str为空或无法分析时返回defaultValue\n\t */\n\tpublic static Boolean parseGeneralString(String str, Boolean defaultValue) {\n\t\treturn BooleanUtils.toBooleanDefaultIfNull(BooleanUtils.toBooleanObject(str), defaultValue);\n\t}\n\n\t/**\n\t * 取反\n\t */\n\tpublic static boolean negate(final boolean bool) {\n\t\treturn !bool;\n\t}\n\n\t/**\n\t * 取反\n\t */\n\tpublic static Boolean negate(final Boolean bool) {\n\t\treturn BooleanUtils.negate(bool);\n\t}\n\n\t/**\n\t * 多个值的and\n\t */\n\tpublic static boolean and(final boolean... array) {\n\t\treturn BooleanUtils.and(array);\n\t}\n\n\t/**\n\t * 多个值的or\n\t */\n\tpublic static boolean or(final boolean... array) {\n\t\treturn BooleanUtils.or(array);\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/EnumUtil.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport java.util.EnumSet;\n\nimport org.apache.commons.lang3.EnumUtils;\n\n/**\n * 枚举工具集\n * \n * 1. 将多个枚举值按bit与long的转换\n * \n * 2. 与String的转换\n * \n * 封装 {@code org.apache.commons.lang3.EnumUtils}\n */\npublic class EnumUtil {\n\n\t/**\n\t * 将若干个枚举值转换为long(按bits 1,2,4,8...的方式叠加)，用于使用long保存多个选项的情况.\n\t */\n\tpublic static > long generateBits(final Class enumClass, final Iterable values) {\n\t\treturn EnumUtils.generateBitVector(enumClass, values);\n\t}\n\n\t/**\n\t * 将若干个枚举值转换为long(按bits 1,2,4,8...的方式叠加)，用于使用long保存多个选项的情况.\n\t */\n\tpublic static > long generateBits(final Class enumClass, final E... values) {\n\t\treturn EnumUtils.generateBitVector(enumClass, values);\n\t}\n\n\t/**\n\t * long重新解析为若干个枚举值，用于使用long保存多个选项的情况.\n\t */\n\tpublic static > EnumSet processBits(final Class enumClass, final long value) {\n\t\treturn EnumUtils.processBitVector(enumClass, value);\n\t}\n\n\t/**\n\t * Enum转换为String\n\t */\n\tpublic static String toString(Enum e) {\n\t\treturn e.name();\n\t}\n\n\t/**\n\t * String转换为Enum\n\t */\n\tpublic static > T fromString(Class enumClass, String value) {\n\t\treturn Enum.valueOf(enumClass, value);\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/ExceptionUtil.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport java.io.PrintWriter;\nimport java.lang.reflect.UndeclaredThrowableException;\n\nimport org.apache.commons.lang3.ClassUtils;\nimport org.apache.commons.lang3.StringUtils;\nimport org.apache.commons.lang3.exception.ExceptionUtils;\n\nimport com.google.common.base.Throwables;\nimport com.vip.vjtools.vjkit.base.annotation.NotNull;\nimport com.vip.vjtools.vjkit.base.annotation.Nullable;\nimport com.vip.vjtools.vjkit.base.type.UncheckedException;\nimport com.vip.vjtools.vjkit.io.type.StringBuilderWriter;\n\n/**\n * 关于异常的工具类.\n * \n * 1. Checked/Unchecked及Wrap(如ExecutionException)的转换.\n * \n * 2. 打印Exception的辅助函数. (其中一些来自Common Lang ExceptionUtils)\n * \n * 3. 查找Cause(其中一些来自Guava Throwables)\n * \n * 4. StackTrace性能优化相关，尽量使用静态异常避免异常生成时获取StackTrace(Netty)\n * \n * @see com.vip.vjtools.vjkit.base.type.CloneableException\n */\npublic class ExceptionUtil {\n\n\tprivate static final StackTraceElement[] EMPTY_STACK_TRACE = new StackTraceElement[0];\n\n\t///// Checked/Unchecked及Wrap(如ExecutionException)的转换/////\n\n\t/**\n\t * 将CheckedException转换为RuntimeException重新抛出, 可以减少函数签名中的CheckException定义.\n\t * \n\t * CheckedException会用UndeclaredThrowableException包裹，RunTimeException和Error则不会被转变.\n\t * \n\t * copy from Commons Lang 3.5 ExceptionUtils.\n\t * \n\t * 虽然unchecked()里已直接抛出异常，但仍然定义返回值，方便欺骗Sonar。因此本函数也改变了一下返回值\n\t * \n\t * 示例代码:\n\t * \n\t * \n\t * try{ ... }catch(Exception e){ throw unchecked(t); }\n\t * \n\t * \n\t * @see ExceptionUtils#wrapAndThrow(Throwable)\n\t */\n\tpublic static RuntimeException unchecked(@Nullable Throwable t) {\n\t\tif (t instanceof RuntimeException) {\n\t\t\tthrow (RuntimeException) t;\n\t\t}\n\t\tif (t instanceof Error) {\n\t\t\tthrow (Error) t;\n\t\t}\n\n\t\tthrow new UncheckedException(t);\n\t}\n\n\t/**\n\t * 如果是著名的包裹类，从cause中获得真正异常. 其他异常则不变.\n\t * \n\t * Future中使用的ExecutionException 与 反射时定义的InvocationTargetException， 真正的异常都封装在Cause中\n\t * \n\t * 前面 unchecked() 使用的UncheckedException同理.\n\t */\n\tpublic static Throwable unwrap(@Nullable Throwable t) {\n\t\tif (t instanceof UncheckedException || t instanceof java.util.concurrent.ExecutionException\n\t\t\t\t|| t instanceof java.lang.reflect.InvocationTargetException\n\t\t\t\t|| t instanceof UndeclaredThrowableException) {\n\t\t\treturn t.getCause();\n\t\t}\n\n\t\treturn t;\n\t}\n\n\t/**\n\t * 组合unwrap与unchecked，用于处理反射/Callable的异常\n\t */\n\tpublic static RuntimeException unwrapAndUnchecked(@Nullable Throwable t) {\n\t\tthrow unchecked(unwrap(t));\n\t}\n\n\t////// 输出内容相关 //////\n\n\t/**\n\t * 将StackTrace[]转换为String, 供Logger或e.printStackTrace()外的其他地方使用.\n\t * \n\t * 为了使用StringBuilderWriter，没有用Throwables#getStackTraceAsString(Throwable)\n\t */\n\tpublic static String stackTraceText(@NotNull Throwable t) {\n\t\tStringBuilderWriter stringWriter = new StringBuilderWriter();\n\t\tt.printStackTrace(new PrintWriter(stringWriter)); // NOSONAR\n\t\treturn stringWriter.toString();\n\t}\n\n\t/**\n\t * 拼装 短异常类名: 异常信息.\n\t * \n\t * 与Throwable.toString()相比使用了短类名\n\t * \n\t * @see ExceptionUtils#getMessage(Throwable)\n\t */\n\tpublic static String toStringWithShortName(@Nullable Throwable t) {\n\t\treturn ExceptionUtils.getMessage(t);\n\t}\n\n\t/**\n\t * 拼装 短异常类名: 异常信息 <-- RootCause的短异常类名: 异常信息\n\t */\n\tpublic static String toStringWithRootCause(@Nullable Throwable t) {\n\t\tif (t == null) {\n\t\t\treturn StringUtils.EMPTY;\n\t\t}\n\n\t\tfinal String clsName = ClassUtils.getShortClassName(t, null);\n\t\tfinal String message = StringUtils.defaultString(t.getMessage());\n\t\tThrowable cause = getRootCause(t);\n\n\t\tStringBuilder sb = new StringBuilder(128).append(clsName).append(\": \").append(message);\n\t\tif (cause != t) {\n\t\t\tsb.append(\"; <---\").append(toStringWithShortName(cause));\n\t\t}\n\n\t\treturn sb.toString();\n\t}\n\n\t////////// Cause 相关 /////////\n\n\t/**\n\t * 获取异常的Root Cause.\n\t * \n\t * 如无底层Cause, 则返回自身\n\t * \n\t * @see Throwables#getRootCause(Throwable)\n\t */\n\tpublic static Throwable getRootCause(@NotNull Throwable t) {\n\t\treturn Throwables.getRootCause(t);\n\t}\n\n\t/**\n\t * 获取某种类型的cause，如果没有则返回空\n\t * \n\t * copy from Jodd ExceptionUtil\n\t */\n\tpublic static T findCause(@NotNull Throwable throwable, Class cause) {\n\t\twhile (throwable != null) {\n\t\t\tif (throwable.getClass().equals(cause)) {\n\t\t\t\treturn (T) throwable;\n\t\t\t}\n\t\t\tthrowable = throwable.getCause();\n\t\t}\n\t\treturn null;\n\t}\n\n\t/**\n\t * 判断异常是否由某些底层的异常引起.\n\t */\n\t@SuppressWarnings(\"unchecked\")\n\tpublic static boolean isCausedBy(@Nullable Throwable throwable,\n\t\t\tClass... causeExceptionClasses) {\n\t\tThrowable cause = throwable;\n\n\t\twhile (cause != null) {\n\t\t\tfor (Class causeClass : causeExceptionClasses) {\n\t\t\t\tif (causeClass.isInstance(cause)) {\n\t\t\t\t\treturn true;\n\t\t\t\t}\n\t\t\t}\n\t\t\tcause = cause.getCause();\n\t\t}\n\t\treturn false;\n\t}\n\t/////////// StackTrace 性能优化相关////////\n\n\t/**\n\t * copy from Netty, 为静态异常设置StackTrace.\n\t * \n\t * 对某些已知且经常抛出的异常, 不需要每次创建异常类并很消耗性能的并生成完整的StackTrace. 此时可使用静态声明的异常.\n\t * \n\t * 如果异常可能在多个地方抛出，使用本函数设置抛出的类名和方法名.\n\t * \n\t * \n\t * private static RuntimeException TIMEOUT_EXCEPTION = ExceptionUtil.setStackTrace(new RuntimeException(\"Timeout\"),\n\t * \t\tMyClass.class, \"mymethod\");\n\t * \n\t */\n\tpublic static T setStackTrace(@NotNull T throwable, Class throwClass, String throwClazz) {\n\t\tthrowable.setStackTrace(\n\t\t\t\tnew StackTraceElement[] { new StackTraceElement(throwClass.getName(), throwClazz, null, -1) });\n\t\treturn throwable;\n\t}\n\n\t/**\n\t * 清除StackTrace. 假设StackTrace已生成, 但把它打印出来也有不小的消耗.\n\t * \n\t * 如果不能控制StackTrace的生成，也不能控制它的打印端(如logger)，可用此方法暴力清除Trace.\n\t * \n\t * 但Cause链依然不能清除, 只能清除每一个Cause的StackTrace.\n\t */\n\tpublic static T clearStackTrace(@NotNull T throwable) {\n\t\tThrowable cause = throwable;\n\t\twhile (cause != null) {\n\t\t\tcause.setStackTrace(EMPTY_STACK_TRACE);\n\t\t\tcause = cause.getCause();\n\t\t}\n\t\treturn throwable;\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/MoreValidate.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport com.vip.vjtools.vjkit.base.annotation.Nullable;\n\n/**\n * 参数校验统一使用Apache Common Lang Validate, 补充一些缺少的.\n * \n * 为什么不用Guava的{@code com.google.common.base.Preconditions} , 一是少打几个字而已, 二是Validate的方法多，比如noNullElements()判断多个元素都不为空\n * \n * 目前主要参考 {@code com.google.common.math.MathPreconditions} , 补充数字为正数或非负数的校验\n * \n */\npublic class MoreValidate extends org.apache.commons.lang3.Validate {\n\n\t/**\n\t * 校验为正数则返回该数字，否则抛出异常.\n\t */\n\tpublic static int positive(@Nullable String role, int x) {\n\t\tif (x <= 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be > 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为正数则返回该数字，否则抛出异常.\n\t */\n\tpublic static Integer positive(@Nullable String role, Integer x) {\n\t\tif (x.intValue() <= 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be > 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为正数则返回该数字，否则抛出异常.\n\t */\n\tpublic static long positive(@Nullable String role, long x) {\n\t\tif (x <= 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be > 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为正数则返回该数字，否则抛出异常.\n\t */\n\tpublic static Long positive(@Nullable String role, Long x) {\n\t\tif (x.longValue() <= 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be > 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为正数则返回该数字，否则抛出异常.\n\t */\n\tpublic static double positive(@Nullable String role, double x) {\n\t\tif (!(x > 0)) { // not x < 0, to work with NaN.\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be >= 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为非负数则返回该数字，否则抛出异常.\n\t */\n\tpublic static int nonNegative(@Nullable String role, int x) {\n\t\tif (x < 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be >= 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为非负数则返回该数字，否则抛出异常.\n\t */\n\tpublic static Integer nonNegative(@Nullable String role, Integer x) {\n\t\tif (x.intValue() < 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be >= 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为非负数则返回该数字，否则抛出异常.\n\t */\n\tpublic static long nonNegative(@Nullable String role, long x) {\n\t\tif (x < 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be >= 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为非负数则返回该数字，否则抛出异常.\n\t */\n\tpublic static Long nonNegative(@Nullable String role, Long x) {\n\t\tif (x.longValue() < 0) {\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be >= 0\");\n\t\t}\n\t\treturn x;\n\t}\n\n\t/**\n\t * 校验为非负数则返回该数字，否则抛出异常.\n\t */\n\tpublic static double nonNegative(@Nullable String role, double x) {\n\t\tif (!(x >= 0)) { // not x < 0, to work with NaN.\n\t\t\tthrow new IllegalArgumentException(role + \" (\" + x + \") must be >= 0\");\n\t\t}\n\t\treturn x;\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/ObjectUtil.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport java.util.Arrays;\n\nimport com.google.common.base.Objects;\nimport com.vip.vjtools.vjkit.base.annotation.Nullable;\n\n/**\n * 1. Object打印优化，主要解决数组的打印\n * \n * 2. 多个对象的HashCode串联\n */\npublic class ObjectUtil {\n\n\tprivate static final String NULL = \"null\";\n\n\t/**\n\t * JDK7 引入的Null安全的equals\n\t */\n\tpublic static boolean equals(@Nullable Object a, @Nullable Object b) {\n\t\treturn Objects.equal(a, b);\n\t}\n\n\t/**\n\t * 多个对象的HashCode串联, 组成新的HashCode\n\t */\n\tpublic static int hashCode(Object... objects) {\n\t\treturn Arrays.hashCode(objects);\n\t}\n\n\t/**\n\t * 对象的toString(), 处理了对象为数组的情况，JDK的默认toString()只打数组的地址如 \"[Ljava.lang.Integer;@490d6c15.\n\t */\n\tpublic static String toPrettyString(Object value) {\n\t\tif (value == null) {\n\t\t\treturn NULL;\n\t\t}\n\n\t\tClass type = value.getClass();\n\n\t\tif (type.isArray()) {\n\t\t\tClass componentType = type.getComponentType();\n\n\t\t\tif (componentType.isPrimitive()) {\n\t\t\t\treturn primitiveArrayToString(value, componentType);\n\t\t\t} else {\n\t\t\t\treturn objectArrayToString(value);\n\t\t\t}\n\t\t} else if (value instanceof Iterable) {\n\t\t\t// 因为Collection的处理也是默认调用元素的toString(),\n\t\t\t// 为了处理元素是数组的情况，同样需要重载\n\t\t\treturn collectionToString(value);\n\t\t}\n\n\t\treturn value.toString();\n\t}\n\n\tprivate static String primitiveArrayToString(Object value, Class componentType) {\n\t\tStringBuilder sb = new StringBuilder();\n\n\t\tif (componentType == int.class) {\n\t\t\tsb.append(Arrays.toString((int[]) value));\n\t\t} else if (componentType == long.class) {\n\t\t\tsb.append(Arrays.toString((long[]) value));\n\t\t} else if (componentType == double.class) {\n\t\t\tsb.append(Arrays.toString((double[]) value));\n\t\t} else if (componentType == float.class) {\n\t\t\tsb.append(Arrays.toString((float[]) value));\n\t\t} else if (componentType == boolean.class) {\n\t\t\tsb.append(Arrays.toString((boolean[]) value));\n\t\t} else if (componentType == short.class) {\n\t\t\tsb.append(Arrays.toString((short[]) value));\n\t\t} else if (componentType == byte.class) {\n\t\t\tsb.append(Arrays.toString((byte[]) value));\n\t\t} else if (componentType == char.class) {\n\t\t\tsb.append(Arrays.toString((char[]) value));\n\t\t} else {\n\t\t\tthrow new IllegalArgumentException(\"unsupport array type\");\n\t\t}\n\n\t\treturn sb.toString();\n\t}\n\n\tprivate static String objectArrayToString(Object value) {\n\t\tStringBuilder sb = new StringBuilder();\n\t\tsb.append('[');\n\n\t\tObject[] array = (Object[]) value;\n\t\tfor (int i = 0; i < array.length; i++) {\n\t\t\tif (i > 0) {\n\t\t\t\tsb.append(\", \");\n\t\t\t}\n\t\t\tsb.append(toPrettyString(array[i]));\n\t\t}\n\t\tsb.append(']');\n\t\treturn sb.toString();\n\t}\n\n\tprivate static String collectionToString(Object value) {\n\t\tIterable iterable = (Iterable) value;\n\t\tStringBuilder sb = new StringBuilder();\n\t\tsb.append('{');\n\t\tint i = 0;\n\t\tfor (Object o : iterable) {\n\t\t\tif (i > 0) {\n\t\t\t\tsb.append(',');\n\t\t\t}\n\t\t\tsb.append(toPrettyString(o));\n\t\t\ti++;\n\t\t}\n\t\tsb.append('}');\n\t\treturn sb.toString();\n\t}\n\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/Platforms.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport java.io.File;\n\nimport org.apache.commons.lang3.SystemUtils;\n\n/**\n * 关于系统设定，平台信息的变量(via Common Lang SystemUtils)\n */\npublic class Platforms {\n\n\t// 文件路径分隔符\n\tpublic static final String FILE_PATH_SEPARATOR = File.separator;\n\tpublic static final char FILE_PATH_SEPARATOR_CHAR = File.separatorChar;\n\tpublic static final char WINDOWS_FILE_PATH_SEPARATOR_CHAR = '\\\\';\n\tpublic static final char LINUX_FILE_PATH_SEPARATOR_CHAR = '/';\n\n\t// ClassPath分隔符\n\tpublic static final String CLASS_PATH_SEPARATOR = File.pathSeparator;\n\tpublic static final char CLASS_PATH_SEPARATOR_CHAR = File.pathSeparatorChar;\n\n\t// 换行符\n\tpublic static final String LINE_SEPARATOR = System.lineSeparator();\n\n\t// 临时目录\n\tpublic static final String TMP_DIR = SystemUtils.JAVA_IO_TMPDIR;\n\t// 应用的工作目录\n\tpublic static final String WORKING_DIR = SystemUtils.USER_DIR;\n\t// 用户 HOME目录\n\tpublic static final String USER_HOME = SystemUtils.USER_HOME;\n\t// Java HOME目录\n\tpublic static final String JAVA_HOME = SystemUtils.JAVA_HOME;\n\n\t// Java版本\n\tpublic static final String JAVA_SPECIFICATION_VERSION = SystemUtils.JAVA_SPECIFICATION_VERSION; // e.g. 1.8\n\tpublic static final String JAVA_VERSION = SystemUtils.JAVA_VERSION; // e.g. 1.8.0_102\n\tpublic static final boolean IS_JAVA7 = SystemUtils.IS_JAVA_1_7;\n\tpublic static final boolean IS_JAVA8 = SystemUtils.IS_JAVA_1_8;\n\tpublic static final boolean IS_ATLEASET_JAVA7 = IS_JAVA7 || IS_JAVA8;\n\tpublic static final boolean IS_ATLEASET_JAVA8 = IS_JAVA8;\n\n\t// 操作系统类型及版本\n\tpublic static final String OS_NAME = SystemUtils.OS_NAME;\n\tpublic static final String OS_VERSION = SystemUtils.OS_VERSION;\n\tpublic static final String OS_ARCH = SystemUtils.OS_ARCH; // e.g. x86_64\n\tpublic static final boolean IS_LINUX = SystemUtils.IS_OS_LINUX;\n\tpublic static final boolean IS_UNIX = SystemUtils.IS_OS_UNIX;\n\tpublic static final boolean IS_WINDOWS = SystemUtils.IS_OS_WINDOWS;\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/PropertiesUtil.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport java.io.IOException;\nimport java.io.InputStreamReader;\nimport java.io.Reader;\nimport java.io.StringReader;\nimport java.util.Properties;\n\nimport org.slf4j.Logger;\nimport org.slf4j.LoggerFactory;\n\nimport com.vip.vjtools.vjkit.io.URLResourceUtil;\nimport com.vip.vjtools.vjkit.number.NumberUtil;\nimport com.vip.vjtools.vjkit.text.Charsets;\n\n/**\n * 关于Properties的工具类\n * \n * 1. 统一风格读取Properties到各种数据类型\n * \n * 2. 从文件或字符串装载Properties\n */\npublic class PropertiesUtil {\n\n\tprivate static Logger logger = LoggerFactory.getLogger(PropertiesUtil.class);\n\n\t/////////////////// 读取Properties ////////////////////\n\n\tpublic static Boolean getBoolean(Properties p, String name, Boolean defaultValue) {\n\t\treturn BooleanUtil.toBooleanObject(p.getProperty(name), defaultValue);\n\t}\n\n\tpublic static Integer getInt(Properties p, String name, Integer defaultValue) {\n\t\treturn NumberUtil.toIntObject(p.getProperty(name), defaultValue);\n\t}\n\n\tpublic static Long getLong(Properties p, String name, Long defaultValue) {\n\t\treturn NumberUtil.toLongObject(p.getProperty(name), defaultValue);\n\t}\n\n\tpublic static Double getDouble(Properties p, String name, Double defaultValue) {\n\t\treturn NumberUtil.toDoubleObject(p.getProperty(name), defaultValue);\n\t}\n\n\tpublic static String getString(Properties p, String name, String defaultValue) {\n\t\treturn p.getProperty(name, defaultValue);\n\t}\n\n\t/////////// 加载Properties////////\n\t/**\n\t * 从文件路径加载properties. 默认使用utf-8编码解析文件\n\t * \n\t * 路径支持从外部文件或resources文件加载, \"file://\"或无前缀代表外部文件, \"classpath:\"代表resources\n\t */\n\tpublic static Properties loadFromFile(String generalPath) {\n\t\tProperties p = new Properties();\n\t\ttry (Reader reader = new InputStreamReader(URLResourceUtil.asStream(generalPath), Charsets.UTF_8)) {\n\t\t\tp.load(reader);\n\t\t} catch (IOException e) {\n\t\t\tlogger.warn(\"Load property from \" + generalPath + \" failed\", e);\n\t\t}\n\t\treturn p;\n\t}\n\n\t/**\n\t * 从字符串内容加载Properties\n\t */\n\tpublic static Properties loadFromString(String content) {\n\t\tProperties p = new Properties();\n\t\ttry (Reader reader = new StringReader(content)) {\n\t\t\tp.load(reader);\n\t\t} catch (IOException ignored) { // NOSONAR\n\t\t}\n\t\treturn p;\n\t}\n\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/RuntimeUtil.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport java.lang.management.ManagementFactory;\nimport java.util.List;\nimport java.util.concurrent.atomic.AtomicInteger;\n\nimport org.apache.commons.lang3.StringUtils;\n\n/**\n * 运行时工具类\n * \n * 1.取得当前进程PID, JVM参数\n * \n * 2.注册JVM关闭钩子, 获得CPU核数\n * \n * 3.通过StackTrace 获得当前方法的类名方法名，调用者的类名方法名(获取StackTrace有消耗，不要滥用)\n */\npublic class RuntimeUtil {\n\n\tprivate static AtomicInteger shutdownHookThreadIndex = new AtomicInteger(0);\n\n\t/////// RuntimeMXBean相关 //////\n\n\t/**\n\t * 获得当前进程的PID\n\t * \n\t * 当失败时返回-1\n\t */\n\tpublic static int getPid() {\n\n\t\t// format: \"pid@hostname\"\n\t\tString jvmName = ManagementFactory.getRuntimeMXBean().getName();\n\t\tString[] split = jvmName.split(\"@\");\n\t\tif (split.length != 2) {\n\t\t\treturn -1;\n\t\t}\n\n\t\ttry {\n\t\t\treturn Integer.parseInt(split[0]);\n\t\t} catch (Exception e) { // NOSONAR\n\t\t\treturn -1;\n\t\t}\n\t}\n\n\t/**\n\t * 返回应用启动到现在的毫秒数\n\t */\n\tpublic static long getUpTime() {\n\t\treturn ManagementFactory.getRuntimeMXBean().getUptime();\n\t}\n\n\t/**\n\t * 返回输入的JVM参数列表\n\t */\n\tpublic static String getVmArguments() {\n\t\tList vmArguments = ManagementFactory.getRuntimeMXBean().getInputArguments();\n\t\treturn StringUtils.join(vmArguments, \" \");\n\t}\n\n\t//////////// Runtime 相关////////////////\n\t/**\n\t * 获取CPU核数\n\t */\n\tpublic static int getCores() {\n\t\treturn Runtime.getRuntime().availableProcessors();\n\t}\n\n\t/**\n\t * 注册JVM关闭时的钩子程序\n\t */\n\tpublic static void addShutdownHook(Runnable runnable) {\n\t\tRuntime.getRuntime().addShutdownHook(\n\t\t\t\tnew Thread(runnable, \"Thread-ShutDownHook-\" + shutdownHookThreadIndex.incrementAndGet()));\n\t}\n\n\t//////// 通过StackTrace 获得当前方法的调用者 ////\n\t/**\n\t * 通过StackTrace，获得调用者的类名.\n\t * \n\t * 获取StackTrace有消耗，不要滥用\n\t */\n\tpublic static String getCallerClass() {\n\t\tStackTraceElement[] stacktrace = Thread.currentThread().getStackTrace();\n\t\tif (stacktrace.length >= 4) {\n\t\t\tStackTraceElement element = stacktrace[3];\n\t\t\treturn element.getClassName();\n\t\t} else {\n\t\t\treturn StringUtils.EMPTY;\n\t\t}\n\t}\n\n\t/**\n\t * 通过StackTrace，获得调用者的\"类名.方法名()\"\n\t * \n\t * 获取StackTrace有消耗，不要滥用\n\t */\n\tpublic static String getCallerMethod() {\n\t\tStackTraceElement[] stacktrace = Thread.currentThread().getStackTrace();\n\t\tif (stacktrace.length >= 4) {\n\t\t\tStackTraceElement element = stacktrace[3];\n\t\t\treturn element.getClassName() + '.' + element.getMethodName() + \"()\";\n\t\t} else {\n\t\t\treturn StringUtils.EMPTY;\n\t\t}\n\t}\n\n\t/**\n\t * 通过StackTrace，获得当前方法的类名.\n\t * \n\t * 获取StackTrace有消耗，不要滥用\n\t */\n\tpublic static String getCurrentClass() {\n\t\tStackTraceElement[] stacktrace = Thread.currentThread().getStackTrace();\n\t\tif (stacktrace.length >= 3) {\n\t\t\tStackTraceElement element = stacktrace[2];\n\t\t\treturn element.getClassName();\n\t\t} else {\n\t\t\treturn StringUtils.EMPTY;\n\t\t}\n\t}\n\n\t/**\n\t * 通过StackTrace，获得当前方法的\"类名.方法名()\"\n\t * \n\t * 获取StackTrace有消耗，不要滥用\n\t */\n\tpublic static String getCurrentMethod() {\n\t\tStackTraceElement[] stacktrace = Thread.currentThread().getStackTrace();\n\t\tif (stacktrace.length >= 3) {\n\t\t\tStackTraceElement element = stacktrace[2];\n\t\t\treturn element.getClassName() + '.' + element.getMethodName() + \"()\";\n\t\t} else {\n\t\t\treturn StringUtils.EMPTY;\n\t\t}\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/SystemPropertiesUtil.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport java.util.List;\nimport java.util.Properties;\nimport java.util.concurrent.CopyOnWriteArrayList;\n\nimport com.vip.vjtools.vjkit.number.NumberUtil;\n\n/**\n * 关于SystemProperties的工具类\n * \n * 1. 统一风格的读取系统变量到各种数据类型，其中Boolean.readBoolean的风格不统一，Double则不支持，都进行了扩展.\n * \n * 2. 简单的合并系统变量(-D)，环境变量 和默认值，以系统变量优先，在未引入Commons Config时使用.\n * \n * 3. Properties 本质上是一个HashTable，每次读写都会加锁，所以不支持频繁的System.getProperty(name)来检查系统内容变化 因此扩展了一个ListenableProperties,\n * 在其所关心的属性变化时进行通知.\n */\npublic class SystemPropertiesUtil {\n\n\t/**\n\t * 读取Boolean类型的系统变量，为空时返回null，代表未设置，而不是Boolean.getBoolean()的false.\n\t */\n\tpublic static Boolean getBoolean(String name) {\n\t\tString stringResult = System.getProperty(name);\n\t\treturn BooleanUtil.toBooleanObject(stringResult);\n\t}\n\n\t/**\n\t * 读取Boolean类型的系统变量，为空时返回默认值, 而不是Boolean.getBoolean()的false.\n\t */\n\tpublic static Boolean getBoolean(String name, Boolean defaultValue) {\n\t\tString stringResult = System.getProperty(name);\n\t\treturn BooleanUtil.toBooleanObject(stringResult, defaultValue);\n\t}\n\n\t/**\n\t * 读取String类型的系统变量，为空时返回null.\n\t */\n\tpublic static String getString(String name) {\n\t\treturn System.getProperty(name);\n\t}\n\n\t/**\n\t * 读取String类型的系统变量，为空时返回默认值\n\t */\n\tpublic static String getString(String name, String defaultValue) {\n\t\treturn System.getProperty(name, defaultValue);\n\t}\n\n\t/**\n\t * 读取Integer类型的系统变量，为空时返回null.\n\t */\n\tpublic static Integer getInteger(String name) {\n\t\treturn Integer.getInteger(name);\n\t}\n\n\t/**\n\t * 读取Integer类型的系统变量，为空时返回默认值\n\t */\n\tpublic static Integer getInteger(String name, Integer defaultValue) {\n\t\treturn Integer.getInteger(name, defaultValue);\n\t}\n\n\t/**\n\t * 读取Long类型的系统变量，为空时返回null.\n\t */\n\tpublic static Long getLong(String name) {\n\t\treturn Long.getLong(name);\n\t}\n\n\t/**\n\t * 读取Integer类型的系统变量，为空时返回默认值\n\t */\n\tpublic static Long getLong(String name, Long defaultValue) {\n\t\treturn Long.getLong(name, defaultValue);\n\t}\n\n\t/**\n\t * 读取Double类型的系统变量，为空时返回null.\n\t */\n\tpublic static Double getDouble(String propertyName) {\n\t\treturn NumberUtil.toDoubleObject(System.getProperty(propertyName), null);\n\t}\n\n\t/**\n\t * 读取Double类型的系统变量，为空时返回默认值.\n\t */\n\tpublic static Double getDouble(String propertyName, Double defaultValue) {\n\t\tDouble propertyValue = NumberUtil.toDoubleObject(System.getProperty(propertyName), null);\n\t\treturn propertyValue != null ? propertyValue : defaultValue;\n\t}\n\n\t/////////// 简单的合并系统变量(-D)，环境变量 和默认值，以系统变量优先.///////////////\n\n\t/**\n\t * 合并系统变量(-D)，环境变量 和默认值，以系统变量优先\n\t */\n\tpublic static String getString(String propertyName, String envName, String defaultValue) {\n\t\tcheckEnvName(envName);\n\t\tString propertyValue = System.getProperty(propertyName);\n\t\tif (propertyValue != null) {\n\t\t\treturn propertyValue;\n\t\t} else {\n\t\t\tpropertyValue = System.getenv(envName);\n\t\t\treturn propertyValue != null ? propertyValue : defaultValue;\n\t\t}\n\t}\n\n\t/**\n\t * 合并系统变量(-D)，环境变量 和默认值，以系统变量优先\n\t */\n\tpublic static Integer getInteger(String propertyName, String envName, Integer defaultValue) {\n\t\tcheckEnvName(envName);\n\t\tInteger propertyValue = NumberUtil.toIntObject(System.getProperty(propertyName), null);\n\t\tif (propertyValue != null) {\n\t\t\treturn propertyValue;\n\t\t} else {\n\t\t\tpropertyValue = NumberUtil.toIntObject(System.getenv(envName), null);\n\t\t\treturn propertyValue != null ? propertyValue : defaultValue;\n\t\t}\n\t}\n\n\t/**\n\t * 合并系统变量(-D)，环境变量 和默认值，以系统变量优先\n\t */\n\tpublic static Long getLong(String propertyName, String envName, Long defaultValue) {\n\t\tcheckEnvName(envName);\n\t\tLong propertyValue = NumberUtil.toLongObject(System.getProperty(propertyName), null);\n\t\tif (propertyValue != null) {\n\t\t\treturn propertyValue;\n\t\t} else {\n\t\t\tpropertyValue = NumberUtil.toLongObject(System.getenv(envName), null);\n\t\t\treturn propertyValue != null ? propertyValue : defaultValue;\n\t\t}\n\t}\n\n\t/**\n\t * 合并系统变量(-D)，环境变量 和默认值，以系统变量优先\n\t */\n\tpublic static Double getDouble(String propertyName, String envName, Double defaultValue) {\n\t\tcheckEnvName(envName);\n\t\tDouble propertyValue = NumberUtil.toDoubleObject(System.getProperty(propertyName), null);\n\t\tif (propertyValue != null) {\n\t\t\treturn propertyValue;\n\t\t} else {\n\t\t\tpropertyValue = NumberUtil.toDoubleObject(System.getenv(envName), null);\n\t\t\treturn propertyValue != null ? propertyValue : defaultValue;\n\t\t}\n\t}\n\n\t/**\n\t * 合并系统变量(-D)，环境变量 和默认值，以系统变量优先\n\t */\n\tpublic static Boolean getBoolean(String propertyName, String envName, Boolean defaultValue) {\n\t\tcheckEnvName(envName);\n\t\tBoolean propertyValue = BooleanUtil.toBooleanObject(System.getProperty(propertyName), null);\n\t\tif (propertyValue != null) {\n\t\t\treturn propertyValue;\n\t\t} else {\n\t\t\tpropertyValue = BooleanUtil.toBooleanObject(System.getenv(envName), null);\n\t\t\treturn propertyValue != null ? propertyValue : defaultValue;\n\t\t}\n\t}\n\n\t/**\n\t * 检查环境变量名不能有'.'，在linux下不支持\n\t */\n\tprivate static void checkEnvName(String envName) {\n\t\tif (envName == null || envName.indexOf('.') != -1) {\n\t\t\tthrow new IllegalArgumentException(\"envName \" + envName + \"is null or has dot which is not valid\");\n\t\t}\n\t}\n\n\t/////////// ListenableProperties /////////////\n\t/**\n\t * Properties 本质上是一个HashTable，每次读写都会加锁，所以不支持频繁的System.getProperty(name)来检查系统内容变化 因此扩展了一个ListenableProperties,\n\t * 在其所关心的属性变化时进行通知.\n\t * \n\t * @see ListenableProperties\n\t */\n\tpublic static synchronized void registerSystemPropertiesListener(PropertiesListener listener) {\n\t\tProperties currentProperties = System.getProperties();\n\n\t\t// 将System的properties实现替换为ListenableProperties\n\t\tif (!(currentProperties instanceof ListenableProperties)) {\n\t\t\tListenableProperties newProperties = new ListenableProperties(currentProperties);\n\t\t\tSystem.setProperties(newProperties);\n\t\t\tcurrentProperties = newProperties;\n\t\t}\n\n\t\t((ListenableProperties) currentProperties).register(listener);\n\t}\n\n\t/**\n\t * Properties 本质上是一个HashTable，每次读写都会加锁，所以不支持频繁的System.getProperty(name)来检查系统内容变化 因此扩展了Properties子类,\n\t * 在其所关心的属性变化时进行通知.\n\t * \n\t * @see PropertiesListener\n\t */\n\tpublic static class ListenableProperties extends Properties {\n\n\t\tprivate static final long serialVersionUID = -8282465702074684324L;\n\n\t\tprotected transient List listeners = new CopyOnWriteArrayList();\n\n\t\tpublic ListenableProperties(Properties properties) {\n\t\t\tsuper(properties);\n\t\t}\n\n\t\tpublic void register(PropertiesListener listener) {\n\t\t\tlisteners.add(listener);\n\t\t}\n\n\t\t@Override\n\t\tpublic synchronized Object setProperty(String key, String value) {\n\t\t\tObject result = put(key, value);\n\t\t\tfor (PropertiesListener listener : listeners) {\n\t\t\t\tif (listener.propertyName.equals(key)) {\n\t\t\t\t\tlistener.onChange(key, value);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn result;\n\t\t}\n\t}\n\n\t/**\n\t * 获取所关心的Property变更的Listener基类.\n\t */\n\tpublic abstract static class PropertiesListener {\n\n\t\t// 关心的Property\n\t\tprotected String propertyName;\n\n\t\tpublic PropertiesListener(String propertyName) {\n\t\t\tthis.propertyName = propertyName;\n\t\t}\n\n\t\tpublic abstract void onChange(String propertyName, String value);\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/ValueValidator.java",
"content": "package com.vip.vjtools.vjkit.base;\n\nimport org.apache.commons.lang3.StringUtils;\n\n/**\n * 数值校验取值器 \n * \n * 提供对配置值进行校验，并根据结果决定是否使用默认值。\n * \n * Guava, Commons Lang里的Validate类用于判断并抛异常。\n * \n * 而ValueValidator的行为是取默认值，多用于配置值的处理。\n * \n * 除默认提供的Validator，可自行扩写。\n */\npublic class ValueValidator {\n\n\t/**\n\t * 对目标值进行校验，并根据校验结果取值\n\t * \n\t * 使用示例(校验目标值是否大于0, 如果小于 0 则取值为 1)\n\t * \n\t * ValueValidator.checkAndGet(idleTime, 1, Validator.INTEGER_GT_ZERO_VALIDATOR)\n\t * \n\t * @param value 校验值\n\t * @param defaultValue 校验失败默认值\n\t * @param v 校验器\n\t * @return 经Validator校验后的返回值，校验成功返回 value, 校验失败返回 defaultValue\n\t */\n\tpublic static T checkAndGet(T value, T defaultValue, Validator v) {\n\t\tif (v.validate(value)) {\n\t\t\treturn value;\n\t\t}\n\n\t\treturn defaultValue;\n\t}\n\n\t/**\n\t * 对值进行规则匹配的验证器\n\t */\n\tpublic interface Validator {\n\t\t/**\n\t\t * 校验值是否匹配\n\t\t */\n\t\tboolean validate(T value);\n\n\t\t/**\n\t\t * 校验器: 数值配置不为null, 且大于0较验\n\t\t */\n\t\tValidator INTEGER_GT_ZERO_VALIDATOR = new Validator() {\n\t\t\t@Override\n\t\t\tpublic boolean validate(Integer value) {\n\t\t\t\treturn (value != null && value > 0);\n\t\t\t}\n\t\t};\n\n\t\t/**\n\t\t * 校验器: 字符串不为空串较验\n\t\t */\n\t\tValidator STRING_EMPTY_VALUE_VALIDATOR = new Validator() {\n\t\t\t@Override\n\t\t\tpublic boolean validate(String value) {\n\t\t\t\treturn StringUtils.isNotEmpty(value);\n\t\t\t}\n\t\t};\n\n\t\t/**\n\t\t * 校验器: BOOL字符串较验\n\t\t */\n\t\tValidator STRICT_BOOL_VALUE_VALIDATOR = new Validator() {\n\t\t\t@Override\n\t\t\tpublic boolean validate(String value) {\n\t\t\t\treturn \"true\".equalsIgnoreCase(value) || \"false\".equalsIgnoreCase(value);\n\t\t\t}\n\t\t};\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/annotation/NotNull.java",
"content": "package com.vip.vjtools.vjkit.base.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Target;\n\n/**\n * 标注参数、属性、方法不可为 Null\n */\n@Target({ ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD })\npublic @interface NotNull {\n\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/annotation/Nullable.java",
"content": "package com.vip.vjtools.vjkit.base.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Target;\n\n/**\n * 标注参数、属性、方法可为 Null\n */\n@Target({ ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD })\npublic @interface Nullable {\n\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/annotation/VisibleForTesting.java",
"content": "package com.vip.vjtools.vjkit.base.annotation;\n\n/**\n * 标注因为方便UT，将方法／属性的可访问范围扩大了，参考Guava\n */\npublic @interface VisibleForTesting {\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/type/CloneableException.java",
"content": "package com.vip.vjtools.vjkit.base.type;\n\nimport com.vip.vjtools.vjkit.base.ExceptionUtil;\n\n/**\n * 适用于异常信息需要变更的情况, 可通过clone()，不经过构造函数（也就避免了获得StackTrace）地从之前定义的静态异常中克隆，再设定新的异常信息\n * \n * private static CloneableException TIMEOUT_EXCEPTION = new CloneableException(\"Timeout\") .setStackTrace(My.class,\n * \"hello\"); ...\n * \n * throw TIMEOUT_EXCEPTION.clone(\"Timeout for 40ms\");\n * \n */\npublic class CloneableException extends Exception implements Cloneable {\n\n\tprivate static final long serialVersionUID = -6270471689928560417L;\n\n\tprotected String message; // NOSONAR\n\n\tpublic CloneableException() {\n\t\tsuper((Throwable) null);\n\t}\n\n\tpublic CloneableException(String message) {\n\t\tsuper((Throwable) null);\n\t\tthis.message = message;\n\t}\n\n\tpublic CloneableException(String message, Throwable cause) {\n\t\tsuper(cause);\n\t\tthis.message = message;\n\t}\n\n\t@Override\n\tpublic CloneableException clone() { // NOSONAR\n\t\ttry {\n\t\t\treturn (CloneableException) super.clone();\n\t\t} catch (CloneNotSupportedException e) {// NOSONAR\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t@Override\n\tpublic String getMessage() {\n\t\treturn message;\n\t}\n\n\t/**\n\t * 简便函数，定义静态异常时使用\n\t */\n\tpublic CloneableException setStackTrace(Class throwClazz, String throwMethod) {\n\t\tExceptionUtil.setStackTrace(this, throwClazz, throwMethod);\n\t\treturn this;\n\t}\n\n\t/**\n\t * 简便函数, clone并重新设定Message\n\t */\n\tpublic CloneableException clone(String message) {\n\t\tCloneableException newException = this.clone();\n\t\tnewException.setMessage(message);\n\t\treturn newException;\n\t}\n\n\t/**\n\t * 简便函数, 重新设定Message\n\t */\n\tpublic CloneableException setMessage(String message) {\n\t\tthis.message = message;\n\t\treturn this;\n\t}\n}"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/type/CloneableRuntimeException.java",
"content": "package com.vip.vjtools.vjkit.base.type;\n\nimport com.vip.vjtools.vjkit.base.ExceptionUtil;\n\n/**\n * 适用于异常信息需要变更的情况, 可通过clone()，不经过构造函数（也就避免了获得StackTrace）地从之前定义的静态异常中克隆，再设定新的异常信息\n * \n * @see CloneableException\n */\npublic class CloneableRuntimeException extends RuntimeException implements Cloneable {\n\n\tprivate static final long serialVersionUID = 3984796576627959400L;\n\n\tprotected String message; // NOSONAR\n\n\tpublic CloneableRuntimeException() {\n\t\tsuper((Throwable) null);\n\t}\n\n\tpublic CloneableRuntimeException(String message) {\n\t\tsuper((Throwable) null);\n\t\tthis.message = message;\n\t}\n\n\tpublic CloneableRuntimeException(String message, Throwable cause) {\n\t\tsuper(cause);\n\t\tthis.message = message;\n\t}\n\n\t@Override\n\tpublic CloneableRuntimeException clone() { // NOSONAR\n\t\ttry {\n\t\t\treturn (CloneableRuntimeException) super.clone();\n\t\t} catch (CloneNotSupportedException e) { // NOSONAR\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t@Override\n\tpublic String getMessage() {\n\t\treturn message;\n\t}\n\n\t/**\n\t * 简便函数，定义静态异常时使用\n\t */\n\tpublic CloneableRuntimeException setStackTrace(Class throwClazz, String throwMethod) {\n\t\tExceptionUtil.setStackTrace(this, throwClazz, throwMethod);\n\t\treturn this;\n\t}\n\n\t/**\n\t * 简便函数, clone并重新设定Message\n\t */\n\tpublic CloneableRuntimeException clone(String message) {\n\t\tCloneableRuntimeException newException = this.clone();\n\t\tnewException.setMessage(message);\n\t\treturn newException;\n\t}\n\n\t/**\n\t * 简便函数, 重新设定Message\n\t */\n\tpublic CloneableRuntimeException setMessage(String message) {\n\t\tthis.message = message;\n\t\treturn this;\n\t}\n}"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/type/Pair.java",
"content": "package com.vip.vjtools.vjkit.base.type;\n\nimport com.vip.vjtools.vjkit.base.annotation.Nullable;\n\n/**\n * 引入一个简简单单的Pair, 用于返回值返回两个元素.\n *\n * copy from Twitter Common\n */\npublic class Pair {\n\n\t@Nullable\n\tprivate final L left;\n\t@Nullable\n\tprivate final R right;\n\n\t/**\n\t * Creates a new pair.\n\t */\n\tpublic Pair(@Nullable L left, @Nullable R right) {\n\t\tthis.left = left;\n\t\tthis.right = right;\n\t}\n\n\t@Nullable\n\tpublic L getLeft() {\n\t\treturn left;\n\t}\n\n\t@Nullable\n\tpublic R getRight() {\n\t\treturn right;\n\t}\n\n\t@Override\n\tpublic int hashCode() {\n\t\tfinal int prime = 31;\n\t\tint result = 1;\n\t\tresult = prime * result + ((left == null) ? 0 : left.hashCode());\n\t\treturn prime * result + ((right == null) ? 0 : right.hashCode());\n\t}\n\n\t@Override\n\tpublic boolean equals(Object obj) {\n\t\tif (this == obj) {\n\t\t\treturn true;\n\t\t}\n\t\tif (obj == null || getClass() != obj.getClass()) {\n\t\t\treturn false;\n\t\t}\n\t\tPair other = (Pair) obj;\n\t\tif (left == null) {\n\t\t\tif (other.left != null) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else if (!left.equals(other.left)) {\n\t\t\treturn false;\n\t\t}\n\t\tif (right == null) {\n\t\t\tif (other.right != null) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else if (!right.equals(other.right)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\t@Override\n\tpublic String toString() {\n\t\treturn \"Pair [left=\" + left + \", right=\" + right + ']';\n\t}\n\n\t/**\n\t * 根据等号左边的泛型，自动构造合适的Pair\n\t */\n\tpublic static Pair of(@Nullable L left, @Nullable R right) {\n\t\treturn new Pair(left, right);\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/type/Triple.java",
"content": "package com.vip.vjtools.vjkit.base.type;\n\nimport com.vip.vjtools.vjkit.base.annotation.Nullable;\n\n/**\n * 引入一个简简单单的Triple, 用于返回值返回三个元素.\n *\n * copy from Twitter Common\n */\npublic class Triple {\n\n\t@Nullable\n\tprivate final L left;\n\t@Nullable\n\tprivate final M middle;\n\t@Nullable\n\tprivate final R right;\n\n\t/**\n\t * Creates a new Triple.\n\t */\n\tpublic Triple(@Nullable L left, @Nullable M middle, @Nullable R right) {\n\t\tthis.left = left;\n\t\tthis.middle = middle;\n\t\tthis.right = right;\n\t}\n\n\t@Nullable\n\tpublic L getLeft() {\n\t\treturn left;\n\t}\n\n\t@Nullable\n\tpublic M getMiddle() {\n\t\treturn middle;\n\t}\n\n\t@Nullable\n\tpublic R getRight() {\n\t\treturn right;\n\t}\n\n\t@Override\n\tpublic int hashCode() {\n\t\tfinal int prime = 31;\n\t\tint result = 1;\n\t\tresult = prime * result + ((left == null) ? 0 : left.hashCode());\n\t\tresult = prime * result + ((middle == null) ? 0 : middle.hashCode());\n\t\treturn prime * result + ((right == null) ? 0 : right.hashCode());\n\t}\n\n\t@Override\n\tpublic boolean equals(Object obj) {\n\t\tif (this == obj) {\n\t\t\treturn true;\n\t\t}\n\t\tif (obj == null || getClass() != obj.getClass()) {\n\t\t\treturn false;\n\t\t}\n\t\tTriple other = (Triple) obj;\n\t\tif (left == null) {\n\t\t\tif (other.left != null) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else if (!left.equals(other.left)) {\n\t\t\treturn false;\n\t\t}\n\t\tif (middle == null) {\n\t\t\tif (other.middle != null) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else if (!middle.equals(other.middle)) {\n\t\t\treturn false;\n\t\t}\n\t\tif (right == null) {\n\t\t\tif (other.right != null) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else if (!right.equals(other.right)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\t@Override\n\tpublic String toString() {\n\t\treturn \"Triple [left=\" + left + \", middle=\" + middle + \", right=\" + right + ']';\n\t}\n\n\t/**\n\t * 根据等号左边的泛型，自动构造合适的Triple\n\t */\n\tpublic static Triple of(@Nullable L left, @Nullable M middle, @Nullable R right) {\n\t\treturn new Triple(left, middle, right);\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/base/type/UncheckedException.java",
"content": "package com.vip.vjtools.vjkit.base.type;\n\n/**\n * CheckedException的wrapper.\n * \n * 返回Message时, 将返回内层Exception的Message.\n */\npublic class UncheckedException extends RuntimeException {\n\n\tprivate static final long serialVersionUID = 4140223302171577501L;\n\n\tpublic UncheckedException(Throwable wrapped) {\n\t\tsuper(wrapped);\n\t}\n\n\t@Override\n\tpublic String getMessage() {\n\t\treturn super.getCause().getMessage();\n\t}\n}"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/collection/ArrayUtil.java",
"content": "package com.vip.vjtools.vjkit.collection;\n\nimport java.lang.reflect.Array;\nimport java.util.Arrays;\nimport java.util.Collection;\nimport java.util.List;\nimport java.util.Random;\n\nimport com.google.common.collect.ObjectArrays;\nimport com.google.common.primitives.Doubles;\nimport com.google.common.primitives.Ints;\nimport com.google.common.primitives.Longs;\nimport com.vip.vjtools.vjkit.base.annotation.Nullable;\n\n/**\n * 数组工具类.\n * \n * 1. 创建Array的函数\n * \n * 2. 数组的乱序与contact相加\n * \n * 3. 从Array转换到Guava的底层为原子类型的List\n * \n * JDK Arrays的其他函数，如sort(), toString() 请直接调用\n * \n * Common Lang ArrayUtils的其他函数，如subarray(),reverse(),indexOf(), 请直接调用\n */\npublic class ArrayUtil {\n\n\t/**\n\t * 传入类型与大小创建数组.\n\t * \n\t * Array.newInstance()的性能并不差\n\t */\n\t@SuppressWarnings(\"unchecked\")\n\tpublic static T[] newArray(Class type, int length) {\n\t\treturn (T[]) Array.newInstance(type, length);\n\t}\n\n\t/**\n\t * 从collection转为Array, 以 list.toArray(new String[0]); 最快 不需要创建list.size()的数组.\n\t * \n\t * 本函数等价于list.toArray(new String[0]); 用户也可以直接用后者.\n\t * \n\t * https://shipilev.net/blog/2016/arrays-wisdom-ancients/\n\t */\n\t@SuppressWarnings(\"unchecked\")\n\tpublic static T[] toArray(Collection col, Class type) {\n\t\treturn col.toArray((T[]) Array.newInstance(type, 0));\n\t}\n\n\t/**\n\t * Swaps the two specified elements in the specified array.\n\t */\n\tprivate static void swap(Object[] arr, int i, int j) {\n\t\tObject tmp = arr[i];\n\t\tarr[i] = arr[j];\n\t\tarr[j] = tmp;\n\t}\n\n\t/**\n\t * 将传入的数组乱序\n\t */\n\tpublic static T[] shuffle(T[] array) {\n\t\tif (array != null && array.length > 1) {\n\t\t\tRandom rand = new Random();\n\t\t\treturn shuffle(array, rand);\n\t\t} else {\n\t\t\treturn array;\n\t\t}\n\t}\n\n\t/**\n\t * 将传入的数组乱序\n\t */\n\tpublic static T[] shuffle(T[] array, Random random) {\n\t\tif (array != null && array.length > 1 && random != null) {\n\t\t\tfor (int i = array.length; i > 1; i--) {\n\t\t\t\tswap(array, i - 1, random.nextInt(i));\n\t\t\t}\n\t\t}\n\t\treturn array;\n\t}\n\n\t/**\n\t * 添加元素到数组头.\n\t */\n\tpublic static T[] concat(@Nullable T element, T[] array) {\n\t\treturn ObjectArrays.concat(element, array);\n\t}\n\n\t/**\n\t * 添加元素到数组末尾.\n\t */\n\tpublic static T[] concat(T[] array, @Nullable T element) {\n\t\treturn ObjectArrays.concat(array, element);\n\t}\n\n\t////////////////// guava Array 转换为底层为原子类型的List ///////////\n\t/**\n\t * 原版将数组转换为List.\n\t * \n\t * 注意转换后的List不能写入, 否则抛出UnsupportedOperationException\n\t * \n\t * @see java.util.Arrays#asList(Object...)\n\t */\n\tpublic static List asList(T... a) {\n\t\treturn Arrays.asList(a);\n\t}\n\n\t/**\n\t * Arrays.asList()的加强版, 返回一个底层为原始类型int的List\n\t * \n\t * 与保存Integer相比节约空间，同时只在读取数据时AutoBoxing.\n\t * \n\t * @see java.util.Arrays#asList(Object...)\n\t * @see com.google.common.primitives.Ints#asList(int...)\n\t * \n\t */\n\tpublic static List intAsList(int... backingArray) {\n\t\treturn Ints.asList(backingArray);\n\t}\n\n\t/**\n\t * Arrays.asList()的加强版, 返回一个底层为原始类型long的List\n\t * \n\t * 与保存Long相比节约空间，同时只在读取数据时AutoBoxing.\n\t * \n\t * @see java.util.Arrays#asList(Object...)\n\t * @see com.google.common.primitives.Longs#asList(long...)\n\t */\n\tpublic static List longAsList(long... backingArray) {\n\t\treturn Longs.asList(backingArray);\n\t}\n\n\t/**\n\t * Arrays.asList()的加强版, 返回一个底层为原始类型double的List\n\t * \n\t * 与保存Double相比节约空间，同时也避免了AutoBoxing.\n\t * \n\t * @see java.util.Arrays#asList(Object...)\n\t * @see com.google.common.primitives.Doubles#asList(double...)\n\t */\n\tpublic static List doubleAsList(double... backingArray) {\n\t\treturn Doubles.asList(backingArray);\n\t}\n\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/collection/CollectionUtil.java",
"content": "package com.vip.vjtools.vjkit.collection;\n\nimport java.util.Collection;\nimport java.util.Collections;\nimport java.util.Comparator;\nimport java.util.Iterator;\nimport java.util.List;\n\nimport com.google.common.collect.Iterables;\nimport com.google.common.collect.Iterators;\nimport com.google.common.collect.Ordering;\nimport com.vip.vjtools.vjkit.base.type.Pair;\n\n/**\n * 通用Collection的工具集\n * \n * 1. 集合是否为空，取得集合中首个及最后一个元素，判断集合是否完全相等\n * \n * 2. 集合的最大最小值，及Top N, Bottom N\n * \n * 关于List, Map, Queue, Set的特殊工具集，另见特定的Util.\n * \n * 另JDK中缺少ComparableComparator和NullComparator，直到JDK8才补上。\n * 因此平时请使用guava的Ordering.natural(),fluentable的API更好用，可以链式设置nullFirst，nullLast,reverse\n * \n * @see com.google.common.collect.Ordering\n */\npublic class CollectionUtil {\n\n\t/**\n\t * 判断是否为空.\n\t */\n\tpublic static boolean isEmpty(Collection collection) {\n\t\treturn (collection == null) || collection.isEmpty();\n\t}\n\n\t/**\n\t * 判断是否不为空.\n\t */\n\tpublic static boolean isNotEmpty(Collection collection) {\n\t\treturn (collection != null) && !(collection.isEmpty());\n\t}\n\n\t/**\n\t * 取得Collection的第一个元素，如果collection为空返回null.\n\t */\n\tpublic static T getFirst(Collection collection) {\n\t\tif (isEmpty(collection)) {\n\t\t\treturn null;\n\t\t}\n\t\tif (collection instanceof List) {\n\t\t\treturn ((List) collection).get(0);\n\t\t}\n\t\treturn collection.iterator().next();\n\t}\n\n\t/**\n\t * 获取Collection的最后一个元素，如果collection为空返回null.\n\t */\n\tpublic static T getLast(Collection collection) {\n\t\tif (isEmpty(collection)) {\n\t\t\treturn null;\n\t\t}\n\n\t\t// 当类型List时，直接取得最后一个元素.\n\t\tif (collection instanceof List) {\n\t\t\tList list = (List) collection;\n\t\t\treturn list.get(list.size() - 1);\n\t\t}\n\n\t\treturn Iterators.getLast(collection.iterator());\n\t}\n\n\t/**\n\t * 两个集合中的所有元素按顺序相等.\n\t */\n\tpublic static boolean elementsEqual(Iterable iterable1, Iterable iterable2) {\n\t\treturn Iterables.elementsEqual(iterable1, iterable2);\n\t}\n\n\t///////////// 求最大最小值，及Top N, Bottom N//////////\n\t/**\n\t * 返回无序集合中的最小值，使用元素默认排序\n\t */\n\tpublic static > T min(Collection coll) {\n\t\treturn Collections.min(coll);\n\t}\n\n\t/**\n\t * 返回无序集合中的最小值\n\t */\n\tpublic static T min(Collection coll, Comparator comp) {\n\t\treturn Collections.min(coll, comp);\n\t}\n\n\t/**\n\t * 返回无序集合中的最大值，使用元素默认排序\n\t */\n\tpublic static > T max(Collection coll) {\n\t\treturn Collections.max(coll);\n\t}\n\n\t/**\n\t * 返回无序集合中的最大值\n\t */\n\tpublic static T max(Collection coll, Comparator comp) {\n\t\treturn Collections.max(coll, comp);\n\t}\n\n\t/**\n\t * 同时返回无序集合中的最小值和最大值，使用元素默认排序\n\t * \n\t * 在返回的Pair中，第一个为最小值，第二个为最大值\n\t */\n\tpublic static > Pair minAndMax(Collection coll) {\n\t\tIterator i = coll.iterator();\n\t\tT minCandidate = i.next();\n\t\tT maxCandidate = minCandidate;\n\n\t\twhile (i.hasNext()) {\n\t\t\tT next = i.next();\n\t\t\tif (next.compareTo(minCandidate) < 0) {\n\t\t\t\tminCandidate = next;\n\t\t\t} else if (next.compareTo(maxCandidate) > 0) {\n\t\t\t\tmaxCandidate = next;\n\t\t\t}\n\t\t}\n\t\treturn Pair.of(minCandidate, maxCandidate);\n\t}\n\n\t/**\n\t * 返回无序集合中的最小值和最大值\n\t * \n\t * 在返回的Pair中，第一个为最小值，第二个为最大值\n\t */\n\tpublic static Pair minAndMax(Collection coll, Comparator comp) {\n\n\t\tIterator i = coll.iterator();\n\t\tT minCandidate = i.next();\n\t\tT maxCandidate = minCandidate;\n\n\t\twhile (i.hasNext()) {\n\t\t\tT next = i.next();\n\t\t\tif (comp.compare(next, minCandidate) < 0) {\n\t\t\t\tminCandidate = next;\n\t\t\t} else if (comp.compare(next, maxCandidate) > 0) {\n\t\t\t\tmaxCandidate = next;\n\t\t\t}\n\t\t}\n\n\t\treturn Pair.of(minCandidate, maxCandidate);\n\t}\n\n\t/**\n\t * 返回Iterable中最大的N个对象, back by guava.\n\t */\n\tpublic static > List topN(Iterable coll, int n) {\n\t\treturn Ordering.natural().greatestOf(coll, n);\n\t}\n\n\t/**\n\t * 返回Iterable中最大的N个对象, back by guava.\n\t */\n\tpublic static List topN(Iterable coll, int n, Comparator comp) {\n\t\treturn Ordering.from(comp).greatestOf(coll, n);\n\t}\n\n\t/**\n\t * 返回Iterable中最小的N个对象, back by guava.\n\t */\n\tpublic static > List bottomN(Iterable coll, int n) {\n\t\treturn Ordering.natural().leastOf(coll, n);\n\t}\n\n\t/**\n\t * 返回Iterable中最小的N个对象, back by guava.\n\t */\n\tpublic static List bottomN(Iterable coll, int n, Comparator comp) {\n\t\treturn Ordering.from(comp).leastOf(coll, n);\n\t}\n\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/collection/ListUtil.java",
"content": "package com.vip.vjtools.vjkit.collection;\n\nimport java.util.ArrayList;\nimport java.util.Collections;\nimport java.util.Comparator;\nimport java.util.HashSet;\nimport java.util.Iterator;\nimport java.util.LinkedList;\nimport java.util.List;\nimport java.util.Random;\nimport java.util.Set;\nimport java.util.concurrent.CopyOnWriteArrayList;\n\nimport com.google.common.collect.Lists;\n\n/**\n * 关于List的工具集合.\n * \n * 1. 常用函数(如是否为空，sort/binarySearch/shuffle/reverse(via JDK Collection)\n * \n * 2. 各种构造函数(from guava and JDK Collection)\n * \n * 3. 各种扩展List类型的创建函数\n * \n * 5. 集合运算：交集，并集, 差集, 补集，from Commons Collection，但对其不合理的地方做了修正\n */\n@SuppressWarnings(\"unchecked\")\npublic class ListUtil {\n\n\t/**\n\t * 判断是否为空.\n\t */\n\tpublic static boolean isEmpty(List list) {\n\t\treturn (list == null) || list.isEmpty();\n\t}\n\n\t/**\n\t * 判断是否不为空.\n\t */\n\tpublic static boolean isNotEmpty(List list) {\n\t\treturn (list != null) && !(list.isEmpty());\n\t}\n\n\t/**\n\t * 获取第一个元素, 如果List为空返回 null.\n\t */\n\tpublic static T getFirst(List list) {\n\t\tif (isEmpty(list)) {\n\t\t\treturn null;\n\t\t}\n\t\treturn list.get(0);\n\t}\n\n\t/**\n\t * 获取最后一个元素，如果List为空返回null.\n\t */\n\tpublic static T getLast(List list) {\n\t\tif (isEmpty(list)) {\n\t\t\treturn null;\n\t\t}\n\n\t\treturn list.get(list.size() - 1);\n\t}\n\n\t///////////////// from Guava的构造函数///////////////////\n\t/**\n\t * 根据等号左边的类型，构造类型正确的ArrayList.\n\t *\n\t * @deprecated JDK7开始已经简化 \n\t */\n\t@Deprecated\n\tpublic static ArrayList newArrayList() {\n\t\treturn new ArrayList();\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的ArrayList, 并初始化元素.\n\t * \n\t * @see com.google.common.collect.Lists#newArrayList(Object...)\n\t */\n\tpublic static ArrayList newArrayList(T... elements) {\n\t\treturn Lists.newArrayList(elements);\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的ArrayList, 并初始化元素.\n\t * \n\t * @see com.google.common.collect.Lists#newArrayList(Iterable)\n\t */\n\tpublic static ArrayList newArrayList(Iterable elements) {\n\t\treturn Lists.newArrayList(elements);\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的ArrayList, 并初始化数组大小.\n\t * \n\t * @see com.google.common.collect.Lists#newArrayListWithCapacity(int)\n\t */\n\tpublic static ArrayList newArrayListWithCapacity(int initSize) {\n\t\treturn new ArrayList(initSize);\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的LinkedList.\n\t * \n\t * @deprecated JDK7开始已经简化 \n\t */\n\t@Deprecated\n\tpublic static LinkedList newLinkedList() {\n\t\treturn new LinkedList();\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的LinkedList.\n\t * \n\t * @see com.google.common.collect.Lists#newLinkedList()\n\t */\n\tpublic static LinkedList newLinkedList(Iterable elements) {\n\t\treturn Lists.newLinkedList(elements);\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的CopyOnWriteArrayList.\n\t * \n\t * @deprecated JDK7开始已经简化 \n\t */\n\t@Deprecated\n\tpublic static CopyOnWriteArrayList newCopyOnWriteArrayList() {\n\t\treturn new CopyOnWriteArrayList();\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型转换的CopyOnWriteArrayList, 并初始化元素.\n\t */\n\tpublic static CopyOnWriteArrayList newCopyOnWriteArrayList(T... elements) {\n\t\treturn new CopyOnWriteArrayList(elements);\n\t}\n\n\t///////////////// from JDK Collections的常用构造函数 ///////////////////\n\n\t/**\n\t * 返回一个空的结构特殊的List，节约空间.\n\t * \n\t * 注意返回的List不可写, 写入会抛出UnsupportedOperationException.\n\t * \n\t * @see java.util.Collections#emptyList()\n\t */\n\tpublic static final List emptyList() {\n\t\treturn Collections.emptyList();\n\t}\n\n\t/**\n\t * 如果list为null，转化为一个安全的空List.\n\t * \n\t * 注意返回的List不可写, 写入会抛出UnsupportedOperationException.\n\t * \n\t * @see java.util.Collections#emptyList()\n\t */\n\tpublic static List emptyListIfNull(final List list) {\n\t\treturn list == null ? (List) Collections.EMPTY_LIST : list;\n\t}\n\n\t/**\n\t * 返回只含一个元素但结构特殊的List，节约空间.\n\t * \n\t * 注意返回的List不可写, 写入会抛出UnsupportedOperationException.\n\t * \n\t * @see java.util.Collections#singletonList(Object)\n\t */\n\tpublic static List singletonList(T o) {\n\t\treturn Collections.singletonList(o);\n\t}\n\n\t/**\n\t * 返回包装后不可修改的List.\n\t * \n\t * 如果尝试写入会抛出UnsupportedOperationException.\n\t * \n\t * @see java.util.Collections#unmodifiableList(List)\n\t */\n\tpublic static List unmodifiableList(List list) {\n\t\treturn Collections.unmodifiableList(list);\n\t}\n\n\t/**\n\t * 返回包装后同步的List，所有方法都会被synchronized原语同步.\n\t * \n\t * 用于CopyOnWriteArrayList与 ArrayDequeue均不符合的场景\n\t */\n\tpublic static List synchronizedList(List list) {\n\t\treturn Collections.synchronizedList(list);\n\t}\n\n\t///////////////// from JDK Collections的常用函数 ///////////////////\n\n\t/**\n\t * 升序排序, 采用JDK认为最优的排序算法, 使用元素自身的compareTo()方法\n\t * \n\t * @see java.util.Collections#sort(List)\n\t */\n\tpublic static > void sort(List list) {\n\t\tCollections.sort(list);\n\t}\n\n\t/**\n\t * 倒序排序, 采用JDK认为最优的排序算法,使用元素自身的compareTo()方法\n\t * \n\t * @see java.util.Collections#sort(List)\n\t */\n\tpublic static > void sortReverse(List list) {\n\t\tCollections.sort(list, Collections.reverseOrder());\n\t}\n\n\t/**\n\t * 升序排序, 采用JDK认为最优的排序算法, 使用Comparator.\n\t * \n\t * @see java.util.Collections#sort(List, Comparator)\n\t */\n\tpublic static void sort(List list, Comparator c) {\n\t\tCollections.sort(list, c);\n\t}\n\n\t/**\n\t * 倒序排序, 采用JDK认为最优的排序算法, 使用Comparator\n\t * \n\t * @see java.util.Collections#sort(List, Comparator)\n\t */\n\tpublic static void sortReverse(List list, Comparator c) {\n\t\tCollections.sort(list, Collections.reverseOrder(c));\n\t}\n\n\t/**\n\t * 二分法快速查找对象, 使用Comparable对象自身的比较.\n\t * \n\t * list必须已按升序排序.\n\t * \n\t * 如果不存在，返回一个负数，代表如果要插入这个对象，应该插入的位置\n\t * \n\t * @see java.util.Collections#binarySearch(List, Object)\n\t */\n\tpublic static int binarySearch(List> sortedList, T key) {\n\t\treturn Collections.binarySearch(sortedList, key);\n\t}\n\n\t/**\n\t * 二分法快速查找对象，使用Comparator.\n\t * \n\t * list必须已按升序排序.\n\t * \n\t * 如果不存在，返回一个负数，代表如果要插入这个对象，应该插入的位置\n\t * \n\t * @see java.util.Collections#binarySearch(List, Object, Comparator)\n\t */\n\tpublic static int binarySearch(List sortedList, T key, Comparator c) {\n\t\treturn Collections.binarySearch(sortedList, key, c);\n\t}\n\n\t/**\n\t * 随机乱序，使用默认的Random.\n\t * \n\t * @see java.util.Collections#shuffle(List)\n\t */\n\tpublic static void shuffle(List list) {\n\t\tCollections.shuffle(list);\n\t}\n\n\t/**\n\t * 随机乱序，使用传入的Random.\n\t * \n\t * @see java.util.Collections#shuffle(List, Random)\n\t */\n\tpublic static void shuffle(List list, Random rnd) {\n\t\tCollections.shuffle(list, rnd);\n\t}\n\n\t/**\n\t * 返回一个倒转顺序访问的List，仅仅是一个倒序的View，不会实际多生成一个List\n\t * \n\t * @see com.google.common.collect.Lists#reverse(List)\n\t */\n\tpublic static List reverse(final List list) {\n\t\treturn Lists.reverse(list);\n\t}\n\t///////////////// from guava的函数 ///////////////////\n\n\t/**\n\t * List分页函数\n\t */\n\tpublic static List> partition(List list, int size) {\n\t\treturn Lists.partition(list, size);\n\t}\n\n\t///////////////// 其他处理函数 ///////////////\n\n\t/**\n\t * 清理掉List中的Null对象\n\t */\n\tpublic static void notNullList(List list) {\n\t\tif (isEmpty(list)) {\n\t\t\treturn;\n\t\t}\n\n\t\tIterator ite = list.iterator();\n\t\twhile (ite.hasNext()) {\n\t\t\tT obj = ite.next();\n\t\t\t// 清理掉null的集合\n\t\t\tif (null == obj) {\n\t\t\t\tite.remove();\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic static void uniqueNotNullList(List list) {\n\t\tif (isEmpty(list)) {\n\t\t\treturn;\n\t\t}\n\t\tIterator ite = list.iterator();\n\t\tSet set = new HashSet<>((int) (list.size() / 0.75F + 1.0F));\n\n\t\twhile (ite.hasNext()) {\n\t\t\tT obj = ite.next();\n\t\t\t// 清理掉null的集合\n\t\t\tif (null == obj) {\n\t\t\t\tite.remove();\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\t// 清理掉重复的集合\n\t\t\tif (set.contains(obj)) {\n\t\t\t\tite.remove();\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tset.add(obj);\n\t\t}\n\t}\n\n\n\t///////////////// 集合运算 ///////////////////\n\n\t/**\n\t * list1,list2的并集（在list1或list2中的对象），产生新List\n\t * \n\t * 对比Apache Common Collection4 ListUtils, 优化了初始大小\n\t */\n\tpublic static List union(final List list1, final List list2) {\n\t\tfinal List result = new ArrayList(list1.size() + list2.size());\n\t\tresult.addAll(list1);\n\t\tresult.addAll(list2);\n\t\treturn result;\n\t}\n\n\t/**\n\t * list1, list2的交集（同时在list1和list2的对象），产生新List\n\t * \n\t * copy from Apache Common Collection4 ListUtils，但其做了不合理的去重，因此重新改为性能较低但不去重的版本\n\t * \n\t * 与List.retainAll()相比，考虑了的List中相同元素出现的次数, 如\"a\"在list1出现两次，而在list2中只出现一次，则交集里会保留一个\"a\".\n\t */\n\tpublic static List intersection(final List list1, final List list2) {\n\t\tList smaller = list1;\n\t\tList larger = list2;\n\t\tif (list1.size() > list2.size()) {\n\t\t\tsmaller = list2;\n\t\t\tlarger = list1;\n\t\t}\n\n\t\t// 克隆一个可修改的副本\n\t\tList newSmaller = new ArrayList(smaller);\n\t\tList result = new ArrayList(smaller.size());\n\t\tfor (final T e : larger) {\n\t\t\tif (newSmaller.contains(e)) {\n\t\t\t\tresult.add(e);\n\t\t\t\tnewSmaller.remove(e);\n\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * list1, list2的差集（在list1，不在list2中的对象），产生新List.\n\t * \n\t * 与List.removeAll()相比，会计算元素出现的次数，如\"a\"在list1出现两次，而在list2中只出现一次，则差集里会保留一个\"a\".\n\t */\n\tpublic static List difference(final List list1, final List list2) {\n\t\tfinal List result = new ArrayList(list1);\n\t\tfinal Iterator iterator = list2.iterator();\n\n\t\twhile (iterator.hasNext()) {\n\t\t\tresult.remove(iterator.next());\n\t\t}\n\n\t\treturn result;\n\t}\n\n\t/**\n\t * list1, list2的补集（在list1或list2中，但不在交集中的对象，又叫反交集）产生新List.\n\t * \n\t * copy from Apache Common Collection4 ListUtils，但其并集－交集时，初始大小没有对交集*2，所以做了修改\n\t */\n\tpublic static List disjoint(final List list1, final List list2) {\n\t\tList intersection = intersection(list1, list2);\n\t\tList towIntersection = union(intersection, intersection);\n\t\treturn difference(union(list1, list2), towIntersection);\n\t}\n}\n"
},
{
"path": "vjkit/src/main/java/com/vip/vjtools/vjkit/collection/MapUtil.java",
"content": "package com.vip.vjtools.vjkit.collection;\n\nimport java.util.Arrays;\nimport java.util.Collections;\nimport java.util.Comparator;\nimport java.util.EnumMap;\nimport java.util.HashMap;\nimport java.util.Iterator;\nimport java.util.LinkedHashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.Map.Entry;\nimport java.util.Set;\nimport java.util.SortedMap;\nimport java.util.TreeMap;\nimport java.util.concurrent.ConcurrentHashMap;\nimport java.util.concurrent.ConcurrentMap;\nimport java.util.concurrent.ConcurrentSkipListMap;\n\nimport org.apache.commons.lang3.Validate;\n\nimport com.google.common.base.Preconditions;\nimport com.google.common.collect.MapDifference;\nimport com.google.common.collect.Maps;\nimport com.google.common.collect.Ordering;\nimport com.vip.vjtools.vjkit.base.annotation.NotNull;\nimport com.vip.vjtools.vjkit.base.annotation.Nullable;\n\n/**\n * 关于Map的工具集合，\n * \n * 1. 常用函数(如是否为空, 两个map的Diff对比，针对value值的排序)\n * \n * 2. 对于并发Map，增加putIfAbsent(返回最终值版), createIfAbsent这两个重要函数(from Common Lang)\n * \n * 3. 便捷的构造函数(via guava,Java Collections，并增加了用数组，List等方式初始化Map的函数)\n * \n * 4. JDK Collections的empty,singleton\n */\n@SuppressWarnings(\"unchecked\")\npublic class MapUtil {\n\n\tpublic static final float DEFAULT_LOAD_FACTOR = 0.75f;\n\n\t/**\n\t * 判断是否为空.\n\t */\n\tpublic static boolean isEmpty(final Map map) {\n\t\treturn (map == null) || map.isEmpty();\n\t}\n\n\t/**\n\t * 判断是否为空.\n\t */\n\tpublic static boolean isNotEmpty(final Map map) {\n\t\treturn (map != null) && !map.isEmpty();\n\t}\n\n\t/**\n\t * ConcurrentMap的putIfAbsent()返回之前的Value，此函数封装返回最终存储在Map中的Value\n\t * \n\t * @see org.apache.commons.lang3.concurrent.ConcurrentUtils#putIfAbsent(ConcurrentMap, Object, Object)\n\t */\n\tpublic static V putIfAbsentReturnLast(@NotNull final ConcurrentMap map, final K key, final V value) {\n\t\tfinal V result = map.putIfAbsent(key, value);\n\t\treturn result != null ? result : value;\n\t}\n\n\t/**\n\t * 如果Key不存在则创建，返回最后存储在Map中的Value.\n\t * \n\t * 如果创建Value对象有一定成本, 直接使用PutIfAbsent可能重复浪费，则使用此类，传入一个被回调的ValueCreator，Lazy创建对象。\n\t * \n\t * @see org.apache.commons.lang3.concurrent.ConcurrentUtils#createIfAbsent(ConcurrentMap, Object,\n\t * org.apache.commons.lang3.concurrent.ConcurrentInitializer)\n\t */\n\tpublic static V createIfAbsentReturnLast(@NotNull final ConcurrentMap map, final K key,\n\t\t\t@NotNull final ValueCreator creator) {\n\t\tfinal V value = map.get(key);\n\t\tif (value == null) {\n\t\t\treturn putIfAbsentReturnLast(map, key, creator.get());\n\t\t}\n\t\treturn value;\n\t}\n\n\t/**\n\t * Lazy创建Value值的回调类\n\t * \n\t * @see MapUtil#createIfAbsentReturnLast(ConcurrentMap, Object, ValueCreator)\n\t */\n\tpublic interface ValueCreator {\n\t\t/**\n\t\t * 创建对象\n\t\t */\n\t\tT get();\n\t}\n\n\t///////////////// from Guava的构造函数///////////////////\n\n\t/**\n\t * 根据等号左边的类型, 构造类型正确的HashMap.\n\t * \n\t * 未初始化数组大小, 默认为16个桶.\n\t * \n\t * @deprecated JDK7开始已经简化 \n\t */\n\t@Deprecated\n\tpublic static HashMap newHashMap() {\n\t\treturn new HashMap();\n\t}\n\n\t/**\n\t * 根据等号左边的类型, 构造类型正确的HashMap.\n\t * \n\t * 注意HashMap中有0.75的加载因子的影响, 需要进行运算后才能正确初始化HashMap的大小.\n\t * \n\t * 加载因子也是HashMap中减少Hash冲突的重要一环，如果读写频繁，总记录数不多的Map，可以比默认值0.75进一步降低，建议0.5\n\t * \n\t * @see com.google.common.collect.Maps#newHashMap\n\t */\n\tpublic static HashMap newHashMapWithCapacity(int expectedSize, float loadFactor) {\n\t\tint finalSize = (int) (expectedSize / loadFactor + 1.0F);\n\t\treturn new HashMap(finalSize, loadFactor);\n\t}\n\n\t/**\n\t * 根据等号左边的类型, 构造类型正确的HashMap.\n\t * \n\t * 同时初始化第一个元素\n\t */\n\tpublic static HashMap newHashMap(final K key, final V value) {\n\t\tHashMap map = new HashMap();\n\t\tmap.put(key, value);\n\t\treturn map;\n\t}\n\n\t/**\n\t * 根据等号左边的类型, 构造类型正确的HashMap.\n\t * \n\t * 同时初始化元素.\n\t */\n\tpublic static HashMap newHashMap(@NotNull final K[] keys, @NotNull final V[] values) {\n\t\tValidate.isTrue(keys.length == values.length, \"keys.length is %d but values.length is %d\", keys.length,\n\t\t\t\tvalues.length);\n\n\t\tHashMap map = new HashMap(keys.length * 2);\n\n\t\tfor (int i = 0; i < keys.length; i++) {\n\t\t\tmap.put(keys[i], values[i]);\n\t\t}\n\n\t\treturn map;\n\t}\n\n\t/**\n\t * 根据等号左边的类型, 构造类型正确的HashMap.\n\t * \n\t * 同时初始化元素.\n\t */\n\tpublic static HashMap newHashMap(@NotNull final List keys, @NotNull final List values) {\n\t\tValidate.isTrue(keys.size() == values.size(), \"keys.length is %s but values.length is %s\", keys.size(),\n\t\t\t\tvalues.size());\n\n\t\tHashMap map = new HashMap(keys.size() * 2);\n\t\tIterator keyIt = keys.iterator();\n\t\tIterator valueIt = values.iterator();\n\n\t\twhile (keyIt.hasNext()) {\n\t\t\tmap.put(keyIt.next(), valueIt.next());\n\t\t}\n\n\t\treturn map;\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的TreeMap.\n\t * \n\t * @see com.google.common.collect.Maps#newTreeMap()\n\t */\n\t@SuppressWarnings(\"rawtypes\")\n\tpublic static TreeMap newSortedMap() {\n\t\treturn new TreeMap();\n\t}\n\n\t/**\n\t * 根据等号左边的类型，构造类型正确的TreeMap.\n\t * \n\t * @see com.google.common.collect.Maps#newTreeMap(Comparator)\n\t */\n\tpublic static TreeMap newSortedMap(@Nullable Comparator comparator) {\n\t\treturn Maps.newTreeMap(comparator);\n\t}\n\n\t/**\n\t * 相比HashMap，当key是枚举类时, 性能与空间占用俱佳.\n\t */\n\tpublic static