本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS Flow Framework 适用于 Java 参考 **Topics** + [AWS Flow Framework 适用于 Java 注释](annotations.md) + [AWS Flow Framework 对于 Java 异常](errorhandling.exceptions.md) + [AWS Flow Framework 适用于 Java 软件包](awsflow.packages.md) # AWS Flow Framework 适用于 Java 注释 **Topics** + [@活动](#annotations-activities) + [@活动](#annotations-activity) + [@ActivityRegistrationOptions](#annotations-activityregistration) + [@异步](#annotations-asynchronous) + [@Execute](#annotations-execute) + [@ExponentialRetry](#annotations-exponentialretry) + [@GetState](#annotations-getstate) + [@ManualActivityCompletion](#annotations-manualactivitycompletion) + [@Signal](#annotations-signal) + [@SkipRegistration](#annotations-skipregistration) + [@Wait 和 @ NoWait](#annotations-waitnowait) + [@工作流](#annotations-workflow) + [@WorkflowRegistrationOptions](#annotations-workflowregistrationoptions) ## @活动 此注释可在接口上用于声明一组活动类型。使用此注释进行注释的接口中的每个方法都表示活动类型。接口不能同时具有 `@Workflow` 和 `@Activities` 注释。 可对此注释指定以下参数： `activityNamePrefix` 指定在接口中声明的活动类型的名称前缀。如果设置为空字符串（这是默认值），则后跟“.”的接口名称将用作前缀。 `version` 指定在接口中声明的活动类型的默认版本。默认值为 `1.0`。 `dataConverter` 指定创建此活动类型的任务时用于 serializing/deserializing 数据的类型及其结果。`DataConverter`默认设置为 `NullDataConverter`，这指示应使用 `JsonDataConverter`。 ## @活动 可在使用 `@Activities` 进行注释的接口中的方法上使用此注释。 可对此注释指定以下参数： `name` 指定活动类型的名称。默认为空字符串，这指示应使用默认的前缀和活动方法名称来确定活动类型的名称（其格式为 \$1*prefix*\$1\$1*name*\$1）。请注意，在 `@Activity` 注释中指定名称时，框架不会自动在它之前加上前缀。您可以使用任意的命名方案。 `version` 指定活动类型的版本。这将覆盖在包含接口上的 `@Activities` 注释中指定的默认版本。默认值是空字符串。 ## @ActivityRegistrationOptions 指定活动类型的注册选项。可在使用 `@Activities` 进行注释的接口或其中的方法上使用此注释。如果同时在这两个地方指定，则在方法上使用的注释生效。 可对此注释指定以下参数： `defaultTasklist` 指定此活动类型要向 Amazon SWF 注册的默认任务列表。在使用 `ActivitySchedulingOptions` 参数生成的客户端上调用活动方法时，会覆盖此默认值。默认设置为 `USE_WORKER_TASK_LIST`。这是一个特殊值，指示应使用执行注册的工作线程所使用的任务列表。 `defaultTaskScheduleToStartTimeoutSeconds` 指定 defaultTaskScheduleToStartTimeout 已在 Amazon SWF 中注册的该活动类型。这是在将此活动类型的任务分配给工作线程之前，允许它等待的最长时间。有关更多详细信息，请参阅 *Amazon Simple Workflow Service API 参考*。 `defaultTaskHeartbeatTimeoutSeconds` 指定此活动类型向 Amazon SWF 注册的 `defaultTaskHeartbeatTimeout`。活动工作线程必须提供位于此持续时间内的检测信号；否则，任务将超时。默认设置为 -1，这是一个特殊值，指示应禁用此超时。有关更多详细信息，请参阅 *Amazon Simple Workflow Service API 参考*。 `defaultTaskStartToCloseTimeoutSeconds` 指定 defaultTaskStartToCloseTimeout 已在 Amazon SWF 中注册的该活动类型。此超时确定工作线程可用于处理此类型的活动任务的最长时间。有关更多详细信息，请参阅 *Amazon Simple Workflow Service API 参考*。 `defaultTaskScheduleToCloseTimeoutSeconds` 指定此活动类型向 Amazon SWF 注册的 `defaultScheduleToCloseTimeout`。此超时确定任务可保持打开状态的总持续时间。默认设置为 -1，这是一个特殊值，指示应禁用此超时。有关更多详细信息，请参阅 *Amazon Simple Workflow Service API 参考*。 ## @异步 在工作流协调逻辑中的方法上使用时，指示该方法应异步执行。对该方法的调用将立即返回，但实际执行将在传递给该方法的所有 Promise<> 参数都已准备就绪时异步进行。使用 @Asynchronous 进行注释的方法必须具有返回类型 Promise<> 或 void。 `daemon` 指示为异步方法创建的任务是否应为守护程序任务。默认情况下为 `False`。 ## @Execute 在使用 `@Workflow` 注释进行注释的接口中的方法上使用时，标识工作流的入口点。 **重要** 只有接口中的一个方法可以使用 `@Execute` 进行修饰。 可对此注释指定以下参数： `name` 指定工作流类型的名称。如果未设置，则名称默认为 \$1*prefix*\$1\$1*name*\$1，其中 \$1*prefix*\$1 是后跟“.”的工作流程接口，\$1*name*\$1 是工作流程中 `@Execute` 装饰的方法。 `version` 指定工作流类型的版本。 ## @ExponentialRetry 在活动或异步方法上使用时，设置该方法引发未处理异常时的指数重试策略。在退避期之后进行重试尝试，退避期通过尝试次数的幂进行计算。 可对此注释指定以下参数： `intialRetryIntervalSeconds` 指定在进行第一次重试尝试之前等待的持续时间。此值不应大于 `maximumRetryIntervalSeconds` 和 `retryExpirationSeconds`。 `maximumRetryIntervalSeconds` 指定重试尝试之间的最长持续时间。达到后，重试间隔的上限为此值。默认设置为 -1，这表示持续时间不受限制。 `retryExpirationSeconds` 指定在多长的持续时间之后，指数重试将停止。默认设置为 -1，这表示不会过期。 `backoffCoefficient` 指定用于计算重试间隔的系数。请参阅[指数重试策略](features-retry.md#features-retry-exponential)。 `maximumAttempts` 指定在多少次尝试之后，指数重试将停止。默认设置为 -1，这表示对重试尝试次数没有限制。 `exceptionsToRetry` 指定应触发重试的异常类型列表。这些类型的未处理异常不会进一步传播，将在计算的重试间隔后重试方法。默认情况下，此列表包含 `Throwable`。 `excludeExceptions` 指定不应触发重试的异常类型列表。将允许传播此类型的未处理异常。此列表默认为空。 ## @GetState 在使用 `@Workflow` 注释进行注释的接口中的方法上使用时，标识该方法用于检索最新工作流执行状态。在具有 `@Workflow` 注释的接口中最多可以有一个具有此注释的方法。具有此注释的方法不得使用任何参数，并且必须具有非 `void` 的返回类型。 ## @ManualActivityCompletion 此注释可在活动方法上用于指示在该方法返回时活动任务不应完成。活动任务不会自动完成，需要直接使用 Amazon SWF API 来手动完成。对于将活动任务委派给一些不是自动的或需要人为干预才能完成的外部系统的使用案例，这非常有用。 ## @Signal 在使用 `@Workflow` 注释进行注释的接口中的方法上使用时，标识可通过该接口声明的工作流类型的执行获得的信号。定义信号方法需要使用此注释。 可对此注释指定以下参数： `name` 指定信号名称的名称部分。如果未设置，将使用方法的名称。 ## @SkipRegistration 在使用 `@Workflow` 注释进行注释的接口上使用时，可用于指示该工作流类型不应在 Amazon SWF 注册。必须在使用 `@Workflow` 注释的接口上使用 `@WorkflowRegistrationOptions` 和 `@SkipRegistrationOptions` 注释之一，但不能同时使用这两个注释。 ## @Wait 和 @ NoWait 这些注解可以用在类型的参数上，`Promise<>`以指示 for AWS Flow Framework Java 是否应等待其准备就绪后再执行该方法。默认情况下，传递给 `@Asynchronous` 方法的 `Promise<>` 参数必须已准备就绪，然后方法才能执行。在某些情况下，有必要覆盖此默认行为。传递到 `@Asynchronous` 方法且使用 `@NoWait` 注释的 `Promise<>` 参数不等待。 必须使用 `@Wait` 注释来注释包含 Promise 的参数 (或其子类) 的集合，如 `List>`。默认情况下，框架不等待集合的成员。 ## @工作流 此注释在接口上用于声明*工作流* 类型。使用此注释修饰的接口应包含一个使用 [@Execute](#annotations-execute) 注释修饰的方法来声明您的工作流的入口点。 **注意** 接口不能同时声明 `@Workflow` 和 `@Activities` 注释；它们相互排斥。 可对此注释指定以下参数： `dataConverter` 指定在将请求发送给此工作流类型的工作流执行并从其接收结果时要使用哪个 `DataConverter`。 反过来`NullDataConverter`，默认设置为`JsonDataConverter`将所有请求和响应数据作为 JavaScript对象表示法 (JSON) 进行处理。 ### 示例 ``` import com.amazonaws.services.simpleworkflow.flow.annotations.Execute; import com.amazonaws.services.simpleworkflow.flow.annotations.Workflow; import com.amazonaws.services.simpleworkflow.flow.annotations.WorkflowRegistrationOptions; @Workflow @WorkflowRegistrationOptions(defaultExecutionStartToCloseTimeoutSeconds = 3600) public interface GreeterWorkflow { @Execute(version = "1.0") public void greet(); } ``` ## @WorkflowRegistrationOptions 在使用 `@Workflow` 进行注释的接口上使用时，可用于提供 Amazon SWF 在注册工作流类型时使用的默认设置。 **注意** 必须在使用 `@Workflow` 进行注释的接口上使用 `@WorkflowRegistrationOptions` 或 `@SkipRegistrationOptions`，但不能同时指定这两个。 可对此注释指定以下参数： 描述 工作流类型的可选文本描述。 `defaultExecutionStartToCloseTimeoutSeconds` 指定此工作流类型向 Amazon SWF 注册的 `defaultExecutionStartToCloseTimeout`。这是此类型的工作流执行完成所需的总时间。 有关工作流超时的更多信息，请参阅 [Amazon SWF 超时类型](swf-timeout-types.md)。 `defaultTaskStartToCloseTimeoutSeconds` 指定此工作流类型向 Amazon SWF 注册的 `defaultTaskStartToCloseTimeout`。这指定此类型的工作流执行的一个决策任务完成所需的时间。 如果您没有指定 `defaultTaskStartToCloseTimeout`，则默认为 30 秒。 有关工作流超时的更多信息，请参阅 [Amazon SWF 超时类型](swf-timeout-types.md)。 `defaultTaskList` 用于此工作流类型的执行的决策任务的默认任务列表。在启动工作流执行时，可以使用 `StartWorkflowOptions` 覆盖此处设置的默认值。 如果您没有指定 `defaultTaskList`，则默认设置为 `USE_WORKER_TASK_LIST`。这指示应使用执行工作流注册的工作线程所使用的任务列表。 `defaultChildPolicy` 指定在此类型的执行终止时用于子工作流的策略。默认值为 `ABANDON`。可能的值包括： + `ABANDON` – 允许子工作流执行保持运行 + `TERMINATE` – 终止子工作流执行 + `REQUEST_CANCEL` – 请求取消子工作流执行 # AWS Flow Framework 对于 Java 异常 在 Java 中使用 AWS Flow Framework 了以下异常。本章提供异常的概述。有关更多详细信息，请参阅各个异常的 适用于 Java 的 AWS SDK 文档。 **Topics** + [ActivityFailureException](#errorhandling.exceptions.ActivityFailureException) + [ActivityTaskException](#errorhandling.exceptions.ActivityTaskException) + [ActivityTaskFailedException](#errorhandling.exceptions.ActivityTaskFailedException) + [ActivityTaskTimedOutException](#errorhandling.exceptions.ActivityTaskTimedOutException) + [ChildWorkflowException](#errorhandling.exceptions.ChildWorkflowException) + [ChildWorkflowFailedException](#errorhandling.exceptions.ChildWorkflowFailedException) + [ChildWorkflowTerminatedException](#errorhandling.exceptions.ChildWorkflowTerminatedException) + [ChildWorkflowTimedOutException](#errorhandling.exceptions.ChildWorkflowTimedOutException) + [DataConverterException](#errorhandling.exceptions.DataConverterException) + [DecisionException](#errorhandling.exceptions.DecisionException) + [ScheduleActivityTaskFailedException](#errorhandling.exceptions.ScheduleActivityTaskFailedException) + [SignalExternalWorkflowException](#errorhandling.exceptions.SignalExternalWorkflowException) + [StartChildWorkflowFailedException](#errorhandling.exceptions.StartChildWorkflowFailedException) + [StartTimerFailedException](#errorhandling.exceptions.StartTimerFailedException) + [TimerException](#errorhandling.exceptions.TimerException) + [WorkflowException](#errorhandling.exceptions.WorkflowException) ## ActivityFailureException 框架在内部使用此异常来沟通活动故障。当活动因未处理的异常而失败时，它将被封装在 `ActivityFailureException` 中并报告给 Amazon SWF。仅当您使用活动工作线程扩展性点时，才需要处理此异常。您的应用程序代码将从来不需要处理此异常。 ## ActivityTaskException 这是用于以下活动任务失败异常的基类：`ScheduleActivityTaskFailedException`、`ActivityTaskFailedException`、`ActivityTaskTimedoutException`。它包含失败任务的任务 ID 和活动类型。您可以在工作流实现中捕获此异常，以常规方式处理活动故障。 ## ActivityTaskFailedException 在活动中未处理的异常将通过引发 `ActivityTaskFailedException` 报告回工作流实现。原始异常可从此异常的原因属性中检索。此异常还可提供对调试有用的其他信息，如历史记录中的唯一活动标识符。 架构可以通过从活动工作线程中序列化原始异常来提供远程异常。 ## ActivityTaskTimedOutException 如果活动超时，Amazon SWF 会引发此异常。如果活动任务无法在要求的时间段内分配给工作线程或在要求时间内无法由工作线程完成，则会出现此异常。您可以在调用活动方法时使用 `@ActivityRegistrationOptions` 注释或使用 `ActivitySchedulingOptions` 参数来为活动设置这些超时。 ## ChildWorkflowException 用于报告子工作流执行故障的异常的基类。该异常包含子工作流执行的 ID 及其工作流类型。您可以捕获此异常，以常规方式处理子工作流执行故障。 ## ChildWorkflowFailedException 子工作流中未处理的异常将通过引发 `ChildWorkflowFailedException` 报告回父工作流实现。原始异常可从此异常的 `cause` 属性中检索。该异常还可提供对调试有用的其他信息，如子执行的唯一标识符。 ## ChildWorkflowTerminatedException 此异常在父工作流执行中引发，以报告子工作流执行的终止。如果要处理子工作流的终止，例如执行清除或补偿，则应捕获此异常。 ## ChildWorkflowTimedOutException 此异常在父工作流执行中引发，用于报告子工作流执行超时并被由 Amazon SWF 关闭。如果要处理子工作流的强制关闭，例如执行清除或补偿，则应捕获此异常。 ## DataConverterException 架构使用 `DataConverter` 组件来封送和拆收通过线路发送的数据。如果 `DataConverter` 无法封送或拆收数据，将引发此异常。可能由于各种原因而出现这种情况，例如，因为用于封送和拆收数据的 `DataConverter` 组件中存在不匹配。 ## DecisionException 这一异常基类表示 Amazon SWF 执行决策失败。您可以捕获此异常，以常规方式处理此类异常。 ## ScheduleActivityTaskFailedException 如果 Amazon SWF 未能安排活动任务，将引发此异常。出现这种情况可能有多种原因，例如，活动被弃用，或您的账户已达到 Amazon SWF 的限制。异常中的 `failureCause` 属性指明了计划活动失败的确切原因。 ## SignalExternalWorkflowException 如果 Amazon SWF 无法处理某工作流执行向其他工作流执行发出的请求，将引发此异常。如果找不到目标工作流执行，也就是说，您指定的工作流执行不存在或处于关闭状态，将出现这种情况。 ## StartChildWorkflowFailedException 如果 Amazon SWF 未能启动子工作流执行，将引发此异常。出现这种情况可能有多种原因，例如，指定的子工作流类型被弃用或您的账户已达到 Amazon SWF 的限制。异常中的 `failureCause` 属性指明无法启动子工作流执行的确切原因。 ## StartTimerFailedException 如果 Amazon SWF 未能启动工作流执行请求的计时器，将引发此异常。如果指定计时器 ID 已在使用中或您的账户已达到 Amazon SWF 的限制，就可能会出现此情况。异常中的 `failureCause` 属性指明了故障的确切原因。 ## TimerException 这是与计时器相关的异常的基类。 ## WorkflowException 框架在内部使用此异常来报告工作流执行中的故障。仅当您使用工作流工作线程扩展性点时，才需要处理此异常。 # AWS Flow Framework 适用于 Java 软件包 本节概述了 for Java 中包含 AWS Flow Framework 的软件包。有关每个软件包的更多信息，请参阅 [适用于 Java 的 AWS SDK API Reference](https://docs.aws.amazon.com/sdk-for-java/latest/reference/) 中的 com.amazonaws.services.simpleworkflow.flow。 [com.amazonaws.services.simpleworkflow.flow](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/package-summary.html) 包含与 Amazon SWF 集成的组件。 [com.amazonaws.services.simpleworkflow.flow.annotations](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/annotations/package-summary.html) 包含用于 Java 编程模型 AWS Flow Framework 的注解。 [com.amazonaws.services.simpleworkflow.flow.aspectj](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/aspectj/package-summary.html) 包含 AWS Flow Framework 和等[@异步](annotations.md#annotations-asynchronous)功能所需的 Java 组件[@ExponentialRetry](annotations.md#annotations-exponentialretry)。 [com.amazonaws.services.simpleworkflow.flow.common](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/common/package-summary.html) 包含常见实用工具，例如框架定义的常量。 [com.amazonaws.services.simpleworkflow.flow.core](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/core/package-summary.html) 包含核心功能，例如 `Task` 和 `Promise`。 [com.amazonaws.services.simpleworkflow.flow.generic](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/generic/package-summary.html) 包含作为其他功能的构建基础的核心组件，例如通用客户端。 [com.amazonaws.services.simpleworkflow.flow.interceptors](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/interceptors/package-summary.html) 包含框架提供的修饰器 (包括 `RetryDecorator`) 的实施。 [com.amazonaws.services.simpleworkflow.flow.junit](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/junit/package-summary.html) 包含提供 Junit 集成的组件。 [com.amazonaws.services.simpleworkflow.flow.pojo](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/pojo/package-summary.html) 包含为基于注释的编程模型实施活动和工作流程定义的类。 [com.amazonaws.services.simpleworkflow.flow.spring](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/spring/package-summary.html) 包含提供 Spring 集成的组件。 [com.amazonaws.services.simpleworkflow.flow.test](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/test/package-summary.html) 包含用于单元测试工作流程实施的帮助程序类，例如 `TestWorkflowClock`。 [com.amazonaws.services.simpleworkflow.flow.worker](https://docs.aws.amazon.com//AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/worker/package-summary.html) 包含活动和工作流程工作线程的实施。