Skip to content

Commit b97c26c

Browse files
KFCFansKFCFans
committed
docs: translate for OhMyClient
1 parent 078db73 commit b97c26c

File tree

4 files changed

+89
-106
lines changed

4 files changed

+89
-106
lines changed

‎powerjob-client/src/main/java/com/github/kfcfans/powerjob/client/OhMyClient.java

+86-101
Original file line numberDiff line numberDiff line change
@@ -41,18 +41,20 @@ public class OhMyClient {
4141

4242
/**
4343
* Init OhMyClient with domain, appName and password.
44-
* @param domain 比如 www.powerjob-server.com（内网域名，自行完成 DNS & Proxy）
44+
* @param domain like powerjob-server.apple-inc.com (Intranet Domain)
4545
* @param appName name of the application
46+
* @param password password of the application
4647
*/
4748
public OhMyClient(String domain, String appName, String password) {
4849
this(Lists.newArrayList(domain), appName, password);
4950
}
5051

5152

5253
/**
53-
* nit OhMyClient with server address, appName and password.
54-
* @param addressList IP:Port address list
54+
* Init OhMyClient with server address, appName and password.
55+
* @param addressList IP:Port address list, like 192.168.1.1:7700
5556
* @param appName name of the application
57+
* @param password password of the application
5658
*/
5759
public OhMyClient(List<String> addressList, String appName, String password) {
5860

@@ -79,7 +81,7 @@ public OhMyClient(List<String> addressList, String appName, String password) {
7981
}
8082

8183
if (StringUtils.isEmpty(currentAddress)) {
82-
throw new PowerJobException("no server available");
84+
throw new PowerJobException("no server available for OhMyClient");
8385
}
8486
log.info("[OhMyClient] {}'s OhMyClient bootstrap successfully, using server: {}", appName, currentAddress);
8587
}
@@ -101,12 +103,12 @@ private static String getUrl(String path, String address) {
101103
/* ************* Job 区 ************* */
102104

103105
/**
104-
* 保存任务（包括创建与修改）
105-
* @param request 任务详细参数
106-
* @return 创建的任务ID
107-
* @throws PowerJobException 异常
106+
* Save one Job
107+
* When an ID exists in SaveJobInfoRequest, it is an update operation. Otherwise, it is a crate operation.
108+
* @param request Job meta info
109+
* @return jobId
108110
*/
109-
public ResultDTO<Long> saveJob(SaveJobInfoRequest request) throws PowerJobException {
111+
public ResultDTO<Long> saveJob(SaveJobInfoRequest request) {
110112

111113
request.setAppId(appId);
112114
MediaType jsonType = MediaType.parse("application/json; charset=utf-8");
@@ -116,12 +118,11 @@ public ResultDTO<Long> saveJob(SaveJobInfoRequest request) throws PowerJobExcept
116118
}
117119

118120
/**
119-
* 根据 jobId 查询任务信息
120-
* @param jobId 任务ID
121-
* @return 任务详细信息
122-
* @throws PowerJobException 异常
121+
* Query JobInfo by jobId
122+
* @param jobId jobId
123+
* @return Job meta info
123124
*/
124-
public ResultDTO<JobInfoDTO> fetchJob(Long jobId) throws PowerJobException {
125+
public ResultDTO<JobInfoDTO> fetchJob(Long jobId) {
125126
RequestBody body = new FormBody.Builder()
126127
.add("jobId", jobId.toString())
127128
.add("appId", appId.toString())
@@ -131,12 +132,11 @@ public ResultDTO<JobInfoDTO> fetchJob(Long jobId) throws PowerJobException {
131132
}
132133

133134
/**
134-
* 禁用某个任务
135-
* @param jobId 任务ID
136-
* @return 标准返回对象
137-
* @throws PowerJobException 异常
135+
* Disable one Job by jobId
136+
* @param jobId jobId
137+
* @return Standard return object
138138
*/
139-
public ResultDTO<Void> disableJob(Long jobId) throws PowerJobException {
139+
public ResultDTO<Void> disableJob(Long jobId) {
140140
RequestBody body = new FormBody.Builder()
141141
.add("jobId", jobId.toString())
142142
.add("appId", appId.toString())
@@ -146,12 +146,11 @@ public ResultDTO<Void> disableJob(Long jobId) throws PowerJobException {
146146
}
147147

148148
/**
149-
* 启用某个任务
150-
* @param jobId 任务ID
151-
* @return 标准返回对象
152-
* @throws PowerJobException 异常
149+
* Enable one job by jobId
150+
* @param jobId jobId
151+
* @return Standard return object
153152
*/
154-
public ResultDTO<Void> enableJob(Long jobId) throws PowerJobException {
153+
public ResultDTO<Void> enableJob(Long jobId) {
155154
RequestBody body = new FormBody.Builder()
156155
.add("jobId", jobId.toString())
157156
.add("appId", appId.toString())
@@ -161,12 +160,11 @@ public ResultDTO<Void> enableJob(Long jobId) throws PowerJobException {
161160
}
162161

163162
/**
164-
* 删除某个任务
165-
* @param jobId 任务ID
166-
* @return 标准返回对象
167-
* @throws PowerJobException 异常
163+
* Delete one job by jobId
164+
* @param jobId jobId
165+
* @return Standard return object
168166
*/
169-
public ResultDTO<Void> deleteJob(Long jobId) throws PowerJobException {
167+
public ResultDTO<Void> deleteJob(Long jobId) {
170168
RequestBody body = new FormBody.Builder()
171169
.add("jobId", jobId.toString())
172170
.add("appId", appId.toString())
@@ -176,14 +174,13 @@ public ResultDTO<Void> deleteJob(Long jobId) throws PowerJobException {
176174
}
177175

178176
/**
179-
* 运行某个任务
180-
* @param jobId 任务ID
181-
* @param instanceParams 任务实例的参数
182-
* @param delayMS 延迟时间，单位毫秒
183-
* @return 任务实例ID（instanceId）
184-
* @throws PowerJobException 异常
177+
* Run a job once
178+
* @param jobId ID of the job to be run
179+
* @param instanceParams Runtime parameters of the job (TaskContext#instanceParams)
180+
* @param delayMS Delay time（Milliseconds）
181+
* @return instanceId
185182
*/
186-
public ResultDTO<Long> runJob(Long jobId, String instanceParams, long delayMS) throws PowerJobException {
183+
public ResultDTO<Long> runJob(Long jobId, String instanceParams, long delayMS) {
187184
FormBody.Builder builder = new FormBody.Builder()
188185
.add("jobId", jobId.toString())
189186
.add("appId", appId.toString())
@@ -201,12 +198,11 @@ public ResultDTO<Long> runJob(Long jobId) throws PowerJobException {
201198

202199
/* ************* Instance API list ************* */
203200
/**
204-
* 停止应用实例
205-
* @param instanceId 应用实例ID
206-
* @return true 停止成功，false 停止失败
207-
* @throws PowerJobException 异常
201+
* Stop one job instance
202+
* @param instanceId instanceId
203+
* @return Standard return object
208204
*/
209-
public ResultDTO<Void> stopInstance(Long instanceId) throws PowerJobException {
205+
public ResultDTO<Void> stopInstance(Long instanceId) {
210206
RequestBody body = new FormBody.Builder()
211207
.add("instanceId", instanceId.toString())
212208
.add("appId", appId.toString())
@@ -216,13 +212,12 @@ public ResultDTO<Void> stopInstance(Long instanceId) throws PowerJobException {
216212
}
217213

218214
/**
219-
* 取消任务实例
220-
* 接口使用条件：调用接口时间与待取消任务的预计执行时间有一定时间间隔，否则不保证可靠性！
221-
* @param instanceId 任务实例ID
222-
* @return true 代表取消成功，false 取消失败
223-
* @throws PowerJobException 异常
215+
* Cancel a job instance that is not yet running
216+
* Notice：There is a time interval between the call interface time and the expected execution time of the job instance to be cancelled, otherwise reliability is not guaranteed
217+
* @param instanceId instanceId
218+
* @return Standard return object
224219
*/
225-
public ResultDTO<Void> cancelInstance(Long instanceId) throws PowerJobException {
220+
public ResultDTO<Void> cancelInstance(Long instanceId) {
226221
RequestBody body = new FormBody.Builder()
227222
.add("instanceId", instanceId.toString())
228223
.add("appId", appId.toString())
@@ -232,13 +227,12 @@ public ResultDTO<Void> cancelInstance(Long instanceId) throws PowerJobException
232227
}
233228

234229
/**
235-
* 重试任务实例
236-
* 只有完成状态（成功、失败、手动停止、被取消）的任务才能被重试，且暂不支持工作流内任务实例的重试
237-
* @param instanceId 任务实例ID
238-
* @return true 代表取消成功，false 取消失败
239-
* @throws PowerJobException 异常
230+
* Retry failed job instance
231+
* Notice: Only job instance with completion status (success, failure, manually stopped, cancelled) can be retried, and retries of job instances within workflows are not supported yet.
232+
* @param instanceId instanceId
233+
* @return Standard return object
240234
*/
241-
public ResultDTO<Void> retryInstance(Long instanceId) throws PowerJobException {
235+
public ResultDTO<Void> retryInstance(Long instanceId) {
242236
RequestBody body = new FormBody.Builder()
243237
.add("instanceId", instanceId.toString())
244238
.add("appId", appId.toString())
@@ -248,12 +242,11 @@ public ResultDTO<Void> retryInstance(Long instanceId) throws PowerJobException {
248242
}
249243

250244
/**
251-
* 查询任务实例状态
252-
* @param instanceId 应用实例ID
253-
* @return {@link InstanceStatus} 的枚举值
254-
* @throws PowerJobException 异常
245+
* Query status about a job instance
246+
* @param instanceId instanceId
247+
* @return {@link InstanceStatus}
255248
*/
256-
public ResultDTO<Integer> fetchInstanceStatus(Long instanceId) throws PowerJobException {
249+
public ResultDTO<Integer> fetchInstanceStatus(Long instanceId) {
257250
RequestBody body = new FormBody.Builder()
258251
.add("instanceId", instanceId.toString())
259252
.build();
@@ -262,12 +255,11 @@ public ResultDTO<Integer> fetchInstanceStatus(Long instanceId) throws PowerJobEx
262255
}
263256

264257
/**
265-
* 查询任务实例的信息
266-
* @param instanceId 任务实例ID
267-
* @return 任务实例信息
268-
* @throws PowerJobException 潜在的异常
258+
* Query detail about a job instance
259+
* @param instanceId instanceId
260+
* @return instance detail
269261
*/
270-
public ResultDTO<InstanceInfoDTO> fetchInstanceInfo(Long instanceId) throws PowerJobException {
262+
public ResultDTO<InstanceInfoDTO> fetchInstanceInfo(Long instanceId) {
271263
RequestBody body = new FormBody.Builder()
272264
.add("instanceId", instanceId.toString())
273265
.build();
@@ -277,12 +269,12 @@ public ResultDTO<InstanceInfoDTO> fetchInstanceInfo(Long instanceId) throws Powe
277269

278270
/* ************* Workflow API list ************* */
279271
/**
280-
* 保存工作流（包括创建和修改）
281-
* @param request 创建/修改 Workflow 请求
282-
* @return 工作流ID
283-
* @throws PowerJobException 异常
272+
* Save one workflow
273+
* When an ID exists in SaveWorkflowRequest, it is an update operation. Otherwise, it is a crate operation.
274+
* @param request Workflow meta info
275+
* @return workflowId
284276
*/
285-
public ResultDTO<Long> saveWorkflow(SaveWorkflowRequest request) throws PowerJobException {
277+
public ResultDTO<Long> saveWorkflow(SaveWorkflowRequest request) {
286278
request.setAppId(appId);
287279
MediaType jsonType = MediaType.parse(OmsConstant.JSON_MEDIA_TYPE);
288280
// 中坑记录：用 FastJSON 序列化会导致 Server 接收时 pEWorkflowDAG 为 null，无语.jpg
@@ -292,12 +284,11 @@ public ResultDTO<Long> saveWorkflow(SaveWorkflowRequest request) throws PowerJob
292284
}
293285

294286
/**
295-
* 根据 workflowId 查询工作流信息
287+
* Query Workflow by workflowId
296288
* @param workflowId workflowId
297-
* @return 工作流信息
298-
* @throws PowerJobException 异常
289+
* @return Workflow meta info
299290
*/
300-
public ResultDTO<WorkflowInfoDTO> fetchWorkflow(Long workflowId) throws PowerJobException {
291+
public ResultDTO<WorkflowInfoDTO> fetchWorkflow(Long workflowId) {
301292
RequestBody body = new FormBody.Builder()
302293
.add("workflowId", workflowId.toString())
303294
.add("appId", appId.toString())
@@ -307,12 +298,11 @@ public ResultDTO<WorkflowInfoDTO> fetchWorkflow(Long workflowId) throws PowerJob
307298
}
308299

309300
/**
310-
* 禁用某个工作流
311-
* @param workflowId 工作流ID
312-
* @return 标准返回对象
313-
* @throws PowerJobException 异常
301+
* Disable Workflow by workflowId
302+
* @param workflowId workflowId
303+
* @return Standard return object
314304
*/
315-
public ResultDTO<Void> disableWorkflow(Long workflowId) throws PowerJobException {
305+
public ResultDTO<Void> disableWorkflow(Long workflowId) {
316306
RequestBody body = new FormBody.Builder()
317307
.add("workflowId", workflowId.toString())
318308
.add("appId", appId.toString())
@@ -322,12 +312,11 @@ public ResultDTO<Void> disableWorkflow(Long workflowId) throws PowerJobException
322312
}
323313

324314
/**
325-
* 启用某个工作流
315+
* Enable Workflow by workflowId
326316
* @param workflowId workflowId
327-
* @return 标准返回对象
328-
* @throws PowerJobException 异常
317+
* @return Standard return object
329318
*/
330-
public ResultDTO<Void> enableWorkflow(Long workflowId) throws PowerJobException {
319+
public ResultDTO<Void> enableWorkflow(Long workflowId) {
331320
RequestBody body = new FormBody.Builder()
332321
.add("workflowId", workflowId.toString())
333322
.add("appId", appId.toString())
@@ -337,12 +326,11 @@ public ResultDTO<Void> enableWorkflow(Long workflowId) throws PowerJobException
337326
}
338327

339328
/**
340-
* 删除某个工作流
329+
* Delete Workflow by workflowId
341330
* @param workflowId workflowId
342-
* @return 标准返回对象
343-
* @throws PowerJobException 异常
331+
* @return Standard return object
344332
*/
345-
public ResultDTO<Void> deleteWorkflow(Long workflowId) throws PowerJobException {
333+
public ResultDTO<Void> deleteWorkflow(Long workflowId) {
346334
RequestBody body = new FormBody.Builder()
347335
.add("workflowId", workflowId.toString())
348336
.add("appId", appId.toString())
@@ -352,14 +340,13 @@ public ResultDTO<Void> deleteWorkflow(Long workflowId) throws PowerJobException
352340
}
353341

354342
/**
355-
* 运行工作流
356-
* @param workflowId 工作流ID
357-
* @param initParams 启动参数
358-
* @param delayMS 延迟时间，单位毫秒 ms
359-
* @return 工作流实例ID
360-
* @throws PowerJobException 异常信息
343+
* Run a workflow once
344+
* @param workflowId workflowId
345+
* @param initParams workflow startup parameters
346+
* @param delayMS Delay time（Milliseconds）
347+
* @return workflow instanceId
361348
*/
362-
public ResultDTO<Long> runWorkflow(Long workflowId, String initParams, long delayMS) throws PowerJobException {
349+
public ResultDTO<Long> runWorkflow(Long workflowId, String initParams, long delayMS) {
363350
FormBody.Builder builder = new FormBody.Builder()
364351
.add("workflowId", workflowId.toString())
365352
.add("appId", appId.toString())
@@ -376,10 +363,9 @@ public ResultDTO<Long> runWorkflow(Long workflowId) throws PowerJobException {
376363

377364
/* ************* Workflow Instance API list ************* */
378365
/**
379-
* 停止应用实例
380-
* @param wfInstanceId 工作流实例ID
381-
* @return true 停止成功 ； false 停止失败
382-
* @throws PowerJobException 异常
366+
* Stop one workflow instance
367+
* @param wfInstanceId workflow instanceId
368+
* @return Standard return object
383369
*/
384370
public ResultDTO<Void> stopWorkflowInstance(Long wfInstanceId) throws PowerJobException {
385371
RequestBody body = new FormBody.Builder()
@@ -391,12 +377,11 @@ public ResultDTO<Void> stopWorkflowInstance(Long wfInstanceId) throws PowerJobEx
391377
}
392378

393379
/**
394-
* 查询任务实例的信息
395-
* @param wfInstanceId 任务实例ID
396-
* @return 任务实例信息
397-
* @throws PowerJobException 潜在的异常
380+
* Query detail about a workflow instance
381+
* @param wfInstanceId workflow instanceId
382+
* @return detail about a workflow
398383
*/
399-
public ResultDTO<WorkflowInstanceInfoDTO> fetchWorkflowInstanceInfo(Long wfInstanceId) throws PowerJobException {
384+
public ResultDTO<WorkflowInstanceInfoDTO> fetchWorkflowInstanceInfo(Long wfInstanceId) {
400385
RequestBody body = new FormBody.Builder()
401386
.add("wfInstanceId", wfInstanceId.toString())
402387
.add("appId", appId.toString())

‎powerjob-common/src/main/java/com/github/kfcfans/powerjob/common/InstanceStatus.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
import java.util.List;
88

99
/**
10-
* 任务运行状态
10+
* Status of the job instance
1111
*
1212
* @author tjq
1313
* @since 2020/3/17

‎powerjob-common/src/main/java/com/github/kfcfans/powerjob/common/response/InstanceInfoDTO.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
import java.util.Date;
77

88
/**
9-
* instanceInfo 对外输出对象
9+
* instanceInfo Network transmission object
1010
*
1111
* @author tjq
1212
* @since 2020/5/14

0 commit comments

Comments
 (0)