Class EfsActivator

java.lang.Object
org.efs.activator.EfsActivator
@ThreadSafe public final class EfsActivator extends Object
EfsActivator is responsible for starting, enabling, disabling, and stopping agents according to a given Workflow.

An activator may be created either programmatically using EfsActivator.Builder or by loading a typesafe configuration from a file.

Please see org.efs.activator package documentation for a detailed description on how to use EfsActivator.

EfsActivator is thread-safe but can only process a single workflow at a time. That workflow must be either run to completion or terminated prior to initiating another workflow.

That said, this API does not preclude the user from building multiple EfsActivator instances and processing multiple workflows in parallel - which is thread unsafe. It is recommended that an application create a single activator and use that to process all workflows.

Author:
Charles W. Rapp
See Also:

  • Field Details

    • INVALID_WORKFLOW_NAME

      public static final String INVALID_WORKFLOW_NAME
      IllegalArgumentException message when an invalid workflow name is provided is "workflowName is either null or an empty string".
      See Also:

    • NO_WORKFLOW_IN_PROGRESS

      public static final String NO_WORKFLOW_IN_PROGRESS
      IllegalStateException message when execution is called but there is not workflow in progress (""no workflow in-progress"").
      See Also:

    • NULL_AGENT

      public static final String NULL_AGENT
      NullPointerException message for a null agent is "agent is null".
      See Also:

    • UNREGISTERED_AGENT

      public static final String UNREGISTERED_AGENT
      IllegalStateException message for an agent not registered with a dispatcher is "agent not registered with dispatcher".
      See Also:

    • NULL_CALLBACK

      public static final String NULL_CALLBACK
      NullPointerException message for a null callback is "callback is null".
      See Also:

    • STAND_ALONE_STEP

      public static final String STAND_ALONE_STEP
      Stand-alone executed steps are named "standalone-step".
      See Also:

    • INVALID_AGENT_NAME

      public static final String INVALID_AGENT_NAME
      IllegalArgumentException message when an invalid agent name is provided is "agent name is either null, an empty string, or blank".
      See Also:

  • Method Details

    • workflow

      public String workflow()
      Returns current, in-progress workflow name. If there is no workflow in progress, then returns NO_WORKFLOW_IN_PROGRESS.
      Returns:
      name of workflow currently in-progress.

    • isInProgress

      public boolean isInProgress()
      Returns true if there is a workflow activation in progress and false otherwise.
      Returns:
      true if a workflow activation is in progress.

    • agentState

      @Nullable public EfsAgentState agentState(String agentName)
      Returns named agent's current state.
      Parameters:
      agentName - agent's unique name.
      Returns:
      agent's current state or null if there is no activation agent with given agent name.
      Throws:
      IllegalArgumentException - if agentName is either null, an empty string, or blank.

    • isRegisteredListener

      public boolean isRegisteredListener(IEfsAgent agent)
      Returns true if agent is a registered activator listener and false otherwise.
      Parameters:
      agent - check if this agent is registered as an activator listener.
      Returns:
      true if agent is a registered activator listener.

    • initializeWorkflow

      public void initializeWorkflow(@Nonnull String workflowName)
      Sets workflow to be executed. This method must be successfully called prior to calling the following workflow execution methods:

      This activator may not have an in-progress workflow when attempting initialize a workflow. A workflow remains in-progress until either the workflow reaches completion or is terminated.

      Note: execute(String, EfsAgentState, EfsAgentState, Duration) may always be called whether a workflow is in progress or not.

      Parameters:
      workflowName - set in place this activator workflow.
      Throws:
      IllegalArgumentException - if workflowName is either null, an empty string, or does not reference a known workflow.
      IllegalStateException - if this activator already has an in-progress workflow.
      See Also:

    • setWorkflowStage

      public void setWorkflowStage(int stageIndex, int stepIndex)
      Sets workflow position to given stage and step index.

      This method forcibly sets workflow to a particular stage, step pair independently of workflow's current position. As such, this method should be used with caution since workflow may be set to an invalid state.

      Parameters:
      stageIndex - set current stage to this index.
      stepIndex - set current step within stage to this index.
      Throws:
      IllegalStateException - if there is no workflow in-progress.
      IndexOutOfBoundsException - if either stageIndex or stepIndex is out-of-bounds.

    • agentState

      public void agentState(@Nonnull String agentName, @Nonnull EfsAgentState state)
      Forcibly sets named agent's state. Use this method with care! This method should be used only when an activation step fails but it is determined that named agent is actually in the target state. Using this method indiscriminately will result in activator no longer able to correctly change an agent's state.
      Parameters:
      agentName - set this agent's state.
      state - agent's current state.
      Throws:
      NullPointerException - if state is null.
      IllegalArgumentException - if agentName is either null, an empty string, or does not reference a known agent.

    • terminateWorkflow

      public void terminateWorkflow()
      Terminates an in-progress workflow. No further executions are possible except execute(String, EfsAgentState, EfsAgentState, Duration).
      See Also:

    • registerListener

      public void registerListener(@Nonnull Consumer<ActivatorEvent> callback, @Nonnull IEfsAgent agent)
      Registers agent for listening to activator state changes. ActivatorEvents are delivered to agent via the given callback.

      Please note that an agent may only have one current registration. If you wish to change the activation event callback for a currently registered listener, then you may register again with a new callback and the previous callback will be quietly replaced. It is not necessary to de-register prior to registering the new callback.

      Parameters:
      callback - agent callback lambda.
      agent - agent listening to activator changes.
      Throws:
      NullPointerException - if either callback or agent is null.
      IllegalStateException - if agent is not registered with an EfsDispatcher.
      See Also:

    • deregisterListener

      public void deregisterListener(@Nonnull IEfsAgent agent)
      Retracts registered agent from activator state listening. Does nothing if agent is not currently registered.
      Parameters:
      agent - agent listening to activator changes.
      Throws:
      NullPointerException - if agent is null.
      See Also:

    • executeNextStep

      public boolean executeNextStep()
      Executes next step in workflow. Returns true if workflow is completed after successfully completing step.
      Returns:
      true if workflow is completed.
      Throws:
      IllegalStateException - if there is no activation in progress or the activation fails. Note: if activation step fails, agent remains in its initial state and the step is marked as ActivatorEvent.StepState.COMPLETED_FAILED. User may recover the workflow by either:

    • executeNextStage

      public boolean executeNextStage()
      Executes next stage in workflow. Returns true if workflow is completed after successfully completing stage.
      Returns:
      true if workflow is completed.
      Throws:
      IllegalStateException - if there is no activation in progress or the activation fails. Note: if activation step fails, agent remains in its initial state and the step is marked as ActivatorEvent.StepState.COMPLETED_FAILED. User may recover the workflow by either:

    • executeWorkflow

      public boolean executeWorkflow()
      Executes all remaining stages and steps in this workflow.
      Returns:
      true.
      Throws:
      IllegalStateException - if there is no activation in progress or the activation fails. Note: if activation step fails, agent remains in its initial state and the step is marked as ActivatorEvent.StepState.COMPLETED_FAILED. User may recover the workflow by either:

    • execute

      public void execute(@Nonnull String agentName, @Nonnull EfsAgentState beginState, @Nonnull EfsAgentState endState, @Nonnull Duration transitionTime)
      Executes a single explicit step on a given agent.

      This method may throw any number of RuntimeExceptions either due to the given parameters being invalid (name does not reference a known IEfsActivateAgent, begin and end states not being adjacent) or the step execution failing. You are advised to use a general Exception catch when calling this method.

      Parameters:
      agentName - unique agent name
      beginState - expected agent current state.
      endState - target agent state.
      transitionTime - time limit for state transition.
      Throws:
      IllegalStateException - if activation fails.

    • builder

      public static EfsActivator.Builder builder()
      Returns a new Builder instance.
      Returns:
      new Builder instance.

    • loadActivator

      public static EfsActivator loadActivator(String fileName)
      Returns activator based on configuration loaded from given file name.
      Parameters:
      fileName - name of file containing efs activator definition.
      Returns:
      activator loaded from configuration file.
      Throws:
      IllegalArgumentException - if:
      • fileName is a non-existent file,
      • fileName is not a regular file,
      • fileName cannot be read.
      com.typesafe.config.ConfigException - if fileName contain an invalid efs activator configuration.