Interface RunLevelController

  • All Known Implementing Classes:
    RunLevelControllerImpl

    @Contract
    public interface RunLevelController
    A RunLevelContoller controls the current state of services registered in the RunLevel scope. All services annotated with a RunLevel equal to or less than the current level of the system will be started. All services annotated with a RunLevel higher than the current level of the system will not be started. This service can be used to change the current level of the system.

    Whether or not separate threads are used by the RunLevelController is a policy set by the caller. By default the RunLevelController will use as many threads as there are services to be started at a particular level. So if your system has possibly hundreds of services at some level, you will probably want to set your maximum number of threads to some reasonable number. You can also change your threading policy to USE_NO_THREADS, in which case the RunLevelController will not spawn any threads at all, but will instead use the thread of the caller to perform all work. In this mode the Async API will throw an exception.

    The RunLevelController starts at level -2. The reasoning behind this is to allow two "immediate" levels. The first thing a system might do is proceed to level 0 (running all services at level -1 and 0). Thereafter the system may go up and down in levels, never going below zero. Note this is only a convention, and individual systems can choose other meanings for the levels -1 and 0.

    • Method Detail

      • proceedToAsync

        RunLevelFuture proceedToAsync​(int runLevel)
                               throws CurrentlyRunningException,
                                      java.lang.IllegalStateException
        Causes this RunLevelController to move to the specified run level for all RunLevel instances, orchestrating the appropriate lifecycle events.

        If the run level specified is the same as the current run level then the RunLevelController may return immediately

        Parameters:
        runLevel - the run level to move to
        Returns:
        The future that can be used to wait for this object
        Throws:
        CurrentlyRunningException - if there is currently a job running this exception will be thrown with the currently running job
        java.lang.IllegalStateException - if this method is called when the USE_NO_THREADS policy is in effect
      • getCurrentProceeding

        RunLevelFuture getCurrentProceeding()
        This method will return the current proceedTo that the RunLevelController is working on, or it will return null if the controller is not currently moving up or down
        Returns:
        the current job the run level controller is working on or null if the system is not currently in flight
      • cancel

        void cancel()
        If there is a current procedure in process this method will get it and cancel it
      • getCurrentRunLevel

        int getCurrentRunLevel()
        The current run level state. This represents the last run level successfully achieved by the underlying RunLevelController responsible for this scope.
        Returns:
        the current run level, or null if no run level has been been achieved
      • setMaximumUseableThreads

        void setMaximumUseableThreads​(int maximumThreads)
        This sets the maximum number of threads that the system can create for creation and/or destruction of threads. This number must be one or greater
        Parameters:
        maximumThreads - The maximum number of threads that can be used by the system for creation or destruction of services
      • getMaximumUseableThreads

        int getMaximumUseableThreads()
        Returns the current number of maximum useable threads
        Returns:
        the current number of maximum useable threads
      • setThreadingPolicy

        void setThreadingPolicy​(RunLevelController.ThreadingPolicy policy)
        Sets the threading policy that will be used by this controller. The values can be:
        1. FULLY_THREADED: Use maximumUseableThreads to complete any task
        2. USE_NO_THREADS: Never create a thread, use the callers thread always
        Parameters:
        policy - The policy that should be used by this controller
      • getThreadingPolicy

        RunLevelController.ThreadingPolicy getThreadingPolicy()
        Returns the threading policy currently being used by this controller
        Returns:
        The threading policy currently in use with this controller
      • setExecutor

        void setExecutor​(java.util.concurrent.Executor executor)
        Sets the executor to use for the next job. This value will be used even if the policy is USE_NO_THREADS in order to support canceling hung threads
        Parameters:
        executor - The executor to use for the next job. If null a default executor will be used
      • getExecutor

        java.util.concurrent.Executor getExecutor()
        Gets the executor that will be used by the system when executing tasks. This value will be used even if the policy is USE_NO_THREADS in order to support canceling hung threads
        Returns:
        The currently installed executor. Will not return null (the default executor implementation will be returned if the user has not supplied an executor)
      • getCancelTimeoutMilliseconds

        long getCancelTimeoutMilliseconds()
        Returns the amount of time in milliseconds the run level service will wait after a cancel call before orphaning services that have not yet completed execution
        Returns:
        The amount of time in milliseconds that cancel will wait for running services
      • setCancelTimeoutMilliseconds

        void setCancelTimeoutMilliseconds​(long cancelTimeout)
        Sets the amount of time in milliseconds the run level service will wait after a cancel call before orphaning services that have not yet completed execution

        The default value is 5000 (5 seconds). In general this value should be set to be longer than than the running time of the longest service that may be cancelled

        Parameters:
        cancelTimeout - The amount of time in milliseconds that cancel will wait for running services. Must be greater than 0
      • getValidationOverride

        java.lang.Integer getValidationOverride()
        Returns the override value for the RunLevel.mode() field in RunLevel services. If this value is non-null then the mode will be forced to this value. This is useful in testing scenarios where the test would like to instantiate a run-level service without having to instantiate all the others at a certain level
        Returns:
        null if there is no override or the value that the RunLevel.mode() value should be
      • setValidationOverride

        void setValidationOverride​(java.lang.Integer validationMode)
        Sets the override value for the RunLevel.mode() field in RunLevel services. If this value is non-null then the mode will be forced to this value. This is useful in testing scenarios where the test would like to instantiate a run-level service without having to instantiate all the others at a certain level
        Parameters:
        validationMode - null if there is no override or the value that the RunLevel.mode() value should be