You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by zh...@apache.org on 2020/07/19 16:52:11 UTC
[shardingsphere-elasticjob] branch master updated: Add spring boot
starter usage document (#1177)
This is an automated email from the ASF dual-hosted git repository.
zhangliang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere-elasticjob.git
The following commit(s) were added to refs/heads/master by this push:
new 5187d01 Add spring boot starter usage document (#1177)
5187d01 is described below
commit 5187d01a4231967d70d4032e61b09f5d9ec73e2b
Author: 吴伟杰 <ro...@me.com>
AuthorDate: Mon Jul 20 00:52:02 2020 +0800
Add spring boot starter usage document (#1177)
---
.../usage/job-api/spring-boot-starter.cn.md | 101 +++++++++++++++++++-
.../usage/job-api/spring-boot-starter.en.md | 102 ++++++++++++++++++++-
2 files changed, 197 insertions(+), 6 deletions(-)
diff --git a/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.cn.md b/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.cn.md
index 8f2525d..f17a50c 100644
--- a/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.cn.md
+++ b/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.cn.md
@@ -5,14 +5,109 @@ chapter = true
+++
ElasticJob-Lite 提供自定义的 Spring Boot Starter，可以与 Spring Boot 配合使用。
-开发者能够便捷的在作业中通过依赖注入使用 Spring 容器管理的数据源等对象，并使用占位符从属性文件中取值。
+基于 ElasticJob Spring Boot Starter 使用 ElasticJob ，用户无需手动创建 CoordinatorRegistryCenter、JobBootstrap 等实例，
+只需实现核心作业逻辑并辅以少量配置，即可利用轻量、无中心化的 ElasticJob 解决分布式调度问题。
## 作业配置
-```yaml
+### 实现作业逻辑
+
+作业逻辑实现与 ElasticJob 的其他使用方式并没有较大的区别，只需将当前作业注册为 Spring 容器中的 bean。
+
+**线程安全问题**
+Bean 默认是单例的，如果该作业实现会在同一个进程内被创建出多个 `JobBootstrap` 的实例，
+可以考虑设置 Scope 为 `prototype`。
+
+```java
+@Component
+public class SpringBootDataflowJob implements DataflowJob<Foo> {
+
+ @Override
+ public List<Foo> fetchData(final ShardingContext shardingContext) {
+ switch (context.getShardingItem()) {
+ case 0:
+ List<Foo> data = // 获取“分片0”需要处理的数据
+ return data;
+ case 1:
+ List<Foo> data = // 获取“分片1”需要处理的数据
+ return data;
+ case 2:
+ List<Foo> data = // 获取“分片2”需要处理的数据
+ return data;
+ // case n: ...
+ }
+
+ }
+ @Override
+ public void processData(final ShardingContext shardingContext, final List<Foo> data) {
+ // 处理数据
+ }
+}
+```
+
+### 配置协调服务与作业
+
+在配置文件中指定 ElasticJob 所使用的 Zookeeper。配置前缀为 `elasticjob.reg-center`。
+
+实现了 ElasticJob 的作业逻辑属于 classed 类型作业，需要配置在 `elasticjob.jobs.classed` 下，
+`elasticjob.jobs.classed` 是一个 Map，限定类名作为 key，value 是一个 List<JobConfigurationPOJO>，
+Starter 会根据该配置自动创建 `OneOffJobBootstrap` 或 `ScheduleJobBootstrap` 的实例并注册到 Spring 容器中。
+
+配置参考：
+```yaml
+elasticjob:
+ regCenter:
+ serverLists: localhost:6181
+ namespace: elasticjob-lite-springboot
+ jobs:
+ classed:
+ org.apache.shardingsphere.elasticjob.example.job.SpringBootDataflowJob:
+ - jobName: dataflowJob
+ cron: 0/5 * * * * ?
+ shardingTotalCount: 3
+ shardingItemParameters: 0=Beijing,1=Shanghai,2=Guangzhou
+ typed:
+ SCRIPT:
+ - jobName: scriptJob
+ cron: 0/10 * * * * ?
+ shardingTotalCount: 3
+ props:
+ script.command.line: "echo SCRIPT Job: "
```
+
## 作业启动
-直接启动 Spring Boot Starter 即可。
+### 定时调度
+
+定时调度作业在 Spring Boot 应用程序启动完成后会自动启动，无需其他额外操作。
+
+### 一次性调度
+
+一次性调度的作业的执行权在开发者手中，开发者可以在需要调用作业的位置注入 `OneOffJobBootstrap`，
+通过 `execute()` 方法执行作业。
+
+**关于@DependsOn注解**
+JobBootstrap 由 Starter 动态创建，如果依赖方的实例化时间早于 Starter 创建 JobBootstrap，将无法注入 JobBoostrap 的实例。
+
+也可以通过 ApplicationContext 获取 JobBootstrap 的 Bean。
+
+此处欢迎各位开发者提出改进方案。
+
+```java
+@RestController
+@DependsOn("org.apache.shardingsphere.elasticjob.lite.boot.ElasticJobLiteAutoConfiguration")
+public class OneOffJobController {
+
+ @Resource(name = "manualScriptJobOneOffJobBootstrap")
+ private OneOffJobBootstrap manualScriptJob;
+
+ @GetMapping("/execute")
+ public String executeOneOffJob() {
+ manualScriptJob.execute();
+ return "{\"msg\":\"OK\"}";
+ }
+}
+```
+
diff --git a/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.en.md b/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.en.md
index cc29f4c..7f3062f 100644
--- a/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.en.md
+++ b/docs/content/user-manual/elasticjob-lite/usage/job-api/spring-boot-starter.en.md
@@ -5,14 +5,110 @@ chapter = true
+++
ElasticJob-Lite provides a customized Spring Boot Starter, which can be used in conjunction with Spring Boot.
-Developers can easily use Spring container-managed data sources and other objects in their jobs through dependency injection, and use placeholders to get values from property files.
+Developers are free from configuring CoordinatorRegistryCenter, JobBootstrap by using ElasticJob Spring Boot Starter.
+What developers need to solve distributed scheduling problem are job implementations with a little configuration.
## Job configuration
-```yaml
+### Implements ElasticJob
+
+Job implementation is similar to other usage of ElasticJob. The difference is that jobs will be registered into the Spring IoC container.
+
+**Thread-Safety Issue**
+Bean is singleton by default. Consider setting Bean Scope to `prototype` if the instance of ElasticJob would be used by more than a JobBootstrap.
+
+```java
+@Component
+public class SpringBootDataflowJob implements DataflowJob<Foo> {
+
+ @Override
+ public List<Foo> fetchData(final ShardingContext shardingContext) {
+ switch (context.getShardingItem()) {
+ case 0:
+ List<Foo> data = // get data from database by sharding item 0
+ return data;
+ case 1:
+ List<Foo> data = // get data from database by sharding item 1
+ return data;
+ case 2:
+ List<Foo> data = // get data from database by sharding item 2
+ return data;
+ // case n: ...
+ }
+
+ }
+ @Override
+ public void processData(final ShardingContext shardingContext, final List<Foo> data) {
+ // process data
+ // ...
+ }
+}
+```
+
+### Configure CoordinateRegistryCenter and Jobs
+
+Configure the Zookeeper which will be used by ElasticJob via configuration files.
+
+Those jobs which have implemented ElasticJob are `classed` job.
+They should be configured under `elasticjob.jobs.classed`.
+`elasticjob.jobs.classed` is a Map which using qualified class name as keys and List<JobConfigurationPOJO> as values.
+The Starter will create instances of `OneOffJobBootstrap` or `ScheduleJobBootstrap` and register them into the Spring IoC container automatically.
+
+Configuration reference:
+```yaml
+elasticjob:
+ regCenter:
+ serverLists: localhost:6181
+ namespace: elasticjob-lite-springboot
+ jobs:
+ classed:
+ org.apache.shardingsphere.elasticjob.example.job.SpringBootDataflowJob:
+ - jobName: dataflowJob
+ cron: 0/5 * * * * ?
+ shardingTotalCount: 3
+ shardingItemParameters: 0=Beijing,1=Shanghai,2=Guangzhou
+ typed:
+ SCRIPT:
+ - jobName: scriptJob
+ cron: 0/10 * * * * ?
+ shardingTotalCount: 3
+ props:
+ script.command.line: "echo SCRIPT Job: "
```
## Job start
-Just start Spring Boot Starter directly.
\ No newline at end of file
+### Schedule Job
+
+Just start Spring Boot Starter directly. The schedule jobs will startup when the Spring Boot Application is started.
+
+### One-off Job
+
+When to execute OneOffJob is up to you.
+Developers can inject the `OneOffJobBootstrap` bean into where they plan to invoke.
+Trigger the job by invoking `execute()` method manually.
+
+**About @DependsOn Annotation**
+JobBootstraps are created by the Starter dynamically. It's unable to inject the `JobBootstrap` beans if the beans which depends on `JobBootstrap` were instantiated earlier than the instantiation of `JobBootstrap`.
+
+Developers can also retrieve `JobBootstrap` beans by ApplicationContext.
+
+Improvement is welcome.
+
+```java
+@RestController
+@DependsOn("org.apache.shardingsphere.elasticjob.lite.boot.ElasticJobLiteAutoConfiguration")
+public class OneOffJobController {
+
+ @Resource(name = "manualScriptJobOneOffJobBootstrap")
+ private OneOffJobBootstrap manualScriptJob;
+
+ @GetMapping("/execute")
+ public String executeOneOffJob() {
+ manualScriptJob.execute();
+ return "{\"msg\":\"OK\"}";
+ }
+}
+```
+