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.

Author:
Charles W. Rapp
See Also:

  • Field Details

    • 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:

    • 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:

  • 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.

    • agentState

      public EfsAgentState agentState(String agentName)
      Returns named agent's current state.
      Parameters:
      agentName - agent's unique name.
      Returns:
      agent's current state.
      Throws:
      IllegalStateException - if agentName either references an un-registered agent or the agent does not implement IEfsActivateAgent.

    • 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(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.

      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.
      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(String agentName, 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(Consumer<ActivatorEvent> callback, 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 the agent is de-registered, then it may register again.

      Parameters:
      callback - agent callback lambda.
      agent - agent listening to activator changes.
      Throws:
      NullPointerException - if either calback or agent is null.
      IllegalStateException - if agent is already registered.
      See Also:

    • deregisterListener

      public void deregisterListener(Consumer<ActivatorEvent> callback, IEfsAgent agent)
      Retracts registered agent from activator state listening. Does nothing if agent is not currently registered.
      Parameters:
      callback - agent callback lambda.
      agent - agent listening to activator changes.
      Throws:
      NullPointerException - if either calback or 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.

    • 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.

    • 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.

    • execute

      public void execute(String agentName, EfsAgentState beginState, EfsAgentState endState, 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:
      com.typesafe.config.ConfigException - if fileName contain an invalid efs activator configuration.