diff --git a/README-EN.md b/README-EN.md index f7187c593..52bac3580 100644 --- a/README-EN.md +++ b/README-EN.md @@ -221,18 +221,18 @@ At present, `TTL` agent has decorated below `JDK` execution components(aka. thre - decoration implementation code is in [`TtlTimerTaskTransformlet.java`](src/main/java/com/alibaba/ttl/threadpool/agent/internal/transformlet/impl/TtlTimerTaskTransformlet.java), supports since version **_`2.7.0`_**. - **_NOTE_**: Since version `2.11.2` decoration for `TimerTask` default is enable (because correctness is first concern, not the best practice like "It is not recommended to use `TimerTask`" :); before version `2.11.1` default is disable. - enabled/disable by agent argument `ttl.agent.enable.timer.task`: - - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true` - - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:false` + - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true` + - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false` - more info about `TTL` agent arguments, see [the javadoc of `TtlAgent.java`](src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java). Add start options on Java command: -- `-javaagent:path/to/transmittable-thread-local-2.x.x.jar` +- `-javaagent:path/to/transmittable-thread-local-2.x.y.jar` **NOTE**: - Because TTL agent modified the `JDK` std lib classes, make code refer from std lib class to the TTL classes, so the TTL Agent jar must be added to `boot classpath`. -- Since `v2.6.0`, TTL agent jar will auto add self to `boot classpath`. But you **should _NOT_** modify the downloaded TTL jar file name in the maven repo(eg: `transmittable-thread-local-2.x.x.jar`). +- Since `v2.6.0`, TTL agent jar will auto add self to `boot classpath`. But you **should _NOT_** modify the downloaded TTL jar file name in the maven repo(eg: `transmittable-thread-local-2.x.y.jar`). - if you modified the downloaded TTL jar file name(eg: `ttl-foo-name-changed.jar`), you must add TTL agent jar to `boot classpath` manually by java option `-Xbootclasspath/a:path/to/ttl-foo-name-changed.jar`. @@ -252,7 +252,7 @@ More info: Java command example: ```bash -java -javaagent:transmittable-thread-local-2.x.x.jar \ +java -javaagent:transmittable-thread-local-2.x.y.jar \ -cp classes \ com.alibaba.demo.ttl.agent.AgentDemo ``` diff --git a/README.md b/README.md index 628673d28..0d6ced095 100644 --- a/README.md +++ b/README.md @@ -248,8 +248,8 @@ Demo参见[`AgentDemo.kt`](src/test/java/com/alibaba/demo/ttl/agent/AgentDemo.kt - 修饰实现代码在[`TtlTimerTaskTransformlet.java`](src/main/java/com/alibaba/ttl/threadpool/agent/internal/transformlet/impl/TtlTimerTaskTransformlet.java)。从版本 **_`2.7.0`_** 开始支持。 - **_注意_**:从`2.11.2`版本开始缺省开启`TimerTask`的修饰(因为保证正确性是第一位,而不是最佳实践『不推荐使用`TimerTask`』:);`2.11.1`版本及其之前的版本没有缺省开启`TimerTask`的修饰。 - 使用`Agent`参数`ttl.agent.enable.timer.task`开启/关闭`TimerTask`的修饰: - - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true` - - `-javaagent:path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:false` + - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true` + - `-javaagent:path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false` - 更多关于`TTL Agent`参数的配置说明详见[`TtlAgent.java`的JavaDoc](src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java)。 > **关于`java.util.TimerTask`/`java.util.Timer`** @@ -265,7 +265,7 @@ Demo参见[`AgentDemo.kt`](src/test/java/com/alibaba/demo/ttl/agent/AgentDemo.kt 因为修饰了`JDK`标准库的类,标准库由`bootstrap class loader`加载;修饰后的`JDK`类引用了`TTL`的代码,所以`Java Agent`使用方式下`TTL Jar`文件需要配置到`boot class path`上。 `TTL`从`v2.6.0`开始,加载`TTL Agent`时会自动设置`TTL Jar`到`boot class path`上。 -**_注意_**:不能修改从`Maven`库下载的`TTL Jar`文件名(形如`transmittable-thread-local-2.x.x.jar`)。 +**_注意_**:不能修改从`Maven`库下载的`TTL Jar`文件名(形如`transmittable-thread-local-2.x.y.jar`)。 如果修改了,则需要自己手动通过`-Xbootclasspath JVM`参数来显式配置(就像`TTL`之前的版本的做法一样)。 自动设置`TTL Jar`到`boot class path`的实现是通过指定`TTL Java Agent Jar`文件里`manifest`文件(`META-INF/MANIFEST.MF`)的`Boot-Class-Path`属性: @@ -283,15 +283,15 @@ Demo参见[`AgentDemo.kt`](src/test/java/com/alibaba/demo/ttl/agent/AgentDemo.kt #### `Java`的启动参数配置 -在`Java`的启动参数加上:`-javaagent:path/to/transmittable-thread-local-2.x.x.jar`。 +在`Java`的启动参数加上:`-javaagent:path/to/transmittable-thread-local-2.x.y.jar`。 -如果修改了下载的`TTL`的`Jar`的文件名(`transmittable-thread-local-2.x.x.jar`),则需要自己手动通过`-Xbootclasspath JVM`参数来显式配置: +如果修改了下载的`TTL`的`Jar`的文件名(`transmittable-thread-local-2.x.y.jar`),则需要自己手动通过`-Xbootclasspath JVM`参数来显式配置: 比如修改文件名成`ttl-foo-name-changed.jar`,则还加上`Java`的启动参数:`-Xbootclasspath/a:path/to/ttl-foo-name-changed.jar` `Java`命令行示例如下: ```bash -java -javaagent:path/to/transmittable-thread-local-2.x.x.jar \ +java -javaagent:path/to/transmittable-thread-local-2.x.y.jar \ -cp classes \ com.alibaba.demo.ttl.agent.AgentDemo ``` diff --git a/docs/release-action-list.md b/docs/release-action-list.md index ac2c281f7..9fde25091 100644 --- a/docs/release-action-list.md +++ b/docs/release-action-list.md @@ -9,14 +9,14 @@ - `./scripts/gen-pom4ide.sh` 重新生成 `pom4ide` - 更新`README` - 更新badge的引用,由master分支名改成Tag名 - - `sed 's/master/v2.x.x/g' -i README*` + - `sed 's/master/v2.x.y/g' -i README*` - `javadoc` badge的JavaDoc链接到固定版本 - https://alibaba.github.io/transmittable-thread-local/apidocs/2.x.x/index.html + https://alibaba.github.io/transmittable-thread-local/apidocs/2.x.y/index.html - 示例`Maven`依赖的版本 - 更新`JavaDoc`链接到固定版本 -2. 新建并Push Tag,如`v2.x.x` - - `git tag -m 'release v2.x.x' v2.x.x` - - `git push origin v2.x.x` +2. 新建并Push Tag,如`v2.x.y` + - `git tag -m 'release v2.x.y' v2.x.y` + - `git push origin v2.x.y` 3. 等待Tag的CI通过 3. 执行`scripts/checke-japi-compliance.sh`,检查`API`兼容性 4. 发布版本到`Maven`中央库 @@ -24,7 +24,7 @@ 5. 更新`JavaDoc` 1. 生成`JavaDoc`,更新到分支`gh-pages` - `git checkout gh-pages` - - `mv target/apidocs apidocs/2.x.x` + - `mv target/apidocs apidocs/2.x.y` 2. 修改`index.html`的重定向到最新版本的`JavaDoc` 6. 编写Release Note: 7. 升级`Master`分支的开发版本号 diff --git a/src/main/java/com/alibaba/ttl/TransmittableThreadLocal.java b/src/main/java/com/alibaba/ttl/TransmittableThreadLocal.java index b817c55e9..a43a02853 100644 --- a/src/main/java/com/alibaba/ttl/TransmittableThreadLocal.java +++ b/src/main/java/com/alibaba/ttl/TransmittableThreadLocal.java @@ -13,7 +13,7 @@ import java.util.logging.Logger; /** - * {@link TransmittableThreadLocal} can transmit value from the thread of submitting task to the thread of executing task. + * {@link TransmittableThreadLocal}({@code TTL}) can transmit value from the thread of submitting task to the thread of executing task. *

* Note:
* {@link TransmittableThreadLocal} extends {@link InheritableThreadLocal}, diff --git a/src/main/java/com/alibaba/ttl/threadpool/TtlExecutors.java b/src/main/java/com/alibaba/ttl/threadpool/TtlExecutors.java index 21aa5810e..18432afd3 100644 --- a/src/main/java/com/alibaba/ttl/threadpool/TtlExecutors.java +++ b/src/main/java/com/alibaba/ttl/threadpool/TtlExecutors.java @@ -41,11 +41,11 @@ public final class TtlExecutors { * transmit the {@link TransmittableThreadLocal} from the task submit time of {@link Runnable} * to the execution time of {@link Runnable}. *

- * NOTE: sine v2.12.0 the idempotency of return wrapper Executor is changed to true, - * so the wrapper Executor can be cooperation the usage of "Decorate Runnable and Callable". + * NOTE: sine v2.12.0 the idempotency of return wrapped Executor is changed to true, + * so the wrapped Executor can be cooperated with the usage of "Decorate Runnable and Callable". *

- * about idempotency: if is idempotent, - * allowed submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapper Executor; + * About idempotency: if is idempotent, + * it's allowed to submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapped Executor; * otherwise throw {@link IllegalStateException}. * * @param executor input Executor @@ -66,11 +66,11 @@ public static Executor getTtlExecutor(@Nullable Executor executor) { * transmit the {@link TransmittableThreadLocal} from the task submit time of {@link Runnable} or {@link java.util.concurrent.Callable} * to the execution time of {@link Runnable} or {@link java.util.concurrent.Callable}. *

- * NOTE: sine v2.12.0 the idempotency of return wrapper ExecutorService is changed to true, - * so the wrapper ExecutorService can be cooperation the usage of "Decorate Runnable and Callable". + * NOTE: sine v2.12.0 the idempotency of return wrapped ExecutorService is changed to true, + * so the wrapped ExecutorService can be cooperated with the usage of "Decorate Runnable and Callable". *

- * about idempotency: if is idempotent, - * allowed submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapper ExecutorService; + * About idempotency: if is idempotent, + * it's allowed to submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapped ExecutorService; * otherwise throw {@link IllegalStateException}. * * @param executorService input ExecutorService @@ -92,11 +92,11 @@ public static ExecutorService getTtlExecutorService(@Nullable ExecutorService ex * transmit the {@link TransmittableThreadLocal} from the task submit time of {@link Runnable} or {@link java.util.concurrent.Callable} * to the execution time of {@link Runnable} or {@link java.util.concurrent.Callable}. *

- * NOTE: sine v2.12.0 the idempotency of return wrapper ScheduledExecutorService is changed to true, - * so the wrapper ScheduledExecutorService can be cooperation the usage of "Decorate Runnable and Callable". + * NOTE: sine v2.12.0 the idempotency of return wrapped ScheduledExecutorService is changed to true, + * so the wrapped ScheduledExecutorService can be cooperated with the usage of "Decorate Runnable and Callable". *

- * about idempotency:if is idempotent, - * allowed submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapper scheduledExecutorService; + * About idempotency: if is idempotent, + * it's allowed to submit the {@link com.alibaba.ttl.TtlRunnable}/{@link com.alibaba.ttl.TtlCallable} to the wrapped ScheduledExecutorService; * otherwise throw {@link IllegalStateException}. * * @param scheduledExecutorService input scheduledExecutorService @@ -113,7 +113,7 @@ public static ScheduledExecutorService getTtlScheduledExecutorService(@Nullable } /** - * check the executor is TTL wrapper executor or not. + * check the executor is a TTL executor wrapper or not. *

* if the parameter executor is TTL wrapper, return {@code true}, otherwise {@code false}. *

@@ -132,7 +132,7 @@ public static boolean isTtlWrapper(@Nullable T executor) { } /** - * Unwrap TTL wrapper executor to the original/underneath one. + * Unwrap TTL executor wrapper to the original/underneath one. *

* if the parameter executor is TTL wrapper, return the original/underneath executor; * otherwise, just return the input parameter executor. @@ -157,7 +157,7 @@ public static T unwrap(@Nullable T executor) { } /** - * Wrapper of {@link ThreadFactory}, disable inheritable. + * Wrapper of {@link ThreadFactory}, disable inheritable. * * @param threadFactory input thread factory * @see DisableInheritableThreadFactory diff --git a/src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java b/src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java index 9f4fb60f0..0967f271b 100644 --- a/src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java +++ b/src/main/java/com/alibaba/ttl/threadpool/agent/TtlAgent.java @@ -43,7 +43,7 @@ * More info about "disable inheritable" see {@link com.alibaba.ttl.TransmittableThreadLocal}. *

* Configuration example:
- * {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.disable.inheritable.for.thread.pool:true} + * {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.disable.inheritable.for.thread.pool:true} * *

The log configuration

* The log of TTL Java Agent is config by key {@code ttl.agent.logger}. Since version {@code 2.6.0}. @@ -58,8 +58,8 @@ *

* configuration example: *

    - *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar}
  • - *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.logger:STDOUT}
  • + *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar}
  • + *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.logger:STDOUT}
  • *
* *

Enable/disable TimerTask class decoration

@@ -72,16 +72,16 @@ *

* Configuration example: *

    - *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:false}
  • - *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.enable.timer.task:true}
  • + *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:false}
  • + *
  • {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.enable.timer.task:true}
  • *
* *

Multi key configuration example

- * {@code -javaagent:/path/to/transmittable-thread-local-2.x.x.jar=ttl.agent.logger:STDOUT,ttl.agent.disable.inheritable.for.thread.pool:true} + * {@code -javaagent:/path/to/transmittable-thread-local-2.x.y.jar=ttl.agent.logger:STDOUT,ttl.agent.disable.inheritable.for.thread.pool:true} * *

About boot classpath for TTL agent

* NOTE: Since {@code v2.6.0}, TTL agent jar will auto add self to {@code boot classpath}. - * But you should NOT modify the downloaded TTL jar file name in the maven repo(eg: {@code transmittable-thread-local-2.x.x.jar}).
+ * But you should NOT modify the downloaded TTL jar file name in the maven repo(eg: {@code transmittable-thread-local-2.x.y.jar}).
* if you modified the downloaded TTL agent jar file name(eg: {@code ttl-foo-name-changed.jar}), * you must add TTL agent jar to {@code boot classpath} manually * by java option {@code -Xbootclasspath/a:path/to/ttl-foo-name-changed.jar}.